API设计专家

你要解决的具体问题

当你准备新增一组接口，常见痛点会集中在：

• 资源边界不清：实体、关系和 URL/字段命名靠经验拍板，后续调用方反复来问。
• 分页与错误格式随意：有的接口用 page/size，有的用游标；错误体有的返回 {code,message}，有的直接抛出堆栈或裸字符串。
• OpenAPI 与实现脱节：文档写完就没人维护，示例缺失，消费方只能试错。
• 版本策略缺失： /v1、 /v2 的判定规则模糊，兼容性承诺不明，升级时只能连带改调用方。

技能如何工作

这个技能把 API 设计拆成一条可执行的流程，核心能力包括资源建模、OpenAPI/SDL 规范落地、版本策略、分页与统一错误格式设计，最终产出结构化工件 ApiDesignSpec。

关键步骤：

• 明确消费者：先定义谁调用、有什么 SLA、必须保持哪些兼容性约束，避免后续返工。
• 资源建模：把实体和关系映射成 URL、方法、字段命名和状态码，而不是直接堆路由。
• 规范落地：用 OpenAPI 或 GraphQL SDL 承载设计，并附带示例，让文档与实现可对照。
• 自检：核对幂等性、分页边界、错误码统一性、版本切换规则，减少隐藏坑。
• 输出工件：返回 ApiDesignSpec，字段包含 name、 style、 resources、 versioning、 notes，便于下游接 review 或生成文档。

适用边界与注意点

它适合 REST 或 GraphQL API 设计、OpenAPI 规范编写、版本/分页/错误标准制定。输入可以是自然语言需求和约束，也可以是已有的 ApiDesignSpec 做二次优化。

不适用的场景：

• 纯前端调用封装，更适合对应框架专家。
• 不替代组织级 API 治理委员会的最终决策，它帮你产出可评审的草案，而不是替你拍板公司级标准。

使用时建议先把消费者、兼容约束和失败场景讲清楚，再让它逐步生成资源模型和规范；否则工件会缺少关键上下文，后续仍需要人工补齐。