api-design

name	api-design
description	API 设计方法论 —— REST 资源建模、HTTP 语义、状态码规范、版本策略
category	architecture
loading	on-demand
triggers	{"keywords":["API设计","接口设计","RESTful","REST API","OpenAPI","Swagger"]}

这是什么

API 设计是定义系统间通信接口的工程实践。本 Skill 聚焦 RESTful API 设计，涵盖资源建模、HTTP 语义、状态码、版本管理和文档化。

何时使用

• 设计新系统的 API 接口
• 对现有 API 进行版本升级
• API 审查中发现不一致的设计
• 从 RPC 风格向 RESTful 风格迁移
• 需要制定团队 API 设计规范

核心规则

1. 资源优先，动作其次：围绕资源（名词）建模，而非围绕操作（动词）。用 HTTP 方法表达操作语义。
2. 一致胜过完美：整个 API 的风格统一比单个端点的最优设计更重要。开发者只需要学习一种模式。
3. 向后兼容是铁律：不破坏现有客户端。新增字段是安全的，删除或重命名字段是破坏性的。
4. 每个端点只做一件事：不要设计一个端点既创建资源又发送通知又更新统计。可组合性胜过便利性。
5. 错误信息要可操作：错误响应必须包含足够信息让调用方能判断原因并决定下一步动作。

工作流程

1. 资源建模

   • 识别业务域中的核心实体（用户、订单、产品）
   • 定义资源之间的关系（一对多、多对多、依赖）
   • 区分独立资源和子资源，子资源通过父资源路径访问
   • 确定每个资源的唯一标识符方案

2. 端点设计

   • 集合端点：GET /resources 列表查询，POST /resources 创建
   • 单体端点：GET /resources/{id} 获取，PUT/PATCH /resources/{id} 更新，DELETE /resources/{id} 删除
   • 子资源端点：GET /resources/{id}/sub-resources 获取子资源列表
   • 特殊操作：用子资源建模而非动词端点，如 POST /orders/{id}/cancel 而非 POST /cancel-order

3. 请求设计

   • 查询参数用于过滤、排序、分页
   • 请求体用 JSON，字段名用 camelCase 或 snake_case 保持一致
   • 日期时间用 ISO 8601 格式
   • 分页参数：page/offset + limit/pageSize

4. 响应设计

   • 统一响应信封：{ "data": ..., "error": ..., "meta": { "total": 100, "page": 1 } }
   • 列表响应始终包在 data 数组中，即使只有一个元素
   • 不返回 null 字段，用字段缺失表示无值

5. 错误处理

   • 使用正确的 HTTP 状态码
   • 错误体包含：错误码（机器可读）、错误消息（人类可读）、详情（可选，字段级错误）
   • 生产环境不暴露堆栈跟踪

6. 文档化

   • 用 OpenAPI 3.x 规范编写 API 文档
   • 每个端点包含请求示例和响应示例
   • 文档与代码同步更新，不滞后

HTTP 方法语义

方法	语义	幂等	安全
GET	获取资源	是	是
POST	创建资源	否	否
PUT	完整替换资源	是	否
PATCH	部分更新资源	否	否
DELETE	删除资源	是	否
HEAD	获取响应头	是	是
OPTIONS	获取支持的方法	是	是

HTTP 状态码规范

• 2xx 成功：200 通用成功，201 创建成功（含 Location 头），204 成功无响应体（删除）
• 3xx 重定向：301 永久迁移，304 未修改（缓存）
• 4xx 客户端错误：400 请求格式无效，401 未认证，403 无权限，404 资源不存在，409 冲突（版本冲突），422 语义错误（校验失败），429 请求过多
• 5xx 服务端错误：500 内部错误（客户端无法区分），502 网关错误，503 服务不可用

版本策略

• URL 路径版本：/api/v1/resources——最直观、最常用
• 请求头版本：Accept: application/vnd.api.v1+json——URL 简洁但调试不便
• 查询参数版本：/api/resources?version=1——简单但不推荐
• 版本升级规则：只在新版本中做破坏性变更。同时最多维护两个版本（当前和上一版本），旧版本明确弃用日期

Richardson 成熟度模型

• Level 0：单个 URI，单个 HTTP 方法（通常是 POST），类似 RPC
• Level 1：多个 URI，每个资源有独立端点
• Level 2：正确使用 HTTP 方法，用状态码表达结果
• Level 3：HATEOAS——响应中包含可用的下一步链接

建议至少达到 Level 2，Level 3 按需选择。

参考标准

• RFC 7231（HTTP/1.1 语义和内容）—— HTTP 方法的权威定义
• OpenAPI 3.1 规范 —— REST API 文档标准
• JSON:API 规范 —— 标准化 JSON API 格式
• Roy Fielding 博士论文 —— REST 架构风格原始定义
• Google API Design Guide —— 大规模 API 设计实践