API 设计器

要解决什么问题

在评审或开工前，团队往往只有业务描述，缺少可落地的 HTTP 接口契约：路径是否 RESTful、鉴权头怎么写、列表是否分页、错误码是否按端点裁剪，这些若靠口头对齐，返工成本很高。本技能把大模型约束成专业 API 架构师，按统一模板输出可扫描的设计稿，而不是零散的自然语言建议。

技能如何工作

对话开始时，若你未说明粒度，会先确认 仅端点 还是 详细设计；若已在需求里写明，则直接按你的选择执行。

• 仅端点：先列出全部端点，满足快速对齐范围与路由表。
• 详细设计：在端点清单之后，按资源组展开每个端点，结构固定为：方法 + 路径、两行以内描述、头部 表格、请求体（GET/DELETE 无体则省略）、成功响应（含状态码与 JSON 形状）、错误码（按端点选取相关子集，而非机械贴满 7 个）。

输出规则覆盖日常 REST 设计细节：推断或补全主要资源并尽量包含 CRUD 与领域操作；集合用复数名词、关系用嵌套路径（如 /hotels/{id}/rooms）；默认路径前缀 /api/v1/；受保护路由默认 Authorization: Bearer JWT，并按场景标注 X-Api-Key 或公开端点；列表端点带 page/limit/sort/filter 与分页信封。技能还引用 references/domains.md 等领域速查，减少漏资源；可参考 references/testmu_example.md 的结构与示例。

设计交付后会问是否生成 API 文档：若已安装对应文档技能则按其流程用本次设计作输入；未安装则提示安装或提供基本纯文本文档。

适用边界与注意点

• 产出是设计规格，不会替你实现服务端、数据库或 OpenAPI 文件导出（除非另有文档技能衔接）。
• 系统很大（例如超过 8 个资源组）时，技能会建议分节或先聚焦子集；也可通过选项只展开头部、状态码等片段。
• 领域列表来自参考文档与你的描述，复杂业务规则仍需你补充约束，避免模型过度推断。