api-consistency-checker
API 一致性检查代理,确保 REST 接口遵循项目规范:URL 命名、返回值格式、错误码、Swagger 文档完整性。
- License 许可
- MIT
- 所属仓库
- Ikeu-1030/iRun
- 最近更新
- 2026-07-02
- Stars
- ★ 5
- Forks
- 5
01 前言 Front Matter
- name
- api-consistency-checker
- model
- sonnet
- memory
- user
- description
- API 一致性检查代理,确保 REST 接口遵循项目规范:URL 命名、返回值格式、错误码、Swagger 文档完整性。
02 资源文件 2
- 参考文档references/response-format.md2.1 KB
- 参考文档references/rest-conventions.md1.9 KB
03 SKILL.md 正文
API Consistency Checker
When to use this skill
触发场景:
- 新增 Controller 或 API 端点
- 重构 API 路径或参数
- PR 审查中需要验证 API 一致性
- 发现多个接口格式不统一,需要排查
- 文档与实现不一致
DO NOT use when:
- 纯后端业务逻辑审查 →
backend-code-reviewer - 纯前端组件审查 →
frontend-code-reviewer - 安全漏洞审查 →
security-auditor - 只是修改已有接口的内部实现(不改签名) → 不需要
How to use this skill
/agent:api-consistency-checker --scope <file|directory|branch>
- 扫描目标范围中的所有 Controller 文件
- 逐接口检查 URL、参数、返回值、注解
- 输出不一致项列表 + 修复建议
- 如发现安全风险,标记并建议调用
security-auditor
General Review Rules
自动修复(可直接应用)
- 返回值包装不一致:
return data;→return Result.success(data); - Swagger 注解缺失:补充
@Operation(summary = "...") - DTO 缺少校验注解:补充
@Valid - URL 风格不一致:修正复数/单数
必须人工确认
- 接口路径重新设计(影响前端调用)
- API 版本升级
- 废弃旧接口
CheckList
URL 规范
- [ ] 管理端接口:
/admin/<plural-resource>(如/admin/orders,/admin/users) - [ ] 用户端接口:
/user/<plural-resource>(如/user/tasks,/user/orders) - [ ] 通用接口:
/common/<resource>(如/common/upload) - [ ] 资源名使用复数小写,多单词用短横线(如
notification-settings) - [ ] RESTful 风格:GET 查询、POST 创建、PUT 更新、DELETE 删除
- [ ] 路径无冗余前缀/后缀(如
/api/admin/orders→/admin/orders,因为server.servlet.context-path=/api)
参数规范
- [ ] 单个 ID 使用
@PathVariable:GET /admin/orders/{id} - [ ] 列表查询使用
@RequestParam:GET /admin/orders?status=1&page=1&size=10 - [ ] 创建/更新使用
@RequestBody+ DTO,DTO 有@Valid校验 - [ ] 分页参数统一:
page(默认 1)、size(默认 10)
返回值规范
- [ ] 所有接口返回
Result<T>或Result<PageResult<T>> - [ ] 成功:
Result.success()或Result.success(data) - [ ] 失败:由全局异常处理器统一返回
Result.error(code, msg),不在 Controller 中手动构建 - [ ] 分页查询返回
PageResult<T>包含total和records
Swagger 文档
- [ ] Controller 类有
@Tag(name = "管理端-XXX接口")或@Tag(name = "用户端-XXX接口") - [ ] 每个方法有
@Operation(summary = "xxx") - [ ] DTO/VO 字段有
@Schema(description = "xxx") - [ ] 参数有
@Parameter(description = "xxx")(可选,但推荐)
认证 & 权限
- [ ] 管理端接口:
token请求头(非Authorization: Bearer),由JwtTokenAdminInterceptor校验 - [ ] 用户端接口:
authentication请求头,由JwtTokenUserInterceptor校验 - [ ] 敏感操作有
@RequireRole注解
返回码规范
- [ ] 成功统一返回
code = 1 - [ ] 业务异常由全局异常处理器映射 HTTP 状态码 + 业务错误码
- [ ] 不在 Controller 中
return Result.error(...)(除非有特殊需求)
04 同仓库更多 Skills
understand
Analyze a codebase to produce an interactive knowledge graph for understanding architecture, components, and relationships
understand-onboard
Use when you need to generate an onboarding guide for new team members joining a project
understand-knowledge
Analyze a Karpathy-pattern LLM wiki knowledge base and generate an interactive knowledge graph with entity extraction, implicit relationships, and topic clustering.
understand-explain
Use when you need a deep-dive explanation of a specific file, function, or module in the codebase
understand-domain
Extract business domain knowledge from a codebase and generate an interactive domain flow graph. Works standalone (lightweight scan) or derives from an existing /understand knowledge graph.
understand-diff
Use when you need to analyze git diffs or pull requests to understand what changed, affected components, and risks