api-design-reviewerlisted

## 何时使用 - 评审新增或修改 API 端点的 PR，需快速判断是否符合 REST 约定。 - 为 v2 迁移审计现有 API，识别破坏性变更并产出迁移指引。 - 为团队制定/落地 API 设计规范，并接入 CI 做门禁。 不该用： - GraphQL / gRPC / WebSocket 等非 REST 接口的设计评审。 - 接口的具体业务实现编码、单元测试编写。 - 后端吞吐/延迟的性能压测（本条只评审设计层缓存/分页等模式，不做基准测试）。 ## 步骤 1. 收集输入：目标 API 的 OpenAPI/Swagger 规范（`openapi.json`），如做破坏性变更检测，再取旧版本规范。 2. 跑 lint：检查命名、HTTP 方法、URL 结构、状态码、错误格式、文档覆盖率。 3. 做破坏性变更检测：对比新旧规范，标注端点删除、响应结构/字段/类型变更、新增必填字段。 4. 出评分卡：按一致性(30%)、文档(20%)、安全(20%)、易用性(15%)、性能(15%)给分并给 A-F 等级。 5. 汇总问题清单 + 改进建议，区分「可直接发布」「需修订」「需升版本」。 ## 指令 核心评审维度与硬约束（评审时逐条核对）： 资源命名（kebab-case 资源、camelCase 字段）： ``` ✅ /api/v1/user-profiles /api/v1/orders/123/line-items ❌ /api/v1/getUsers /api/v1/user_profiles /api/v1/orders/123/lineItems ``` HTTP 方法语义：GET 安全幂等 / POST 创建非幂等 / PUT 整体替换幂等 / PATCH 局部更新 / DELETE 删除幂等。 URL 结构：集合 `/users`、单体 `/users/123`、嵌套 `/users/123/orders`、动作 `/users/123/activate`(POST)、过滤 `/users?status=active`。避免动词 URL 与过深嵌套。 版本策略：优先 URL 版本（`/api/v1` `/api/v2`，清晰易路由）；备选 Header / Media Type / Query 版本。 破坏性变更判定（命中即需升版本）：删除响应字段、可选字段改必填、字段类型变更、删除端点、变更 URL 结构、改动错误响应格式。安全变更：新增可选字段、新增响应字段、新增端点、必填改可选、新增枚举值（需优雅处理）。 状态码：400 参数错误 / 401 未认证 / 403 无权限 / 404 不存在 / 409 冲突 / 422 语义错误 / 429 限流 / 500 服务端错误。 CI / 预提交接入： ```yaml - name: api-linting run: python scripts/api_linter.py openapi.json - name: breaking-change-detection run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json - name: api-scorecard run: python scripts/api_scorecard.py openapi.json ``` ## 示例 标准错误响应（评审错误格式时作为基准）： ```