api-design-reviewer

API 设计审查器

依据惯例、最佳实践和行业标准，对 REST API 设计进行全面分析与审查。通过自动化 lint 检查、破坏性变更检测和设计评分卡，帮助工程团队构建一致、易维护且设计完善的 API。

核心功能

• API lint 检查与惯例分析 — 资源命名（kebab-case URL、camelCase 字段）、HTTP 方法用法、URL 结构、状态码合规性、错误格式一致性和文档覆盖率。
• 破坏性变更检测 — 检测两个规范版本之间的端点移除、响应结构变化、字段移除或重命名、类型变化、新增必填字段及状态码变化，并提供迁移指南。
• API 设计评分 — 从一致性（30%）、文档（20%）、安全性（20%）、易用性（15%）和性能（15%）五个维度进行加权评分，给出 A–F 等级和改进建议。

适用场景

• 设计新的 REST API 或审查 API 契约。
• 根据 REST 惯例验证 OpenAPI/Swagger 规范。
• 管理 API 版本并检测不同版本发布之间的破坏性变更。
• 在 CI 中根据 API 设计质量控制部署。

先行确认

在生成审查结果前，请确认以下输入。如果有任何信息未知或含糊不清，请提问，不要自行假设：

• 所需输出 — lint 报告、设计评分卡或破坏性变更检测（决定使用 api_linter.py、api_scorecard.py 或 breaking_change_detector.py）
• 规范文件 — OpenAPI/Swagger JSON，或要进行差异比较的两个版本（工具解析的输入）
• 质量门槛 / CI 门禁 — 最低等级或遇到破坏性变更时失败（设置 --min-grade / --exit-on-breaking，并决定判定标准的严格程度）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“直接起草”，则继续处理，并在产物顶部列出假设。

工具

工具	用途	命令
api_linter.py	检查 OpenAPI/Swagger JSON 规范是否符合 REST 惯例和最佳实践	python scripts/api_linter.py openapi.json --format json
breaking_change_detector.py	检测两个规范版本之间的破坏性变更（附带迁移指南）	python scripts/breaking_change_detector.py v1.json v2.json --exit-on-breaking
api_scorecard.py	从 5 个加权维度对 API 设计质量评分（A–F 等级）	python scripts/api_scorecard.py openapi.json --min-grade B

参考资料

根据任务加载相应参考资料 — 保持此文件精简，按需查阅详细信息：

• references/rest-design-patterns.md — REST 命名、方法和 URL 原则、版本控制策略、分页模式、错误格式和状态码、身份验证/RBAC 模式、速率限制、HATEOAS、幂等性、向后兼容规则、OpenAPI 验证、性能和安全最佳实践。设计或审查端点时阅读。
• references/tooling-ci-and-troubleshooting.md — 三种工具的功能、CI/CD 和提交前集成、最佳实践与反模式检查清单、故障排除表、成功标准以及完整的 CLI 标志参考。将工具接入流水线或排查问题时阅读。
• references/rest_design_rules.md — 详细的 REST 设计规则参考（资源与操作、HTTP 方法语义及示例）。需要深入了解规则目录时阅读。
• references/api_antipatterns.md — 常见 API 反模式（基于动词的 URL / RPC 陷阱等），附带错误与正确示例以及推荐的修复方案。审查现有 API 的设计问题时阅读。

范围与限制

此技能涵盖：

• 根据 REST 规范检查 OpenAPI 3.x 和 Swagger 2.0 JSON 规范
• 检测两个规范版本之间的破坏性、可能破坏性和非破坏性变更
• 从一致性、文档、安全性、易用性和性能等方面评估 API 设计质量
• 发现破坏性变更时生成可执行的迁移指南

此技能不涵盖：

• 运行时 API 测试、负载测试或契约测试（参见 api-test-suite-builder）
• GraphQL、gRPC 或 WebSocket API 设计审查
• 根据代码或服务端存根自动生成 OpenAPI 规范
• 身份验证流程实现或 OAuth 服务端配置（参见 engineering/ 中的 senior-security）

集成点

技能	集成方式	数据流
engineering/api-test-suite-builder	根据检查器发现的问题生成测试用例	检查器问题会影响端点验证测试计划的优先级
engineering/changelog-generator	在发行说明中记录破坏性变更	破坏性变更检测器的输出为变更日志提供结构化变更数据
engineering/ci-cd-pipeline-builder	根据 API 质量设置部署门禁	评分卡等级和检查器退出代码可作为流水线质量门禁
engineering/senior-backend	根据设计审查 API 实现	评分卡建议可指导后端重构决策
engineering/code-reviewer	在 PR 审查中补充 API 分析	检查器报告和破坏性变更报告会附加到 PR 审查评论中
engineering/release-manager	验证版本号递增是否与变更严重程度相符	破坏性变更检测器的严重程度可为 semver 版本决策提供依据