Agent Skills
返回列表
💻

API 设计 Pro

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @user_8ee65e73/cd-api-design-en。

技能介绍

你会卡在什么地方

新服务要对外暴露 HTTP 接口时,往往先在评审里吵一圈:资源路径该用名词还是动词、POST 和 PUT 的语义怎么划界、分页参数叫 page 还是 cursor,以及错误体要不要和别的团队统一。草图画出来了,写成文档又对不上实现;版本一升级,调用方就开始问「这是不是破坏性变更」。这些都不是「再写一个 CRUD」能糊弄过去的,需要的是在设计阶段就把契约、命名和演进策略说清楚。

这个技能在对话里能帮你什么

API Design Pro(@user_8ee65e73/cd-api-design-en)是挂在 SkillHub 上、面向开发编程场景的大模型技能。把它装进 AI 助手之后,你可以把当前的设计草案、接口列表或一段伪 OpenAPI 丢进对话,让助手按 API 设计 这一主线来回应:帮助梳理资源模型、HTTP 方法与状态码的选用、请求/响应字段命名,以及文档里该怎么描述幂等、分页和错误语义。

典型用法包括在方案阶段对齐 REST 风格约定(或你声明的其它风格)、补全遗漏的边界情况说明,以及在发版前一起过一遍「对外契约」——哪些地方一旦改了就会波及客户端。输出仍然是工程师可执行的说明与示例,由你决定是否采纳、是否落进仓库里的规范文件。

适用边界

技能侧重在 设计与说明,不会替你直连 CI、也不会自动扫描线上流量。最终契约以你的网关、代码生成器和团队规范为准;若团队已有强制模板(例如固定的错误码表),应在对话里先声明约束,避免助手按通用最佳实践给出与内部标准冲突的建议。

使用场景

  • 微服务首次对外暴露 REST 接口,需要在评审前把路径、动词和错误体写成一份可讨论的契约草案
  • 现有 v1 接口要加字段或改枚举,想先列出哪些改动算破坏性变更、哪些可以靠可选字段吸收
  • 多团队协作时,要把分页、鉴权错误和业务错误的 JSON 结构统一成同一套对外说明
  • 从 Product 需求拆成资源模型,不确定该用嵌套资源还是扁平 ID,需要对照常见 REST 建模取舍

适合人员

  • 负责新后端模块的技术负责人,要在两周内定稿对外 HTTP 契约并让前端/客户端能并行开发
  • 维护公共 API 的平台工程师,每周处理多个服务的版本与兼容性答疑
  • 写 OpenAPI 或内部接口手册的后端开发,希望对话里快速对齐命名与状态码而不是从零搜博客
  • 做 Code Review 的资深开发,需要 checklist 式地挑路径语义、幂等和错误码是否自洽