api-contract-review

用途：该技能用于审计 REST API 设计的正确性、一致性与兼容性，适合在发布 API 变更前、审查含控制器改动的 PR、或检查向后兼容性时使用。主要能力包括识别常见问题：HTTP 动词误用（如用 POST 做幂等操作、用 GET 做状态变更）、缺少版本管理（/users 而非 /v1/users）、响应中泄漏 JPA 实体、以 200 返回错误体、命名不一致等。它提供 HTTP 动词语义对照表（GET 检索、POST 创建、PUT 全量替换、PATCH 部分更新、DELETE 删除及其幂等性与安全性），推荐 URL 路径版本策略（如 /api/v1/users），并给出 DTO 与实体分离、响应包装一致性、分页、HTTP 状态码（201 创建、204 无内容、400/401/403/404/409/422/500 等）、统一错误响应格式（机器可读 code、人类可读 message、timestamp、path、字段错误）以及避免暴露堆栈的安全建议。还涵盖向后兼容：列出破坏性变更（移除端点、移除字段、新增必填字段、改字段类型、重命名字段、改 URL）与非破坏性变更，并给出弃用模式与评审清单。使用方式：对大型 API 可先列出控制器（find . -name "Controller.java"），抽样 2-3 个分析模式，检查 @ExceptionHandler 配置，并用 grep 查找反模式，例如查找潜在实体泄漏：grep -r "public.Entity.@GetMapping" --include=".java"，查找 200 带错误：grep -r "ResponseEntity.ok.error" --include=".java"，查找未版本化 API：grep -r "@RequestMapping.api" --include=".java" | grep -v "/v[0-9]"。适用场景为 Spring Boot 等 REST 服务的设计审查。限制：资料未提供安装步骤、具体运行命令或与其他工具的集成方式，也未说明收费、价格或效果保证，这些信息暂未提供。