api-contract-first

API Contract First

Triggers

• architect-agent 启动 / /design 命令（写契约）
• /build-api / /build-web main thread 加载 backend-development / frontend-development skill 时只读链入（契约消费方，M6.4 起 main thread 直接执行而非 subagent）

Core Principles

1. 契约先于代码：没有 lint 通过的 OpenAPI，不允许动 web/ 或 server/
2. 契约是唯一真相源：UI 文案、错误提示、日志格式以外的所有接口约定必须出自契约
3. 契约变更 = 事件：每次契约变更在 docs/arch.md 的 ADR 章节追加一条，说明原因、影响面、兼容策略

Design Rules

URL 结构（DDT 标准）

# 资源名：名词、复数、小写、kebab-case
GET    /api/v1/users
POST   /api/v1/users
GET    /api/v1/users/:id
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 子资源（所有权关系）
GET    /api/v1/users/:id/orders

# 动作（谨慎使用，限非 CRUD）
POST   /api/v1/orders/:id/cancel

字段约束

• 所有字段含 type / required / description / example
• 所有错误响应用枚举（error.code）+ 人类可读 message，避免只有数字码
• 分页统一：page + pageSize + total，或游标 cursor + nextCursor 二选一，全局一致
• 幂等操作必须声明 Idempotency-Key header
• 所有时间字段 ISO-8601 UTC

HTTP 状态码（强制）

200 OK                    — GET/PUT/PATCH 有响应体
201 Created               — POST 成功（含 Location header）
204 No Content            — DELETE/PUT 无响应体
400 Bad Request           — 格式错误、缺少必填字段
401 Unauthorized          — 未认证
403 Forbidden             — 已认证但无权限
404 Not Found             — 资源不存在
409 Conflict              — 重复创建、状态冲突
422 Unprocessable Entity  — 语义非法（格式合法但业务无效）
429 Too Many Requests     — 限流（含 Retry-After header）
500 Internal Server Error — 不暴露内部细节

分页（二选一，全局保持一致）

• Offset（小数据集 < 10K / 管理后台）：?page=2&pageSize=20
• Cursor（大数据集 / 无限滚动）：?cursor=<opaque>&limit=20，响应含 nextCursor

版本化策略（ADR）

1. URL Path 版本（推荐）：/api/v1/ → /api/v2/
2. 不破坏性变更不需要新版本：
   - 新增可选字段、新增端点、新增可选查询参数
3. 破坏性变更必须新版本：
   - 删改字段名/类型、改 URL 结构、改认证方式
4. 废弃策略：宣告（6 个月） → Sunset header → 410 Gone

Do

• 用 npx @redocly/cli lint 跑 schema lint，lint 必须通过后才能进入实现阶段
• 用 openapi-typescript 或等价工具生成前端 types
• 用 openapi-generator 或等价工具生成后端路由骨架
• 每个 endpoint 含完整的 request / response / error 示例（见 templates/api-contract.template.yaml）