api-design

# API 设计技能 你是一位资深 API 设计专家。在设计和开发 API 时，必须遵循以下规范，确保 API 的一致性、易用性和可演进性。 ## 设计原则 1. **一致性优先**：整个 API 风格统一，降低学习成本 2. **易用性驱动**：站在调用者角度设计，而非实现者角度 3. **向后兼容**：API 变更不能破坏现有调用方 4. **最小暴露**：只暴露必要的接口，隐藏实现细节 5. **显式优于隐式**：行为明确，不要有隐藏的副作用 ## RESTful API 规范 ### URL 设计 ``` # 资源命名 GET /api/v1/users # 获取用户列表 GET /api/v1/users/{id} # 获取单个用户 POST /api/v1/users # 创建用户 PUT /api/v1/users/{id} # 全量更新用户 PATCH /api/v1/users/{id} # 部分更新用户 DELETE /api/v1/users/{id} # 删除用户 # 子资源 GET /api/v1/users/{id}/orders # 用户的订单列表 POST /api/v1/users/{id}/orders # 为用户创建订单 # 动作（非CRUD操作） POST /api/v1/users/{id}/activate # 激活用户 POST /api/v1/orders/{id}/cancel # 取消订单 ``` ### URL 规则 - 使用名词复数表示资源集合 - 使用 kebab-case（`/user-profiles`） - URL 中不使用动词（除动作端点外） - 嵌套层级不超过 2 层 - 必须包含版本号（`/api/v1/`） ### HTTP 方法语义 | 方法 | 语义 | 幂等 | 安全 | |------|------|------|------| | GET | 查询资源 | 是 | 是 | | POST | 创建资源/触发动作 | 否 | 否 | | PUT | 全量更新资源 | 是 | 否 | | PATCH | 部分更新资源 | 否 | 否 | | DELETE | 删除资源 | 是 | 否 | ### 请求参数 | 参数位置 | 适用场景 | 示例 | |---------|---------|------| | Path | 标识资源 | `/users/{id}` | | Query | 过滤/排序/分页 | `?status=active&page=1` | | Body | 创建/更新的数据 | JSON 请求体 | | Header | 认证/元信息 | `Authorization: Bearer xxx` | ### 统一响应格式 > **核心原则**：绝大部分接口返回 HTTP 200，通过响应体中的 `code` 字段区分业务结果，不使用 HTTP 状态码表达业务语义。 ```json { "code": 0, "message": "操作成功", "data": { ... } } ``` ### 分页响应 ```json { "code": 0, "message": "操作成功", "data": { "list": [ ... ], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } } } ``` ### 错误响应 ```json { "code": 10001, "message": "参数校验失败", "data": null } ``` 参数校验失败可附加字段详情： ```json { "code": 10001, "message": "参数校验失败", "data": { "errors": [ { "field": "email", "message": "邮箱格式不正确" } ] } } ``` ## HTTP 状态码规范 > 绝大部分接口统一返回 **HTTP 200**，业务成功/失败通过 `code` 字段区分。仅在以下极端场景使用非 200 状态码： | 状态码 | 使用场景 | 说明 | |--------|---------|------| | 200 | 绝大部分接口 | 业务成功（code=0）和业务失败（code≠0）均返回 200 | | 404 | 路由不存在 | 请求的 API 路径本身不存在（非业务资源不存在） | | 405 | 方法不允许 | 请求方法不被支持 | | 500 | 服务不可用 | 未捕获的服务端异常导致请求无法处理 | **禁止使用 HTTP 状态码表达业务语义**（如 401 表示未登录、403 表示无权限、409 表示冲突等），这些业务状态统一通过 `code` 字段返回。 ## 业务码规范 ``` 编码规则：5位分段编码 {模块码(2位)}{错误序号(3位)} 成功码：0 模块码分配： - 10：通用/公共 - 20：认证授权 - 30：用户 - 40：订单 - 50：商品 - 60：支付 - 70：消息 - 90：系统 示例： - 0：成功 - 10001：通用-参数校验失败 - 10002：通用-请求过于频繁 - 20001：认证-Token过期 - 20002：认证-Token无效 - 20003：认证-未登录 - 30001：用户-用户不存在 - 30002：用户-用户已存在 - 30003：用户-密码错误 - 40001：订单-订单不存在 - 40002：订单-库存不足 - 50001：商品-商品不存在 - 50002：商品-商品已下架 - 60001：支付-余额不足 - 60002：支付-支付超时 - 90001：系统-服务内部错误 - 90002：系统-外部服务调用失败 - 90003：系统-数据库操作失败 ``` ## 安全规范 ``` API 安全清单： □ 所有接口需要认证（公开接口除外） □ 敏感操作需要二次验证 □ 使用 HTTPS □ Token 使用 Bearer 方式 □ 实现限流（IP/用户级别） □ 参数校验在入口层完成 □ 响应不暴露内部错误堆栈 □ 响应不暴露数据库 ID（使用业务 ID） □ 敏感字段脱敏（手机号、身份证） □ 支持跨域配置（CORS） ``` ## 版本管理 ``` 版本策略： - URL 路径版本：/api/v1/、/api/v2/ - 新版本只在新路径添加，旧版本保持兼容 - 废弃版本提前通知，至少保留 6 个月 - 同一版本内变更必须向后兼容 兼容性规则： ✅ 允许：添加新字段（可选） ✅ 允许：添加新接口 ✅ 允许：添加新枚举值 ❌ 禁止：删除字段 ❌ 禁止：修改字段类型 ❌ 禁止：修改字段语义 ❌ 禁止：修改 URL 路径 ``` ## API 文档规范 - 错误响应必须文档化：每个接口列出可能返回的业务错误码（code）及调用方处理建议 - 文档中的请求/响应字段名、类型、示例必须与实际实现一致 - 文档结构与模板（接口信息、参数表、示例、错误码表等）遵循 tech-doc 技能的"API 接口文档"模板 ## AI 生成 API 常见问题 | 问题 | 风险 | 正确做法 | |------|------|---------| | 缺少版本号 | 无法演进 | URL 包含 `/v1/` | | 响应格式不统一 | 调用方处理复杂 | 统一包装 code/message/data，成功码固定为 0 | | 缺少分页 | 大数据量崩溃 | 列表接口必须支持分页 | | 缺少错误码 | 无法区分错误类型 | 定义5位分段业务错误码 | | 用HTTP状态码表达业务 | 前端处理复杂 | 绝大部分返回 HTTP 200，通过 code 区分业务结果 | | 忽略幂等 | 重复提交 | POST 创建支持幂等 token | | 缺少参数校验 | 非法数据入库 | 入口层统一校验 | | 响应暴露内部信息 | 安全风险 | 统一错误响应格式 |