> For the complete documentation index, see [llms.txt](https://lixiangyun.gitbook.io/go-micro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lixiangyun.gitbook.io/go-micro/components/api.md).

# API

micro api是微服务的API网关。使用API[网关模式](http://microservices.io/patterns/apigateway.html)为您的服务提供一个入口点。 micro api提供HTTP并动态路由到适当的后端服务。

![](/files/-LlaUE7sPyF9WfmxBx8H)

## 如何工作的

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
```

![](/files/-LlaUE844JjY8SyDlcOP)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lixiangyun.gitbook.io/go-micro/components/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.