用途
该技能用于把模糊的集成想法、后端功能或服务边界转化为稳定的 API 契约，供其他技能在其上继续构建。其目标不是生成漂亮的文档，而是：为问题选择正确的 API 风格；定义资源、操作、输入、输出与失败语义；明确兼容性与版本化决策；产出实现、测试和文档可共享的契约产物；在团队固化错误接口之前暴露权衡。
何时使用
- 设计新的 REST API、GraphQL schema 或内部服务契约
- 在不必要破坏客户端的前提下重构现有 API
- 评审命名、资源边界、状态码、分页、过滤、幂等性或错误模型
- 在实现开始前产出 OpenAPI 或 GraphQL SDL 契约
- 评估版本化与向后兼容决策
- 决定 API 应保持 REST、迁移到 GraphQL，还是有意暴露两层
- 为后端、前端、QA 或合作方团队准备可实施的契约包
何时不使用
- 主要任务是构建交互式文档、SDK 文档、入门指南或示例门户：使用 api-documentation
- 主要任务是编写服务端代码、认证中间件、resolver 或持久化逻辑
- 主要任务是数据库规范化、索引或存储模型优化：使用 database-schema-design
- 请求主要是测试规划或契约测试覆盖：使用 backend-testing
- 尚不够清晰、无法诚实定义 API 形态：此时应定义开放问题与设计探针，而非假装确定
使用方式
处理不寻常或高风险 API 工作前，先阅读 references/contract-review-checklist.md 与 references/boundary-guide.md。
步骤 1：框定契约问题。在发明端点前记录设计输入：调用 API 的用户或系统、要完成的业务动作或任务、领域实体与所有权边界、约束兼容性的现有客户端或迁移、敏感性与安全要求、预期规模模式（读、写、扇出、分页、突发性）、请求的产物格式（OpenAPI、GraphQL SDL、端点表或设计备忘）。若请求描述不足，在设计包中明确写出缺失的假设。
步骤 2：有意识地选择接口风格。不要出于习惯默认某种风格。当工作流以资源为中心、缓存/可预测 URL/简单 CRUD 重要、外部客户端需要稳定常规 HTTP 语义、或希望使用 OpenAPI 工具与广泛生态兼容时，优先 REST。当客户端需要灵活字段选择或组合图遍历、前端团队需要减少多屏过度或不足获取、schema 比固定端点列表更适合作为共享契约、或已有/预期有 schema 注册表或破坏性变更检查时，优先 GraphQL。仅当职责明显不同、团队能解释谁消费哪个界面及原因、且能避免重复所有权与漂移时，才优先混合方案。需说明所选风格的理由。
步骤 3：建模资源、操作与边界。REST：定义顶层资源及其所有权边界；选择名词而非动词端点，除非动作端点确实更清晰；保持 URL 结构浅层，除非嵌套资源有明确父子含义；分别列出标准操作与领域特定动作。GraphQL：定义核心类型、关系、查询与变更；避免一个巨大的万能变更面；注明分页、过滤与字段级授权适用位置；识别可能频繁变化的 schema 区域。两种风格均需：标记同步与异步行为；识别幂等与非幂等写入；如相关，指出最终一致性或长任务行为。
步骤 4：定义请求与响应契约。设计契约而非仅快乐路径。包括：请求形态与必填字段；成功响应形态；分页或游标规则；过滤与排序语义；可空性与默认值；字段命名约定；时间戳、ID 与枚举行为；部分更新行为。若 API 同时支持机器对机器与前端客户端，注明响应形态或展开模式差异之处。
步骤 5：设计认证、错误与兼容规则。捕获客户端依赖的操作语义。定义：契约层面的认证模型预期；常见状态码或错误类别；机器可读错误码；重试或幂等预期；弃用与下线行为；兼容承诺：加法安全、破坏性、版本门控或需迁移。此处不完整实现认证，定义契约并在需要时将详细设置交给 authentication-setup。
步骤 6：产出契约产物。选择仍能支持下游工作的最轻量产物。推荐格式：REST 契约与重评审环境用 OpenAPI 大纲；schema 优先的 GraphQL 工作用 GraphQL SDL 草图；早期架构讨论用端点或操作表；形态仍在争论时用设计备忘加风险清单。最小契约包：所选风格及原因；受众或消费者；实体或类型图；操作与请求/响应摘要；认证、错误与版本化说明；开放问题或风险；下游交接。
步骤 7：评审破坏性与交接质量。定稿前检查：现有客户端会否破坏？命名与语义是否一致？分页与过滤规则是否可实现？错误状态与认证失败是否足够明确以供前端、QA 或文档工作？是否意外将契约设计与教程写作或服务端实现混在一起？清晰路由后续步骤：api-documentation 负责已发布文档、教程、示例与文档门户设置；backend-testing 负责契约测试与集成测试规划；authentication-setup 负责具体认证实现；database-schema-design 在存储模型需要单独处理时使用。
输出格式
预期响应形态：API 设计包（名称、风格选择、消费者与主要任务）；资源或类型模型（核心实体与所有权边界）；操作（关键端点、查询或变更的请求与响应摘要）；契约规则（认证、错误、分页与兼容决策）；风险或开放问题（未解决假设或迁移顾虑）；交接（哪些兄弟技能应负责文档、测试、认证或存储后续）。
示例
示例 1：面向合作方集成的公共 REST 契约。输入：为电商供应商设计面向合作方的订单状态 API，需要稳定轮询、后续 webhook 回退与谨慎版本化。预期形态：选择 REST，因为外部合作方需要可预测的 HTTP 语义；清晰定义 orders 与 order-events；指定状态转换、按更新时间过滤与版本化规则；包含机器可读错误与幂等 webhook 注册说明；交接给 api-documentation 编写合作方文档与示例。
示例 2：面向仪表盘客户端的 GraphQL schema。输入：需要项目、部署、事件与告警的仪表盘 API，UI 视图多且 REST 持续过度获取。预期形态：论证 GraphQL 适合灵活客户端读取；定义核心类型与查询或变更边界；注明分页与字段或查询级授权；标记 schema 热点与破坏性变更评审需求；交接给 backend-testing 做契约检查、api-documentation 写示例查询。
示例 3：当任务实为文档发布时路由离开。输入：用 Swagger UI 记录我们的认证 API 并编写前端集成示例。预期形态：识别已发布文档属于 api-documentation；本技能仅聚焦底层契约问题；不假装文档发布与 API 设计是同一工作。
最佳实践
将 API 契约视为产品边界，而非仅代码便利。将设计决策与文档发布分离。记录假设与开放问题，而非假装确定。优先加法演进与显式弃用，而非意外破坏性变更。选择 REST 与 GraphQL 时保持理由可见。使用让下游团队可行动的最小产物。有意交接给相邻技能，而非膨胀本技能。
参考
本地：references/contract-review-checklist.md 本地：references/boundary-guide.md OpenAPI Specification：https://swagger.io/specification/ GraphQL Best Practices：https://graphql.org/learn/best-practices/