API 设计助手

解决什么问题

手工设计 RESTful API 时，失败往往不在接口跑不起来，而在语义失控：POST /getUserList 这类动词式路径混进代码库，PUT 与 PATCH 的幂等边界说不清，列表接口一会儿返回数组一会儿返回 {data, total}，错误码在 400 和 200 之间反复横跳。这个 skill 把一套可重复的设计约束固化下来，让 AI agent 按统一规范产出端点定义、请求响应结构与 OpenAPI 文档，而不是临场发挥。

核心能力与工作流程

它把 API 设计拆成六步：

1. 识别资源与关系——从业务描述中抽取名词（users、tasks、comments），明确一对多、多对多关系，决定用子资源（/tasks/{id}/comments）还是独立集合。核心纪律：URI 只放资源名，不放动词。
2. 定义端点与 HTTP 方法——GET 读取（安全、幂等），POST 创建（非幂等），PUT 全量替换、PATCH 部分更新、DELETE 删除（均幂等）。强关联资源嵌套在父资源下。
3. 设计请求与响应 schema——字段命名统一为 snake_case 或 camelCase，区分必填/可选、类型与校验约束，所有端点共用一个错误信封。
4. 分页、过滤与排序——列表接口支持游标或偏移分页（limit/offset），过滤走查询参数（如 ?status=active），排序用 sort + order，响应带 total 与 next/prev 链接。
5. 版本与内容协商——URI 路径 /v1/tasks（最常见）、查询参数 ?version=1 或 Accept 头三选一；同版本内向后兼容，弃用需文档化时间线。
6. 生成 OpenAPI 文档——输出完整 OpenAPI 3.0 规范，含 paths、schemas、安全方案与示例，响应文档带限流头 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset。

另有几条值得抄进团队规范的实践：资源路径用复数；POST 支持 Idempotency-Key；响应带 HATEOAS 链接；从第一天起做版本号；201 Created 返回 Location 头。技术栈覆盖 OpenAPI 3.0/3.1、JSON Schema、AsyncAPI（仅事件驱动扩展）与 Express.js、FastAPI、Django REST Framework、Spring Boot、Rails API，文档工具兼容 Swagger UI、Redoc、Stoplight，测试可用 Postman、Insomnia、REST Client、curl。

适用边界与注意点

常见坑有明确结论：空集合返回 200 + 空数组 + has_more: false 而非 404；硬删除返回 404，软删除返回 410 Gone 并附删除时间；并发更新用 ETag + If-Match，冲突时返回 412；批量部分失败返回 207 Multi-Status 逐项标注；尾部斜杠归一化，强制规范形式时用 301；未知查询参数要么静默忽略要么报 400，关键是全局一致。

也要留意边界：它的输入是业务领域描述，输出是设计产物而非可运行代码；认证与权限只体现在文档的 security schemes 中，不会生成鉴权中间件；422、207 等细节需团队先达成共识，否则会与现有规范冲突。