# Micro API
micro api是微服務的API網關。使用API[網關模式](http://microservices.io/patterns/apigateway.html)為您的服務提供一個入口點。 micro api提供HTTP并動態路由到適當的后端服務。

## 如何工作的
micro api構建在go-micro上,利用它進行服務發現,負載平衡,編碼和基于RPC的通信。對API的請求通過HTTP提供,并通過RPC進行內部路由。
由于micro api在內部使用go-micro,因此它也支持插件,因此可以隨時切換為kubernetes api的consul服務發現或gRPC的RPC。
## API
micro api提供了以下HTTP API
```
- /[service]/[method] # HTTP paths are dynamically mapped to services
- /rpc # Explicitly call a backend service by name and method
```
見下面的例子
## Handler
Handler是管理請求路由的HTTP處理程序。
默認Handler使用注冊表中的端口元數據來確定服務路由。如果未找到所匹配的路由,它將回退到API處理程序。您可以使用[go-api](https://github.com/micro/go-api)配置注冊路由。
該API有三種可配置的請求Handler。
1. API Handler:`/[service]/[method]`
- 請求/響應:`api.Request/api.Response`
- 該路徑用于解析服務和方法
- 請求通過API服務處理,API服務采用請求`api.Request`和響應`api.Response`類型
- 請求/響應的定義可以在[go-api/proto](https://github.com/micro/go-api/blob/master/proto/api.proto)中找到
- 請求/響應主體的內容類型可以是任何東西
- 路由不可用的默認回退處理程序
- 通過`--handler=api`設置
2. RPC Handler:`/[service]/[method]`
- 請求/響應:`json/protobuf`
- 使用go-micro客戶端將請求主體轉發為RPC請求的默認處理程序的替代方案
- 允許使用具體的Go類型定義API處理程序。
- 在不需要完全控制標題或請求/響應的情況下很有用
- 可以用來運行單層后端服務,而不是其他API服務
- 支持的內容類型`application/json`和`application/protobuf`
- 通過`--handler=rpc`設置
3. 反向代理:`/[service]`
- 請求/響應:http
- 該請求經過反向代理到服務的路徑的第一個處理
- 這允許REST在API后面實現
- 通過`--handler=proxy`設置
4. Event Handler:`/[topic]/[event]`
- 異步處理程序向消息代理發布請求作為事件
- 請求被格式化為[go-api/proto.Event](https://github.com/micro/go-api/blob/master/proto/api.proto#L28L39)
- 通過`--handler=event`進行設置
或者,使用`/rpc`端口直接與任何服務通話 - 期望參數:`service`,`method`,`request`,可選接受`address`,以指定特定主機。
```
curl -d 'service=go.micro.srv.greeter' \
-d 'method=Say.Hello' \
-d 'request={"name": "Bob"}' \
http://localhost:8080/rpc
```
在[github.com/micro/examples/api](https://github.com/micro/examples/tree/master/api)中查找工作示例。
### API Handler 請求/響應原型
API Handler是一個默認處理原型,服務也是基于該原型使用特定的請求和響應處理,可在[go-api/proto](https://github.com/micro/go-api/blob/master/proto/api.proto)中獲得。這允許micro api將HTTP請求解析為RPC并返回到HTTP。
## 入門
### 安裝
```
go get github.com/micro/micro
```
### 運行
```
micro api
```
### 通過ACME加密
通過使用letsencrypt的ACME,提供默認安全服務
```
micro --enable_acme api
```
可以指定一個主機白名單
```
micro --enable_acme --acme_hosts=example.com,api.example.com api
```
### 提供安全的TLS
該API支持使用TLS證書安全地提供服務
```
micro --enable_tls --tls_cert_file=/path/to/cert --tls_key_file=/path/to/key api
```
### 設置命名空間
該API默認為服務名稱空間`go.micro.api`。命名空間和請求路徑的組合用于解析發送查詢的API服務和方法。
```
micro api --namespace=com.example.api
```
## 例子
這里我們有一個3層架構的例子
- micro api(localhost:8080) - 作為http入口點
- api服務(go.micro.api.greeter) - 為面向公眾提供服務
- 后端服務(go.micro.srv.greeter) - 內部范圍服務
完整的工作示例在[這里](https://github.com/micro/examples/tree/master/greeter)
### 運行示例
先決條件:確保您正在運行服務發現,例如consul agent -dev
獲取示例
```
git clone https://github.com/micro/examples
```
啟動服務go.micro.srv.greeter
```
go run examples/greeter/srv/main.go
```
啟動API服務go.micro.api.greeter
```
go run examples/greeter/api/api.go
```
開始 Micro API
```
micro api
```
### 查詢
通過micro API進行HTTP調用
```
curl "http://localhost:8080/greeter/say/hello?name=Asim+Aslam"
```
HTTP `path/greeter/say/hello` 映射到服務 `go.micro.api.greeter` 方法`Say.Hello`
繞過api服務并通過`/rpc`直接調用后端
```
curl -d 'service=go.micro.srv.greeter' \
-d 'method=Say.Hello' \
-d 'request={"name": "Asim Aslam"}' \
http://localhost:8080/rpc
```
與JSON完全相同的調用
```
$ curl -H 'Content-Type: application/json' \
-d '{"service": "go.micro.srv.greeter", "method": "Say.Hello", "request": {"name": "Asim Aslam"}}' \
http://localhost:8080/rpc
```
## 請求映射
Micro使用固定的命名空間和HTTP路徑動態地路由到服務。
這些服務的默認命名空間是`go.micro.api`,但可以通過`--namespace`標志設置命名空間。
### 每個服務的API
我們提倡為面向公眾的流量創建每個后端服務的API服務模式。這在邏輯上將服務API前端和后端服務的分開。
### RPC映射
URLs映射如下:
|Path|Service|Method|
|----|----|----|
|/foo/bar |go.micro.api.foo |Foo.Bar|
|/foo/bar/baz |go.micro.api.foo |Bar.Baz|
|/foo/bar/baz/cat|go.micro.api.foo.bar |Baz.Cat|
版本化的API URL可以很容易地映射到服務名稱:
|Path|Service|Method|
|----|----|----|
|/foo/bar |go.micro.api.foo |Foo.Bar|
|/v1/foo/bar |go.micro.api.v1.foo|Foo.Bar|
|/v1/foo/bar/baz|go.micro.api.v1.foo|Bar.Baz|
|/v2/foo/bar |go.micro.api.v2.foo|Foo.Bar|
|/v2/foo/bar/baz|go.micro.api.v2.foo|Bar.Baz|
### REST映射
您可以使用API作為反向代理并使用諸如[go-restful](https://github.com/emicklei/go-restful)之類的庫實現RESTful路徑,從而為RESTful API提供服務。REST API服務的一個例子可以在[greeter/api/rest](https://github.com/micro/examples/tree/master/greeter/api/rest)找到。
使用`--handler=proxy`運行micro API會將代理請求反轉為API名稱空間內的服務。
|Path|Service|Service Path|
|----|----|----|
|/foo/bar |go.micro.api.foo |/foo/bar|
|/greeter |go.micro.api.greeter|/greeter|
|/greeter/:name|go.micro.api.greeter|/greeter/:name|
使用這個處理程序意味著直接與后端服務通話,忽略任何go-micro傳輸插件。
## 統計儀表板
通過`--enable_stats`標志啟用統計信息顯示板。它將暴露在`/stats`上。
```
micro --enable_stats api
```
