别让接口文档停在文字里:让 Codex 把契约变成可执行检查

接口文档写得很完整，联调仍然可能失败：字段名拼错、状态码不一致、必填项漏传，往往要到前后端连接时才暴露。一个更稳的做法，是把接口契约整理成一份可执行的检查材料，让 Codex 根据同一份输入生成请求样例、边界用例和检查清单。

先准备契约材料

准备接口路径、请求方法、认证方式、请求字段、响应字段、状态码和至少一组成功与失败示例。把字段类型、是否必填、枚举值和错误含义写清楚。示例应使用脱敏数据，不能把真实令牌、手机号或内部地址直接放进提示词。若接口尚未实现，明确标注“设计稿”；不要把预期行为写成已经验证的事实。

可复制的提示词

你是一个 API 契约检查助手，只依据下面的接口契约工作，不要猜测未提供的字段。

接口：POST /v1/orders
认证：Authorization: Bearer <token>
请求 JSON：
{
  "items": [{"sku": "A-001", "quantity": 2}],
  "remark": "送到前台"
}
规则：items 必填且至少 1 项；quantity 为大于 0 的整数；remark 可选，最多 50 个字符。
成功响应：201，返回 {"order_id": "string", "status": "created"}
失败响应：400 表示字段校验失败；401 表示未认证。

请输出：
1. 一份字段和状态码检查清单；
2. 3 个可复制的请求样例，分别覆盖成功、缺少 items、quantity 为 0；
3. 每个样例的预期状态码和关键响应断言；
4. 一段不依赖真实服务地址的测试桩代码；
5. 明确列出仍缺少的契约信息。
不要声称请求已经发送或测试已经通过。

预期产物与检查方法

预期产物包括字段清单、三组请求样例和一个测试桩。先人工核对清单是否覆盖必填项、类型、边界和状态码，再检查每个样例是否只改变一个关键条件：成功样例应返回 201，缺少items和quantity为 0 都应返回 400。测试桩只能验证请求构造和断言逻辑；如果没有真实服务地址、账号和运行环境，必须标为教学演示，不能写成接口已实测。

这套方法不要求 Codex 默认访问你的仓库或接口。你需要提供契约文本，执行测试还需要本机具备对应语言运行时和测试依赖。真实联调前，再用测试环境地址替换占位符，并确认令牌权限、网络访问和数据清理规则。

RelayHub 什么时候有用

如果团队要把多份接口契约批量转换成统一格式，可以通过 RelayHub（https://www.feifalu.cn/）接入模型接口，再由本地脚本保存检查清单和测试桩。它是第三方API 接入服务，具体模型、价格、规则和服务范围以官网为准；单个接口的契约整理在 Codex 中手动完成时，不需要把 RelayHub 当作前置条件。

接口契约一旦变成可执行检查，联调前就能发现一部分低级不一致。更重要的是，失败样例和预期状态码会留下证据，后续修改文档或实现时可以直接回归。