API Design

API工程师技能 (API Engineer Skill)

快速规则（日常开发时自动加载，只需读到这里）

[API核心清单] ① 资源用名词复数+≤2层嵌套，❌动词URL ② 统一{code,data,message}响应，列表必须分页(默认20最大100) ③ 新端点默认需认证，CRUD必须验资源所有权 [幂等三条] POST用Idempotency-Key防重复，PUT/DELETE天然幂等，支付类必须服务端去重 [安全三禁] ❌直接返回DB模型(用DTO) ❌返回密码hash/内部ID ❌500返回堆栈

写/改API端点时，强制遵守：

1. URL规范：资源用名词复数(/users)，嵌套≤2层，❌禁止动词URL(/getUser)（动词URL破坏REST语义，导致端点爆炸且无法统一缓存/权限策略）
2. HTTP方法：GET读(无副作用) POST创建 PUT替换 PATCH更新 DELETE删除，❌禁止POST做所有操作（丢失HTTP语义=无法利用缓存/幂等性/安全性约定，客户端无法预判行为）
3. 认证授权：新端点默认需认证，CRUD必须验证资源所有权(防IDOR)，批量操作逐个验权
4. 响应格式：统一{code, data, message}，列表带分页(默认20最大100)，空列表返回[]非null
5. 错误处理：400参数错误(含字段详情) / 401未认证 / 403无权限 / 404不存在 / 422业务拒绝 / 500+唯一ID
6. 幂等安全：POST创建必须有幂等键(Idempotency-Key)，支付类必须服务端去重
7. 性能：列表必须分页，批量操作有上限，N+1查询→批量查询，大导出→异步+下载链接
8. 安全：❌禁止直接返回DB模型(用DTO)（DB模型新增字段会意外暴露敏感数据） ❌禁止返回密码hash/内部ID（攻击者可离线破解或枚举内部资源） ❌禁止500返回堆栈（堆栈暴露框架版本/文件路径/SQL结构）

新增端点前：Grep确认无重复端点 → 确认命名风格一致 → 确认已加认证中间件

完整审查流程（手动 /api-design 或专项审查时执行）

Phase 1: API现状扫描

1. 扫描所有API端点（Grep路由定义/Controller/Handler）：

   • 列出所有路由：HTTP方法 + 路径 + Handler函数 + 中间件
   • 识别端点完成度：已实现 / TODO占位 / 废弃未删除
   • 用MCP工具(desc_table/read_query)检查API关联的数据模型

2. 检查API一致性：

   • URL命名风格是否统一（kebab-case? camelCase? snake_case?）
   • 响应格式是否统一（所有端点是否用相同的响应结构）
   • 认证方式是否统一（JWT? Session? API Key? 混用?）
   • 错误格式是否统一（错误码体系是否一致）

Phase 2: RESTful设计规范审查

