用途:在架构边界已定义后,规范组件间或面向外部消费者的稳定 API 契约。API 是契约,发布后难以更改,需要在设计阶段谨慎处理。
主要能力:选择 API 风格(REST、GraphQL、gRPC、事件驱动,按架构与消费者边界而非流行度选择);把领域实体映射为 API 资源(使用名词,如 GET /orders,动作走 POST /orders/{id}/cancel,命名用复数名词与 kebab-case);定义各资源的 CRUD 操作、请求响应模式与状态码;规划版本化策略(URL /v1/orders、请求头 Accept: application/vnd.api+json;version=1,或仅做加法式演进);统一错误响应格式;用 OpenAPI 或 protobuf 在实现前写契约规范,便于契约测试与客户端代码生成;明确记录契约假设、暂缓字段与未决问题。
输入:architecture-doc 与 requirements-doc 为必需,domain-model 为可选增强。
输出:api-contract 与 api-documentation。
质量门槛:契约需以 OpenAPI/protobuf/GraphQL schema 表述;命名、错误处理、分页一致;版本化策略有文档;逐端点说明认证授权;定义向后兼容策略。
反模式:一次页面渲染需多次调用的啰嗦 API;泄露内部 ID、数据库列名或内部服务结构;列表端点不分页;无版本化的破坏性变更;把未决的同步、发布或兼容问题固化为契约行为而不加标注。
限制:架构或需求仍存在同步时机、旧版读取、租户兼容、授权边界等不确定项时,应作为契约假设或开放问题记录,而非静默硬编码;具体安装方式与价格资料未提供。