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 接口

示例：

POST /rpc/passport/Login/Pwd
Authorization: <JWT>
Content-Type: application/json

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

动态 RPC 响应

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

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

错误示例：

{
  "code": 3,
  "message": "invalid protobuf JSON: ...",
  "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

鉴权说明

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

Authorization: <JWT>

请求头直接传递 JWT，不添加 Bearer 前缀。all 使用 Authorization.Key 验证 HS256 签名，并根据 token 的 exp 与 Authorization.Expire 校验有效期；是否匿名由 Authorization.Anonymous 配置决定。

当前限制与风险

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

2.6 KiB Raw Blame History Unescape Escape