API

Micro的api就是api網關

• 概覽
• 安裝
• 運行
• 使用ACME協議
• 設置TLS證書
• 設置命名空間
• 示例
  • 運行示例
  • 查詢
• API
• Handlers
  • API Handler
  • RPC Handler
  • Proxy Handler
  • Event Handler
  • Web Handler
  • RPC endpoint
• Resolver
  • RPC Resolver
  • Proxy Resolver

API參考了API網關模式為服務提供了一個單一的公共入口。基于服務發現，使得micro api可以提供具備http及動態路由的服務。

image

概覽

Micro的API基于HTTP協議。請求的API接口通過HTTP協議訪問，并且路由是基于服務發現機制向下轉發的。 Micro API在 go-micro之上開發，所以它集成了服務發現、負載均衡、編碼及基于RPC的通信。

因為micro api內部使用了go-micro，所以它自身也是可插拔的。 參考go-plugins了解對gRPC、kubernetes、etcd、nats、及rabbitmq等支持。另外，api也使用了go-api，這樣，接口handler也是可以配置的。

安裝

go get -u github.com/micro/micro

運行

# 默認的端口是8080
micro api

使用ACME協議

ACME（ Automatic Certificate Management Environment）是由Let’s Encrypt制定的安全協議。

MICRO_ENABLE_ACME=true micro api

可以選擇是否配置白名單

MICRO_ENABLE_ACME=true \
MICRO_ACME_HOSTS=example.com,api.example.com \
micro api

設置TLS證書

API服務支持TLS證書

MICRO_ENABLE_TLS=true \
MICRO_TLS_CERT_FILE=/path/to/cert \
MICRO_TLS_KEY_FILE=/path/to/key \
micro api

設置命名空間

API使用帶分隔符的命名空間來在邏輯上區分后臺服務及公開的服務。命名空間及http請求路徑會用于解析服務名與方法，比如GET /foo HTTP/1.1會被路由到go.micro.api.foo服務上。

API默認的命名空間是go.micro.api，當然，也可以修改：

MICRO_NAMESPACE=com.example.api micro api

示例

我們演示一個3層的服務架構：

• micro api: (localhost:8080) - http訪問入口
• api service: (go.micro.api.greeter) - 對外暴露的API服務
• backend service: (go.micro.srv.greeter) - 內網的后臺服務

完整示例可以參考：examples/greeter

運行示例

先決條件：我們使用Consul作為默認的服務發現，所以請先確定它已經安裝好了，并且已經運行，比如執行consul agent -dev這樣子方式運行。

# 下載示例
git clone https://github.com/micro/examples

# 運行服務
go run examples/greeter/srv/main.go

# 運行api
go run examples/greeter/api/api.go

# 啟動micro api
micro api

查詢

向micro api發起http請求

curl "http://localhost:8080/greeter/say/hello?name=John"

HTTP請求的路徑/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": "John"}' \
     http://localhost:8080/rpc

使用JSON的方式執行同一請求：

curl -H 'Content-Type: application/json' \
     -d '{"service": "go.micro.srv.greeter", "method": "Say.Hello", "request": {"name": "John"}}' \
     http://localhost:8080/rpc

API

micro api提供下面類型的http api接口

- /[service]/[method]   # HTTP路徑式的會被動態地定位到服務上
- /rpc          # 顯式使用后臺服務與方法名直接調用

請看下面的例子

Handlers

Handler負責持有并管理HTTP請求路由。

默認的handler使用從注冊中心獲取的端口元數據來決定指向服務的路由，如果路由不匹配，就會回退到使用”rpc” hander。在注冊時，可以通過go-api來配置路由。

API有如下方法可以配置請求handler：

• api - 處理http請求，通過RPC來完全控制http的請求/響應。
• rpc - 處理json及protobuf格式的POST請求，并轉向RPC。
• proxy - 處理http請求并轉向反向代理。
• event - 處理任意的http請求并向消息總線分發消息。
• web - 包含web socket的http反向代理。

通過/rpc入口可以繞開handler處理器。

API Handler

API處理器接收任何的HTTP請求，并且向前轉發指定格式的RPC請求。

• Content-Type: 支持任何類型
• Body: 支持任何格式
• Forward Format: 轉發格式，api.Request/api.Response
• Path: 請求路徑，/[service]/[method]
• Resolver: 請求解析器，路徑會被解析成服務與方法
• Configure: 配置，在啟動時指定--handler=api或在啟動命令前指定環境變量MICRO_API_HANDLER=api

RPC Handler

RPC處理器接收json或protobuf格式的HTTP POST請求，然后向前轉成RPC請求。

• Content-Type: application/json or application/protobuf
• Body: JSON 或者 Protobuf
• Forward Format: json-rpc或者proto-rpc，與Content-Type有關
• Path: /[service]/[method]
• Resolver: 請求解析器，路徑會被解析成服務與方法
• Configure: 配置，在啟動時指定--handler=rpc或在啟動命令前指定環境變量MICRO_API_HANDLER=rpc
• 如果沒有設置時，RPC Handler就是默認的handler，

Proxy Handler

代理Handler其實是內置在服務發現中的反向代理服務。

• Content-Type: 支持任何類型
• Body: 支持任何格式
• Forward Format: HTTP反向代理
• Path: /[service]
• Resolver: 請求解析器，路徑會被解析成服務名
• Configure: 配置，在啟動時指定--handler=proxy或在啟動命令前指定環境變量MICRO_API_HANDLER=proxy
• REST can be implemented behind the API as microservices（不太好理解，待翻譯）

Event Handler

事件處理器使用go-micro的broker代理接收http請求并把請求作為消息傳到消息總線上。

• Content-Type: 支持任何類型
• Body: 支持任何格式
• Forward Format: 請求格式得是 go-api/proto.Event
• Path: 請求路徑，/[topic]/[event]
• Resolver: 請求解析器，路徑會被解析成topic（主題，相當于事件分類）與事件（event）名。
• Configure: 配置，在啟動時指定--handler=event或在啟動命令前指定環境變量MICRO_API_HANDLER=event

Web Handler

Web處理器是，它是內置在服務發現中的HTTP反向代理服務，支持web socket。

• Content-Type: 支持任何類型
• Body: 支持任何格式
• Forward Format: HTTP反向代理，包括web socket
• Path: /[service]
• Resolver: 請求解析器，路徑會被解析成服務名
• Configure: 配置，在啟動時指定--handler=web或在啟動命令前指定環境變量MICRO_API_HANDLER=web

RPC endpoint

/rpc端點允許繞過主handler，然后與任何服務直接會話。

• 請求參數
  • service - 指定服務名
  • method - 指定方法名
  • request - 請求body體
  • 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

Resolver

解析器，Micro使用命名空間與HTTP請求路徑來動態路由到具體的服務。

API命名的空間是go.micro.api。可以通過指令--namespace或者環境變量MICRO_NAMESPACE=設置命名空間。

下面說一下解析器是如何使用的：

RPC Resolver

RPC解析器示例中的RPC服務有名稱與方法，分別是go.micro.api.greeter，Greeter.Hello。

URL會被解析成以下幾部分：

帶版本號的API URL也可以很容易定位到具體的服務：

Proxy Resolver

代理解析器只處理服務名，所以處理方案和RPC解析器有點不太一樣。

URL會被解析成以下幾部分：