3. URL设计：

   • 资源用名词复数：/users不是/getUser或/user
   • 嵌套关系：/users/{id}/orders（不超过2层嵌套）
   • 查询过滤：/users?status=active&sort=-created_at
   • ❌ 禁止：动词URL(/getUsers//deleteUser)、深层嵌套(>2层)、无意义ID暴露（动词破坏统一性，深嵌套增加耦合度，暴露内部ID助力枚举攻击）

4. HTTP方法：

   • GET：读取，无副作用，可缓存
   • POST：创建新资源
   • PUT：完整替换资源
   • PATCH：部分更新资源
   • DELETE：删除资源
   • ❌ 禁止：用POST做所有操作、GET请求有副作用（POST做所有=丢失HTTP语义约定；GET有副作用=爬虫/预加载会触发数据变更）

5. 状态码规范：

• ❌ 禁止：所有错误都返回200+自定义code、所有错误都返回500（200+自定义code让客户端无法用HTTP状态码统一处理错误；全500丢失了错误类型信息）

Phase 3: 请求与响应规范

6. 请求规范：

   • 必须验证所有输入参数（类型/范围/长度/格式）
   • 验证失败返回具体字段和原因（不只说"参数错误"）
   • 分页参数：page+page_size或cursor+limit，有最大值限制
   • 排序参数：白名单校验可排序字段，防止任意字段排序导致慢查询
   • 文件上传：类型白名单+大小限制+文件名消毒

7. 响应格式（全局统一）：

// 成功
{
  "code": 0,
  "data": { ... },
  "message": "success"
}

// 列表（带分页）
{
  "code": 0,
  "data": {
    "items": [ ... ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

// 错误
{
  "code": 40001,
  "message": "用户友好的错误描述",
  "details": [
    { "field": "email", "reason": "格式不正确" }
  ]
}

• ❌ 禁止：返回原始数据库错误/堆栈/内部路径（暴露数据库结构/框架版本/文件路径给攻击者）
• ❌ 禁止：返回不需要的字段如密码hash/内部ID/调试信息（扩大攻击面，hash可离线破解，内部ID可枚举）
• ✅ 用DTO/序列化器控制返回字段，而非直接返回数据库模型

8. 空值与默认值：
   • 列表为空返回[]不是null
   • 可选字段缺失时有默认值，不是undefined
   • 数字字段缺失返回0不是null（除非null有语义意义）

Phase 4: 认证与授权

9. 认证规范：

   • 新端点默认需认证，公开端点用@public显式标记
   • Token必须：验签+检查过期+检查吊销（不能只解码不验证）
   • 刷新Token机制：Access Token短期(15-30min) + Refresh Token长期(7-30天)
   • Token存储：HttpOnly Cookie(Web) / Keychain(iOS) / KeyStore(Android)
   • ❌ 禁止：Token在URL参数中传递（会被日志/Referer/浏览器历史记录泄露）、LocalStorage存Token（XSS可直接读取）、永不过期的Token（泄露后永久有效无法止血）

10. 授权规范：

    • 每个CRUD操作必须验证资源所有权（防IDOR）
    • GET /users/{id}/orders → 必须验证当前用户有权查看该用户的订单
    • 批量操作必须逐个验证权限（不是只验证第一个）
    • 管理员操作必须有独立的权限检查（不只靠角色字段）
    • 权限检查在业务逻辑之前执行

Phase 5: 错误处理与重试

11. 错误处理分层：

- 每个500错误必须生成唯一ID，日志中可追踪
- 生产环境500不返回堆栈，只返回错误ID
- 第三方服务失败：返回503而非500，告知客户端可重试

12. 幂等性设计：
    • POST创建：用幂等键(Idempotency-Key)防重复创建
    • PUT/DELETE：天然幂等（重复执行结果相同）
    • 支付/转账类：必须有幂等键+服务端去重
    • ❌ 禁止：POST创建无去重机制（网络重试=重复数据）

Phase 6: 并发与性能

13. 并发安全：

    • 乐观锁：更新时带版本号（UPDATE ... WHERE version = ?），冲突返回409
    • 限流：全局限流+按用户限流+按端点限流
    • 防重放：请求带时间戳+签名，过期请求拒绝
    • 长耗时操作：异步化（返回202 Accepted + 轮询/WebSocket通知）

14. 性能规范：

    • 列表API必须分页（默认20条，最大100条）
    • 批量操作有上限（一次最多操作N个资源）
    • N+1查询检测：Grep循环中的数据库调用
    • 响应时间目标：P95 < 200ms（读）/ P95 < 500ms（写）
    • 大数据导出：流式返回或异步+下载链接，不在内存中拼接

15. 缓存策略：

    • 读多写少的数据：Cache-Control / ETag / Redis缓存
    • 缓存失效策略：TTL + 主动失效（写入时清除相关缓存）
    • ❌ 禁止：缓存带认证的个人数据到公共CDN（个人数据被CDN缓存后，其他用户可能拿到别人的数据）

Phase 7: 版本控制与兼容

16. 版本策略：

    • URL路径版本：/v1/users、/v2/users
    • 旧版本维护期：至少维护2个版本，新版本稳定后废弃旧版
    • 废弃API：返回Deprecation头 + 文档标记 + 日志记录使用量

17. 向后兼容规则：

    • ✅ 允许：新增可选字段、新增端点、放宽验证
    • ❌ 破坏性变更：删除字段、修改字段类型、改变语义、加严验证
    • 破坏性变更必须升版本号

Phase 8: API文档与测试

18. 文档规范：

    • 每个端点必须有：描述、请求参数、响应示例、错误码列表
    • 使用OpenAPI/Swagger自动生成文档（代码即文档）
    • 文档必须包含认证说明和速率限制说明

19. 测试覆盖：

    • 每个端点至少覆盖：正常请求、参数缺失、参数非法、未认证、无权限、资源不存在
    • 边界测试：空列表、超长字符串、特殊字符、并发请求
    • 安全测试：SQL注入参数、XSS参数、超大请求体

Phase 9: 输出报告

## API审查报告

### 端点清单
| 方法 | 路径 | Handler | 认证 | 状态 |

### 设计规范违规
| # | 端点 | 问题类型 | 描述 | 修复建议 | 严重度 |

### 安全问题
| # | 端点/文件:行号 | 问题 | 攻击场景 | 修复建议 | 严重度 |

### 性能风险
| # | 端点 | 问题 | 影响 | 优化方案 | 优先级 |

### 一致性问题
| 类别 | 当前状态 | 建议统一方案 |

### 缺失项
| 类别 | 缺失内容 | 建议 | 优先级 |

API开发规则（写API代码时强制遵守）

新增端点前必须执行

1. Grep确认没有已存在的同功能端点
2. 确认URL命名与现有端点风格一致
3. 确认响应格式与全局统一格式一致
4. 确认已添加认证中间件（除非显式标记@public）

修改端点前必须执行

1. Grep所有调用方（前端/移动端/第三方）确认影响范围
2. 确认修改是否向后兼容，不兼容必须升版本号
3. 确认错误处理覆盖所有分支

写API代码强制规则

• ❌ 禁止直接返回数据库模型——用DTO控制返回字段（DB模型含密码hash/内部字段，泄露后可被攻击）
• ❌ 禁止GET请求有副作用（缓存/爨虫/预加载会意外触发修改，违反HTTP语义）
• ❌ 禁止POST创建无幂等机制（网络重试/用户双击=重复创建资源）
• ❌ 禁止列表API无分页（数据量增长后单次返回百万行，OOM或超时）
• ❌ 禁止无WHERE的UPDATE/DELETE暴露为API（一次调用可清空整张表）
• ✅ 所有输入必须验证（类型+范围+长度+格式）
• ✅ 所有CRUD必须验证资源所有权
• ✅ 500错误必须有唯一ID用于追踪

约束

• 所有发现必须有 端点路径 或 文件:行号 引用
• 安全问题必须附带攻击场景说明
• 性能建议必须基于实际查询模式
• API设计建议遵循最小权限原则