API设计参谋
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @user_8ee65e73/cd-api-design。
技能介绍
要解决什么问题
团队在迭代 HTTP / RPC 接口时,常见问题并不在「能不能跑通」,而在命名不一致、错误语义模糊、版本策略各说各话。草案里经常出现同一资源多种路径写法、201 与 200 混用、分页参数有时叫 page 有时叫 offset,对外文档与实现 subtly 对不上。这些问题在代码评审里容易被一带而过,却会在联调、SDK 生成和长期维护里持续付出代价。
技能如何协助
API设计参谋是以对话方式参与设计与评审的大模型技能(@user_8ee65e73/cd-api-design)。你可以把资源草图、现有路由列表或 openapi.yaml 片段贴给它,让它从资源建模、动词与状态码、错误体结构、版本与兼容等维度提问和对照惯例,指出歧义点并给出可讨论的改法,而不是直接代写整套规范。
典型用法包括:
- 对照 REST 风格检查路径是否体现资源层级,方法是否语义合适
- 梳理错误响应是否具备稳定的
code/message(或等价字段)供客户端分支 - 在破坏性变更前列出影响面,协助选择 URL 版本、
Accept-Version等策略
适用边界与注意点
它输出的是设计层面的建议与 checklist,不能替代你们团队的治理流程、安全审计或性能压测结论。技能资料未绑定具体技术栈模板;若你们已有公司级 API 指南,应把关键条款一并提供给模型,避免建议与内部规范冲突。涉及鉴权、PII、速率限制等敏感设计时,仍需由具备权限的工程师做最终裁定。
使用场景
- 新服务定稿前,要把资源路径、HTTP 方法与状态码对照表写成团队可执行的一致规范
- 对外 OpenAPI 与线上实现字段不一致,需要逐项核对命名、必填项与枚举值
- 大版本升级前,要选定 URL 版本还是 Header 协商,并列出破坏性变更影响范围
- 多团队微服务各自定义错误 JSON,需要统一 `code`、`message` 与 HTTP 状态映射
适合人员
- 负责对外 HTTP API 与 SDK 的后端工程师,希望在评审草案时有人按惯例指出命名与语义问题
- 平台组架构师,要在多业务接入前敲定通用分页、鉴权头与错误体字段约定
- 接手遗留 REST 接口的技术负责人,需要在少动客户端的前提下收敛重复或歧义端点
- 维护 OpenAPI 并生成客户端代码的开发者,想把 `operationId` 与路由命名统一成可生成风格