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会被解析成以下几部分：

路径	服务	方法
/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

Proxy Resolver

代理解析器只处理服务名，所以处理方案和RPC解析器有点不太一样。