9.1 KiB
2.2 API 接口设计规范
API 是前后端、微服务之间沟通的核心契约。优秀的 API 设计不仅能大幅降低沟通成本，还能提升系统的稳定性和可维护性。一旦 API 契约对外发布，就必须保持向前兼容。
2.2.1 协议选型与设计原则
根据不同的业务场景，我们支持以下三种主要的接口协议，严禁在不恰当的场景滥用协议：
1. RESTful API (默认首选)
适用于绝大多数 Web 端、App 端的外部接口以及常规业务交互。
- 面向资源： URL 必须全部使用名词的复数形式，严禁在 URL 中包含动词（如 /get-users 是错误示范，应为 GET /users）。名词推荐使用短横线分隔（Kebab-case，如 /user-profiles）。
- HTTP 动词语义化：
- GET：查询资源，幂等，绝对不能产生副作用（如修改数据）。
- POST：创建新资源，非幂等。
- PUT：全量更新资源，幂等。
- PATCH：局部更新资源。
- DELETE：删除资源。
- 版本控制： API 必须具备版本号，推荐放在 URL 路径中（如 /api/v1/users），以便于后续重大重构时的平滑迁移。
- 务实原则： 追求“实用级” REST（Level 2），不强求满足极致的 HATEOAS（Level 3，返回一堆超链接），避免过度设计增加前端解析负担。
2. gRPC (内部微服务首选)
适用于后端微服务之间的高频、内部通信。
- 优势： 基于 HTTP/2 和 Protobuf，强类型约束，序列化体积小，性能远超 HTTP+JSON。
- 规约： 严禁将 gRPC 服务直接暴露给公网 Web/App 端（除非有特定的 API Gateway 或 gRPC-Web 转换层）。对外一律暴露 RESTful 或 GraphQL。
3. GraphQL (复杂聚合场景可选)
适用于 BFF（聚合层）或前端对数据灵活性要求极高、且存在严重“过度获取(Over-fetching)”或“获取不足(Under-fetching)”的复杂场景。
- 规约： 不要在简单的 CRUD 业务中引入 GraphQL，它会极大地增加后端的 N+1 查询优化难度和权限控制复杂度。必须在架构决策（ADR）中经过严格评审后方可使用。
2.2.2 统一的请求头 (Headers) 与鉴权机制
为了实现全链路追踪、多语言支持和统一的安全管控，所有 HTTP 请求必须遵循以下 Headers 规范：
1. 标准请求头列表
- Authorization: 鉴权 Token（必须）。格式为 Bearer <Token>。
- X-Request-Id (或 Trace-Id): 全链路追踪 ID。由网关或客户端生成，后端原样透传并在日志中打印，这是排查线上客诉的唯一生命线。
- X-Client-Type: 客户端类型（如 iOS, Android, Web, MiniProgram），用于后端进行渠道统计或特定逻辑下发。
- X-Client-Version: 客户端版本号（如 1.0.5），用于后端做兼容性控制。
- Accept-Language: 多语言标识（如 zh-CN, en-US），用于国际化错误提示。
2. 鉴权机制 (JWT)
- 系统默认采用 JWT (JSON Web Token) 进行无状态鉴权。
- 安全性底线：
- 严禁在 JWT 的 payload 中携带用户密码、敏感业务数据等隐私信息（JWT 仅防篡改，不防窃听，前端可直接 Decode）。
- Token 必须设置合理的过期时间（Access Token 建议 2 小时内，Refresh Token 建议 7 天）。
- 登出（Logout）或踢人操作，必须依赖 Redis 黑名单机制（Token 屏蔽），不能仅靠客户端删除 Token。
2.2.3 标准响应数据格式 (Response 包装类)
注：考虑到不同技术栈和框架的差异（如 Django DRF 原生倾向于直接返回资源 JSON 而不包外层，或者 GraphQL 有其自有的结构），本章节定义的 Response 包装格式为推荐规范。建议团队根据实际业务需求与框架特性灵活决策。一旦选定，同一项目/子系统内必须保持格式一致，避免前端解析困难。
1. 推荐标准外层结构（如需包装）
如果业务决定采用统一包装格式，建议结构如下：
{
"code": 20000, // 业务状态码（非 HTTP 状态码）
"message": "success", // 面向开发者的提示信息 / 面向用户的国际化错误提示
"data": { ... }, // 实际的业务数据（对象或数组）
"traceId": "9b1deb4d..." // 必返：当前请求的追踪ID，方便前端直接带此ID报障
}
2. 分页数据标准结构与实现方案
分页的实现方式多种多样，不同的框架往往有其自带的最佳实践（如 Spring Data 的 Page 接口，Django DRF 的 PageNumberPagination 或 CursorPagination）。在此仅作推荐与指导性建议。
团队在设计分页接口时，应根据具体的业务端（Admin Web 或 App 瀑布流）选择合适的方法：
方案 A：传统页码分页 (Offset/Limit)
- 适用场景： 后台管理系统 (Admin)、PC 端数据表格（允许用户指定跳到第 N 页）。
- 推荐返回结构示例：
{
"data": {
"list": [ {...}, {...} ], // 当前页的数据列表
"total": 150, // 总条数 (注意：数据量极大时 count() 会有性能瓶颈)
"page": 1, // 当前页码
"pageSize": 20, // 每页大小
"hasNext": true // 是否还有下一页
}
}
方案 B：游标分页 (Cursor-based / Keyset Pagination)
- 适用场景： 移动端 App 的“无限滚动”瀑布流、社交动态流。能有效解决数据实时增删导致的“数据重复出现”或“数据漏滑”问题，且性能极佳。
- 推荐返回结构示例：
{
"data": {
"list": [ {...}, {...} ], // 当前页的数据列表
"next_cursor": "eyJpZCI6IDE1MiwgImNyZWF0ZV90aW1lIjogIjIwMjM..." // 用于请求下一页的游标 (通常是 Base64 编码的最后一条数据标识)
}
}
规约提醒：不强制所有分页结构完全统一，但后端在输出分页数据时，应顺应其所用框架的原生分页器能力，并在 Swagger/API 文档中清晰标明采用的分页模式。
3. Null 值与空值规约 (极度容易引发 NPE 和前端白屏)
不论外层是否包装，实际数据体中的空值处理应遵循：
- 集合/数组： 如果列表为空，必须返回空数组 []，严禁返回 null。
- 对象： 如果对象为空，可以返回 {} 或 null（需与前端约定好）。
- 字符串： 如果字符串为空，必须返回 ""，严禁返回字符串 "null"。
- 布尔值： 严禁使用 0/1 替代 true/false，JSON 必须保持类型严谨。
2.2.4 全局错误码 (Error Codes) 分配与定义字典
注：对于敏捷开发或复杂度一般的单体项目，维护庞大的五位数业务错误码字典往往会带来过高的管理成本。因此，本节为推荐规范。团队应根据项目规模灵活决策：轻量级项目完全可以仅依靠“标准 HTTP 状态码 + 清晰明确的 message”来处理异常；如果业务链路较长，需要精细化区分错误类型，则推荐引入以下错误码规范。
我们需要明确区分 HTTP 协议状态码 与 业务错误码。
1. HTTP 状态码规约（代表网络与网关层面的状态）
后端必须正确使用 HTTP 状态码，严禁将所有请求都返回 200 OK，即使系统内部发生了致命异常。
- 200 OK: 请求成功，业务逻辑被执行。
- 400 Bad Request: 参数校验失败（如缺少必填字段，格式错误）。
- 401 Unauthorized: 鉴权失败（Token 缺失、无效或过期）。前端收到后应统一跳转登录页。
- 403 Forbidden: 权限不足（Token 有效，但当前角色无权操作）。
- 404 Not Found: 路由不存在（资源未找到）。
- 429 Too Many Requests: 触发限流，请稍后重试。
- 500 Internal Server Error: 后端发生了未捕获的严重异常（代码 Bug 或数据库宕机）。
2. 业务错误码规约 (Response Body 中的 code 字段，若启用包装类)
若团队决定启用全局错误码，推荐采用 5 位数字 或 纯字符串枚举（如 USER_NOT_FOUND）。以 5 位数字为例：A-BB-CC。
- A (1位)：系统级分类
- 2：成功。
- 4：客户端调用错误（业务约束拦截）。
- 5：服务端内部错误（业务预期内的异常）。
- BB (2位)：模块或子系统编号
- 00：全局公共错误。
- 01：用户中心。
- 02：订单中心。
- CC (2位)：具体错误序号
全局核心字典示例：
- 20000: 业务执行成功。
- 40000: 客户端错误通配。
- 40102: 账户已被冻结。
- 40202: 账户余额不足。
- 50000: 服务器内部错误通配。
规约：如果决定使用错误码，则禁止在代码中硬编码（如 return new Response(40102, "被冻结")），必须统一定义在 ErrorCodeEnum 枚举类中集中管理。
🤖 [附加] AI 助手执行协议 (AI Output Schema)
绝对红线：接口文档必须输出为 OpenAPI 3.0 YAML 格式；所有 HTTP 接口的响应体必须强制包裹在统一的 {code, msg, data} JSON 结构中。