API 接口设计助手

解决的问题

接口设计中最常见的风险，不是单个接口写不出来，而是多个接口之间缺少统一约定：资源命名不一致、查询参数和路径参数混用、分页字段口径不同、错误响应结构随意扩展。这些问题会直接增加前后端联调、Mock 准备和后续维护成本。

这个技能把一段需求描述整理成可评审的接口设计文档，重点解决 API 风格不统一、响应结构不一致 和 文档与示例脱节 的问题。

技能如何工作

它按 RESTful 规则组织资源路径：资源使用名词复数，动作通过 GET、POST、PUT、PATCH、DELETE 表达，路径层级尽量不超过三层。版本策略采用 URL 版本化，例如 /api/v1/，并明确新增字段不属于破坏性变更。

在输出层面，它会围绕通用响应结构、分页规范和字段模板生成文档，并提供几类快捷产物：

• /gen-mock 生成 Mock 数据
• /gen-curl 生成 curl 调用示例
• /check-design 检查接口设计合理性
• /gen-openapi 生成 OpenAPI 3.0 YAML

适用边界

它适合后端接口设计、API 文档评审、联调前字段对齐，以及需要快速补充 Mock 和 curl 示例的场景。它不负责实现业务逻辑、数据库迁移、权限体系设计或生产网关配置。若项目依赖私有协议、非标准鉴权、复杂事件流或特殊网关路由，仍需要人工补充上下文。