Vibe Coding API 合同：用请求响应示例消除前后端猜测

前端 Prompt 写“调用创建分析任务的 API”，后端 Prompt 写“提供 POST /analyses”，两边都能生成合理代码，却可能在 projectId 放路径还是正文、成功返回 200 还是 202、错误是字符串还是对象、重复点击是否创建两份任务等细节上完全不同。靠最后联调修补，会把偶然实现变成事实合同。

API 合同描述消费者能观察的行为，而不是控制器内部结构。OpenAPI 可以表达路径、操作、参数、响应和 Schema，JSON Schema 提供实例验证词汇，HTTP 语义由 RFC 9110 约束；工具能校验文档格式，却不能替团队决定业务状态和副作用。因此要把数据模型与业务不变量中的规则映射成稳定的请求、响应与领域错误。

先冻结一个操作的完整边界

从MVP 垂直切片挑一个主路径操作，记录：调用者和所需权限；method 与 path；请求 headers、path/query/body；成功和所有预期失败；是否有副作用；超时或断线后能否安全重试；响应中的身份与时间语义；速率限制和可观察追踪 ID。

例如创建反馈分析任务，不要只给字段表，而要给成对样例：

POST /v1/projects/prj_42/analyses HTTP/1.1
Content-Type: application/json
Idempotency-Key: 7f4d8f0e-...

{
  "sourceUploadId": "upl_81",
  "mode": "theme-clustering",
  "maxThemes": 8
}

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /v1/analyses/an_93

{
  "id": "an_93",
  "status": "queued",
  "createdAt": "2026-07-30T12:30:00Z"
}

202 表示请求已接受处理，不表示分析成功；消费者通过 Location 或合同指定的查询操作获取终态。若系统实际在请求内完成，就用符合实际语义的成功码，不要因为示例用了 202 就照抄。时间均说明格式、时区和精度，ID 只声明不透明字符串，客户端不得从前缀推断权限。

每个示例都必须通过对应 Schema，但 Schema 不应只从示例自动推断。写清 required、允许空值、长度和值域、未知字段策略。请求中 maxThemes: null、字段缺失和 0 是否相同必须明确。响应新增可选字段的兼容性也取决于客户端是否遵守忽略规则，需要契约测试而不是口头保证。

错误要让用户和程序都能行动

规定统一错误 envelope，例如：

{
  "error": {
    "code": "UPLOAD_NOT_READY",
    "message": "The upload is still being processed.",
    "requestId": "req_f18",
    "details": {"uploadId": "upl_81"}
  }
}

code 是程序分支使用的稳定标识，message 是安全的默认说明，字段级错误有确定路径表达，requestId 用于支持排查。堆栈、SQL、供应商响应和秘密不进入客户端。列出至少四类反例：结构不合法、身份失效、无权访问、业务状态冲突；再根据操作补资源不存在、速率限制和服务不可用。

状态码与错误 code 分工：HTTP 状态表达通用协议语义，领域 code 细分恢复动作。不能所有失败都返回 200，也不要让同一 409 在不同实现中随机代表版本冲突或重复记录。UI 状态矩阵直接把 code 映射到文案、保留数据和下一动作，未知 code 落到安全的通用失败并上报，而不是当成功解析。

资源存在性是否对无权限用户隐藏，需要统一威胁决策。服务若选择返回 404，日志和指标仍可保留内部拒绝原因；前端不能用另一个列表端点绕过隐藏。认证与授权每次在服务端执行，OpenAPI 中的 security requirement 只是合同声明，不是执行机制。

明确重试、并发和异步语义

有副作用的请求必须说明重复提交。若支持 Idempotency-Key，规定作用域、有效期、请求摘要比较和重复响应：相同 key 加相同正文返回同一结果；相同 key 加不同正文返回稳定冲突；处理中重放返回同一任务身份。客户端超时不代表服务端未执行，不能自动换新 key 再发。

更新操作规定并发控制，例如 If-Match 携带版本 ETag；版本过期返回 412 Precondition Failed，响应不静默覆盖。分页说明游标稳定性、排序键和终止条件；异步任务说明状态集合、允许转换、轮询退避、取消行为和结果保留期。这些语义必须和数据库事务一致，不能只存在于 SDK。

让一份合同驱动两端验证

先评审 OpenAPI 和示例，再并行生成客户端与服务端。服务端测试对每个 example 发真实请求并验证响应；客户端测试用同一套响应 fixture 覆盖成功与失败；合同 lint 阻止缺少 operationId、未声明响应或 Schema 放宽。Mock 只能帮助开发，不能由同一生成器既产出实现又证明实现正确。Agent API 契约兼容门可在公共接口上增加消费者兼容验证。

在 DoD 中要求：文档、实现和 fixture 的版本一致；所有主路径状态都有例子；未知字段、错误和超时测试已运行；日志不含敏感正文；变更已分类。Definition of Done 与交付边界管理完成证据，规格变更日志与重新验收处理已冻结合同的修改。

一份好的 API 合同让前端不必阅读后端源码，让后端不必猜组件需要什么，也让 Agent 无法用“合理默认”填掉业务空白。先用可运行示例把成功、失败和重试说清，再生成代码，联调就从发现需求变成验证双方是否遵守同一个决定。