# API 接入总览

本文档面向 Web、移动端和第三方客户端开发者。默认示例基于 `all` 聚合服务：gRPC 监听 `12000`，HTTP 监听 `12001`，实际地址以 `all/etc/<workspace>_<runtime>.yaml` 为准。

## 协议入口

| 类型 | 地址格式 | 说明 |
|---|---|---|
| 原生 gRPC | `/{package}.{Service}/{Method}` | 高性能内部调用，使用 protobuf 二进制协议 |
| 动态 HTTP RPC | `POST /rpc/{package}/{Service}/{Method}` | JSON 请求动态转换为 PB，再调用本机 gRPC；当前仅支持 unary |
| grpc-gateway | `POST /{package}.{Service}/{Method}` | 由各模块生成代码注册的兼容 HTTP 路由 |
| 原生 REST | `/rest/{module}/{path}` | FTS、Logs、MGT 的 Gin HTTP 接口 |

示例：

```http
POST /rpc/passport/Login/Pwd
Authorization: Bearer <token>
Content-Type: application/json

{"account":"demo","password":"secret"}
```

## 动态 RPC 响应

动态 RPC 无论成功或失败均返回 HTTP 200，客户端必须判断 `code`。

```json
{
  "code": 0,
  "message": "OK",
  "data": {}
}
```

错误示例：

```json
{
  "code": 7,
  "message": "dynamic RPC method is not allowed",
  "details": []
}
```

`code` 使用 gRPC status code：`0=OK`、`3=InvalidArgument`、`5=NotFound`、`7=PermissionDenied`、`16=Unauthenticated`。

## JSON 与 protobuf 规则

- 字段采用 protobuf JSON 名称，即生成 Go 字段的 `json_name`。
- `int64`、`uint64` 在 JSON 中建议使用字符串，避免 JavaScript 精度丢失。
- 枚举可传枚举名称；文档的枚举章节列出允许值。
- `bytes` 使用 Base64 字符串。
- 未知字段会被拒绝。
- 请求体最大 4 MiB；文件上传必须使用 FTS multipart 接口。

## Header 转发

动态 HTTP RPC 会向 gRPC metadata 转发：

- `Authorization`
- `X-Request-ID`
- 其他 `X-*` Header

## 鉴权说明

需要身份的接口统一发送：

```http
Authorization: Bearer <token>
```

具体方法是否允许匿名由服务实现和 gRPC interceptor 决定。客户端不应仅根据请求字段推断匿名权限。

## 动态 RPC 白名单

`all/etc/<workspace>_<runtime>.yaml` 的 `DynamicRPC.Allow` 控制可调用范围：

```yaml
DynamicRPC:
  Allow:
    - passport.Login.Pwd
    - passport.Register
```

支持完整方法名、完整服务名或 `*`。生产环境不建议使用 `*`。

## 当前限制与风险

- 动态 HTTP 仅支持 unary RPC，不支持 client/server/bidirectional streaming。
- social/feed、group、relation 的公共 proto 都使用 `blocks` package，并存在 descriptor 同名冲突。客户端应按模块分别生成 SDK，暂时不要把三个模块的生成代码链接进同一 protobuf 全局 registry。
- 文档中的请求示例表示字段形状，不代表所有字段都必须传入；校验规则仍以服务实现为准。