94 lines
2.8 KiB
Markdown
94 lines
2.8 KiB
Markdown
# 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。
|
||
- 文档中的请求示例表示字段形状，不代表所有字段都必须传入；校验规则仍以服务实现为准。
|
||
|