api-design-checklist

# API 设计检查清单 ## 实施前审查 ### 资源设计 - [ ] 资源是名词，不是动词 - [ ] 集合使用复数名称 - [ ] 所有端点命名一致 - [ ] 清晰的资源层级（避免超过 2 级的深度嵌套） - [ ] 所有 CRUD 操作正确映射到 HTTP 方法 ### HTTP 方法 - [ ] GET 用于检索（安全、幂等） - [ ] POST 用于创建 - [ ] PUT 用于完全替换（幂等） - [ ] PATCH 用于部分更新 - [ ] DELETE 用于删除（幂等） ### 状态码 - [ ] 200 OK 用于成功的 GET/PATCH/PUT - [ ] 201 Created 用于 POST - [ ] 204 No Content 用于 DELETE - [ ] 400 Bad Request 用于格式错误的请求 - [ ] 401 Unauthorized 用于缺少认证 - [ ] 403 Forbidden 用于权限不足 - [ ] 404 Not Found 用于资源缺失 - [ ] 422 Unprocessable Entity 用于验证错误 - [ ] 429 Too Many Requests 用于速率限制 - [ ] 500 Internal Server Error 用于服务器问题 ### 分页 - [ ] 所有集合端点均已分页 - [ ] 定义默认页面大小（例如 20） - [ ] 强制执行最大页面大小（例如 100） - [ ] 包含分页元数据（总数、页数等） - [ ] 选择基于游标或基于偏移量的模式 ### 过滤与排序 - [ ] 使用查询参数进行过滤 - [ ] 支持排序参数 - [ ] 支持全文搜索的搜索参数 - [ ] 支持字段选择（稀疏字段集） ### 版本控制 - [ ] 定义版本控制策略（URL/Header/Query） - [ ] 所有端点包含版本号 - [ ] 记录弃用策略 ### 错误处理 - [ ] 一致的错误响应格式 - [ ] 详细的错误消息 - [ ] 字段级验证错误 - [ ] 用于客户端处理的错误代码 - [ ] 错误响应中的时间戳 ### 认证与授权 - [ ] 定义认证方法（Bearer token, API key） - [ ] 所有端点进行授权检查 - [ ] 正确使用 401 与 403 - [ ] 处理 Token 过期 ### 速率限制 - [ ] 定义每个端点/用户的速率限制 - [ ] 包含速率限制 Header - [ ] 超出限制时返回 429 状态码 - [ ] 提供 Retry-After Header ### 文档 - [ ] 生成 OpenAPI/Swagger 规范 - [ ] 记录所有端点 - [ ] 提供请求/响应示例 - [ ] 记录错误响应 - [ ] 记录认证流程 ### 测试 - [ ] 业务逻辑的单元测试 - [ ] 端点的集成测试 - [ ] 测试错误场景 - [ ] 覆盖边缘情况 - [ ] 重负载下的性能测试