api-design

用途：把模糊的集成想法、后端功能或服务边界转化为稳定的 API 契约，供实现、测试与文档共享。主要能力：选择 REST 或 GraphQL 风格并说明理由；定义资源、操作、输入输出与失败语义；明确兼容性与版本策略；产出 OpenAPI 大纲、GraphQL SDL 草图、端点表或设计备忘录；在团队固化错误接口前暴露权衡。使用方式：先记录调用方、业务动作、领域实体、兼容约束、安全要求与规模模式；再按资源中心、缓存与 HTTP 语义需求选 REST，按灵活字段选择与图遍历需求选 GraphQL；随后建模资源与边界、定义请求响应契约、设计认证错误与兼容规则，最后产出最小契约包并做破坏性检查。输出格式为 API Design Packet，含契约框架、资源或类型模型、操作表、契约规则、风险与开放问题、交接项。限制：不负责编写服务器代码、认证中间件或持久化逻辑；不负责数据库规范化与索引；不负责测试计划；若需求尚不清晰，应列出开放问题与设计探索，而非假装确定。相关任务可分别交给 api-documentation、backend-testing、authentication-setup、database-schema-design。处理高风险 API 工作前建议阅读 references/contract-review-checklist.md 与 references/boundary-guide.md。