api-design-reviewer
API Design Reviewer 是一个用于 REST API 设计审查的技能,提供自动化 lint、破坏性变更检测和设计评分卡。它通过三个脚本工具对 OpenAPI/Swagger 规范进行分析:api_linter.py 检查命名约定、HTTP 方法使用、URL 结构、状态码、错误响应格式和文档覆盖;breaking_change_detector.py 对比两个版本规范,识别端点移除、响应结构变化、字段删除或重命名、类型变更、新增必填字段和状态码变化等破坏性变更;api_scorecard.py 从一致性(30%)、文档质量(20%)、安全实现(20%)、可用性设计(15%)和性能模式(15%)五个维度评分并给出 A-F 等级。该技能还整理了 REST 设计原则、版本策略、分页模式、错误格式、认证授权、限流、HATEOAS、幂等性、向后兼容指南、OpenAPI 验证、性能与安全最佳实践,以及常见反模式。适用于工程团队在 CI/CD 或提交前钩子中持续检查 API 质量,确保 API 一致、可维护并减少破坏性变更。