2026-08-11 19:09:29 +08:00
|
|
|
|
# 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
|
2026-08-12 11:46:48 +08:00
|
|
|
|
Authorization: <JWT>
|
2026-08-11 19:09:29 +08:00
|
|
|
|
Content-Type: application/json
|
|
|
|
|
|
|
|
|
|
|
|
{"account":"demo","password":"secret"}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 动态 RPC 响应
|
|
|
|
|
|
|
|
|
|
|
|
动态 RPC 无论成功或失败均返回 HTTP 200，客户端必须判断 `code`。
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"code": 0,
|
|
|
|
|
|
"message": "OK",
|
|
|
|
|
|
"data": {}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
错误示例：
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
2026-08-12 11:46:48 +08:00
|
|
|
|
"code": 3,
|
|
|
|
|
|
"message": "invalid protobuf JSON: ...",
|
2026-08-11 19:09:29 +08:00
|
|
|
|
"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
|
2026-08-12 11:46:48 +08:00
|
|
|
|
Authorization: <JWT>
|
2026-08-11 19:09:29 +08:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-12 11:46:48 +08:00
|
|
|
|
请求头直接传递 JWT，不添加 `Bearer` 前缀。`all` 使用 `Authorization.Key` 验证 HS256 签名，并根据 token 的 `exp` 与 `Authorization.Expire` 校验有效期；是否匿名由 `Authorization.Anonymous` 配置决定。
|
2026-08-11 19:09:29 +08:00
|
|
|
|
|
|
|
|
|
|
## 当前限制与风险
|
|
|
|
|
|
|
|
|
|
|
|
- 动态 HTTP 仅支持 unary RPC，不支持 client/server/bidirectional streaming。
|
|
|
|
|
|
- social/feed、group、relation 的公共 proto 都使用 `blocks` package，并存在 descriptor 同名冲突。客户端应按模块分别生成 SDK，暂时不要把三个模块的生成代码链接进同一 protobuf 全局 registry。
|
|
|
|
|
|
- 文档中的请求示例表示字段形状，不代表所有字段都必须传入；校验规则仍以服务实现为准。
|
|
|
|
|
|
|
