API 设计师
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/zhaono1-agent-playbook-api-designer。
技能介绍
要解决什么问题
团队在新建服务、对外暴露接口或重构老 API 时,常见问题不是「会不会写路由」,而是资源怎么命名、哪些操作用哪种 HTTP 方法、错误时返回什么状态码、分页和筛选参数是否一致,以及 GraphQL 里 nullable 与 mutation 错误形态是否统一。接口文档与实现一旦分叉,联调成本和后续版本维护会迅速放大。
技能如何工作
API Designer 在你要设计新 API、评审现有设计、改进接口或编写 API 规范时介入,按 REST 与 GraphQL 两条线给出可落地的设计原则与检查点。
REST 侧覆盖:资源导向的 URL 设计(对比应回避的反例)、GET/POST/PUT/PATCH/DELETE 的安全性与幂等性、常用 状态码(如 201/409/422/429)、命名约定(URL 用 kebab-case、JSON 用 camelCase)、分页以及过滤与排序。GraphQL 侧强调 schema 设计:默认 non-null、列表用基于 cursor 的 connections、mutation 使用统一 payload 处理错误,并为类型与字段写清描述。
此外会引导 API 版本(如 URL 路径 v1、或通过 Header)、鉴权方式(JWT Bearer、API Key、OAuth 2.0)、按端点说明权限与 403 语义、速率限制量级,以及文档应包含的端点说明、请求/响应示例与错误格式。技能内还提到用于生成 API 脚手架与校验设计的脚本,并指向 references/rest-patterns.md、references/graphql-patterns.md 等参考材料。
适用边界与注意点
本技能聚焦设计规范与评审视角,不替代你所在组织的网关配置、具体框架代码生成或 OpenAPI/GraphQL 文件的自动同步流程。REST 资料里部分表格在原文中为提纲式占位(如资源导向的 Good/Avoid 明细),实际输出仍需结合业务域建模;版本与限流数值应以你们的环境策略为准,技能给出的是常见工程约定而非硬性 SLA。
使用场景
- 微服务首次对外提供用户与订单资源,需要定 URL、HTTP 方法与统一错误状态码
- Code Review 前要让同事按资源导向与命名约定检查既有 REST 路由设计
- GraphQL 列表接口要从 offset 分页迁到 cursor connection,并统一 mutation 错误返回
- 老 API 要引入 v2 且保留 v1,需要梳理 URL/Header 版本策略与弃用说明
适合人员
- 负责对外 B2B/B2C 接口的后端工程师,希望评审稿里有可执行的状态码与分页约定
- 平台组同学在写内部 API 设计文档,需要补齐鉴权方式与按端点权限说明
- 从 REST 扩展 GraphQL 的全栈开发者,关心 schema nullable 与文档字段描述是否一致
- 技术负责人在合并多个团队 API 风格前,想先对齐版本策略与速率限制文档模板