> Adapted from alirezarezvani/claude-skills by Alireza Rezvani (MIT License)。
> 本技能为功能性改编：保留上游「REST 约定 lint + 破坏性变更检测 + 设计评分卡」三件套方法论，重写为平台无关的中文工作流，并附三个纯 Python 标准库、零依赖脚本（scripts/api_linter.py、scripts/breaking_change_detector.py、scripts/api_scorecard.py）；剥离了上游对第三方 OpenAPI 解析库、Claude Code 插件壳与特定框架的绑定。
REST API 设计审查
何时使用
- 审查一个新增或改动 API 端点的 PR；
- 对存量 API 做 v2 迁移前的规范体检；
- 为团队建立统一的 API 设计标准与 CI 门禁。
铁律：不要仅凭文字结论签字放行——先跑三个工具，把 lint 结果、破坏性变更、评分卡一并附上，修复后再跑，直到 lint 干净、破坏性变更已处理（或已版本化）、评分卡达到约定等级。
三步审查流（先跑工具）
# 1. 规范 lint：检查命名/方法/URL/状态码/错误格式/文档覆盖
python scripts/api_linter.py openapi.json --format json -o lint.json
# 2. 破坏性变更：对比 v1 / v2，存在 critical/high 时非零退出
python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --exit-on-breaking -o breaking.json
# 3. 设计评分：五维加权，低于 --min-grade 时非零退出
python scripts/api_scorecard.py openapi.json --min-grade B --format json -o scorecard.json
工具支持 --help 查看全部参数；规范可为 OpenAPI 2.0/3.x 的 JSON 文件，也可用 - 从 stdin 读取。
一、规范 lint（api_linter.py）检查项
- 信息段：
info.title、info.version必填；缺info.description警告。 - 服务器段：未声明
servers（或 Swagger 的host）给予警告。 - 路径结构：路径必须以
/开头；资源段应使用kebab-case；路径参数用camelCase或kebab-case；资源段含动词（如getUsers）给予警告。 - HTTP 方法：只允许 GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS/TRACE，其它一律按错误拦截。
- 操作文档：每个操作应有
description或summary，缺失记为 info。 - 状态码：非标准状态码（不在 200/201/202/204/301/302/304/400/401/403/404/409/422/429/500/502/503/504）给予警告。
- 错误格式一致性：4xx/5xx 响应若出现多种不同错误结构，建议统一为
{code, message, details, requestId}。 - 评分：按 error×10 / warning×3 / info×1 扣分，下限 0，输出 0–100 分。
二、破坏性变更检测（breaking_change_detector.py）类型
| 变更 | 严重度 |
|---|---|
| 端点/方法被移除 | critical |
| 响应字段被移除 | critical |
| 字段类型变更（如 string→integer） | critical |
| 状态码被移除 | high |
| 字段由可选变必填 | high |
| 新增必填字段 | medium |
| 新增可选字段 | low |
| 新增端点/方法 | info |
> 安全做法：所有 critical/high 变更必须伴随版本号提升（URL 版本或媒体类型版本），或对客户端做兼容迁移。
三、设计评分卡（api_scorecard.py）五维权重
| 维度 | 权重 | 评估信号 |
|---|---|---|
| 一致性 Consistency | 30% | 资源命名 kebab-case、字段命名 camelCase 的占比 |
| 文档 Documentation | 20% | 有 description/summary 的操作占比 |
| 安全 Security | 20% | 是否定义 securitySchemes、servers 是否 https |
| 可用性 Usability | 15% | 列表接口是否分页、错误格式是否统一 |
| 性能 Performance | 15% | 是否分页、是否声明 Cache-Control 等缓存头 |
总体分 = Σ(维度分/100 × 权重)；字母等级：A≥90、B≥80、C≥70、D≥60、F<60。输出按权重排序的改进建议。
REST 设计要点（速查）
- 资源用名词、用 kebab-case；动作由 HTTP 方法表达，不要写
getUsers这类动词路径。 - 字段用 camelCase；集合
/users、个体/users/123、嵌套/users/123/orders、动作POST /users/123/activate。 - 分页优先 cursor 或 offset+limit，并始终返回总量/是否还有更多。
- 错误响应统一结构，并带
requestId便于排查。 - 认证用 Bearer/OAuth2/API Key；全站 https；遵循最小权限。
- 兼容性原则：加可选字段、加端点、把必填改可选是安全的；删字段、删端点、字段改必填、字段改类型、改 URL是破坏性的。
CI 集成示例
- name: api-lint
run: python scripts/api_linter.py openapi.json
- name: breaking-change
run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --exit-on-breaking
- name: api-scorecard
run: python scripts/api_scorecard.py openapi.json --min-grade B
说明
- 三个脚本均仅依赖 Python 标准库，无需 pip 安装任何包，可直接在任意 CI 环境运行。
- 静态 lint 无法替代契约测试与真实联调；它负责在合并前拦住明显约定违规与破坏性变更。
- 上游仓库含 380+ 技能，本技能仅取其
api-design-reviewer单技能做等价改编，不引入任何专有依赖。
