糟糕的 API 契约就是一笔三年的迁移债，你要靠一张张工单慢慢还。每一次字段改名、每一个 200 里偷偷加进去的字段、每一种不一致的分页方式，都会顺着 SDK 和客户集成放大到所有下游。下面这 15 个 Prompt 让 AI 像外部消费者那样走一遍你的契约：盯出说谎的状态码、没有机器码的 500、藏在”minor”版本里的 breaking change，以及 OpenAPI spec 与服务器真实返回之间的偏差。想顺手把端点背后的存储层也压一压，可以配合 数据库 schema 评审 Prompt。
一句话总览
- 把这些 Prompt 丢进一个长上下文模型，连同 spec 和 5 到 10 组真实请求 / 响应一起喂进去。截至 2026 年 6 月，最强的两个选择是 Claude Opus 4.7（1M token 上下文，SWE-bench Verified 第一，87.6%）和 Gemini 3.1 Pro（同样 1M，价格最低，每 1M token $2/$12）。两者都能一次吞下完整的 OpenAPI 或 GraphQL SDL。
- AI 评审是一次快速初筛，不是关卡。要搭配确定性工具：REST 用
oasdiff做 breaking change 检测（450+ 条规则，支持 OpenAPI 3.0 与 3.1，有 GitHub Action），GraphQL 用graphql-inspector做 schema diff，它会把每条变更标成 breaking / dangerous / safe。 - 错误体统一到 RFC 9457 Problem Details（
application/problem+json）。下面第 2、3 个 Prompt 就是专门核这一点。 - REST 和 GraphQL 要施加的压力不同。状态码与可缓存性会坑 REST；N+1 扇出、字段级鉴权、query-cost 限制会坑 GraphQL。文末那张拆分表说明各自该重点压哪里。
这套 Prompt 适合用在哪
- REST 设计评审
- GraphQL schema 评审
- 公开 SDK 上线前
- B2B 集成契约
- 向后兼容审计
1. 端点命名一致性
适用于： REST
下面是 REST 端点列表。请评估命名一致性：(a) 名词 vs 动词；(b) 复数 vs 单数；(c) 嵌套深度；(d) 版本风格。标出不一致并提议规范化命名。
{粘贴}2. 错误模型审计
适用于： REST + GraphQL
下面是 API 的错误模型：{粘贴示例}。请评估：(a) 错误码是否稳定；(b) 是否同时含 human message 与机器码；(c) 是否泄露内部细节；(d) 是否支持重试提示；(e) 距离 RFC 9457 Problem Details 有多远（type/title/status/detail/instance，application/problem+json）。请提议改进，并给出一份符合 RFC 9457 的结构。3. 状态码语义
适用于： REST
下面是 10 个端点及其返回状态码。逐条核：(a) 语义是否正确（如 404 vs 410 vs 422）；(b) 跨端点是否一致；(c) 客户端是否易误读。标出问题并提议修复。
{粘贴}4. 版本化策略评审
适用于： REST + GraphQL
我现在的版本化方式：{粘贴}。结合我消费者画像 {粘贴} 评估：(a) 当前方案的优缺点；(b) 与其他方案对比；(c) 未来应采用哪种。5. 向后兼容 diff
适用于： REST + GraphQL
下面是当前 spec 与新版 spec。请找出所有 breaking change（字段删除 / 类型变更 / 新增必填字段 / 错误形状变化）。每条给：严重度、谁会坏、缓解（deprecation 期 / 双写 / 版本）。把你的清单与自动 diff 工具（OpenAPI 用 oasdiff，GraphQL 用 graphql-inspector）会标出的结果对一遍，并指出那些工具会漏掉、因为是语义而非结构层面的问题（例如字段还在但含义变了）。
{粘贴}6. 分页一致性
适用于： REST
下面是列表端点及其分页方式 {粘贴}。请评估：(a) cursor / offset / page-token 是否一致；(b) total-count 语义；(c) 高基数列表是否仍 OK。提议统一模式。7. GraphQL schema 异味
适用于： GraphQL
下面是 GraphQL schema。请列 top 5 异味：(a) 过度可空字段；(b) 循环类型；(c) 缺 input 类型；(d) Connection 滥用；(e) over-fetch 风险。每条 1 行修复。
{粘贴}8. 请求 / 响应契约缺口
适用于： REST + GraphQL
下面是 spec + 5 个请求示例 + 5 个响应示例。找出 spec 与现实的不一致——响应里有 spec 没写的字段、spec 写了但从不返回、可选 / 必填不一致。
{粘贴}9. 幂等键审计
适用于： REST
下面是需要支持重试的 POST 端点。逐个核：(a) 是否有幂等键；(b) 去重窗口；(c) 同键不同体如何处理；(d) 重复检测怎么暴露给客户端。10. 限流与配额
适用于： REST + GraphQL
下面是当前限流行为。请评估：(a) 限流维度（IP / key / resource）；(b) 是否有 Retry-After header；(c) 是否有 429 body schema；(d) 文档与实际是否一致。提议文档 + 行为修复。
{粘贴}11. SDK 体验评审
适用于： REST
我正基于 OpenAPI spec 生成 SDK。下面是 5 个代表端点。请评估在 {TypeScript / Python / Go} 中体验：类型是否干净、方法名是否合理、required / optional 是否清楚。提议 spec 修改以改善 SDK。
{粘贴}12. Webhook 契约评审
适用于： REST + GraphQL
下面是我的 webhook payload + headers。请评估：(a) 签名方案；(b) 防重放；(c) event ID + version；(d) 顺序语义；(e) 重试行为。提议改善以让消费者更轻松。
{粘贴}13. Connection 风格分页评审
适用于： GraphQL
下面是我 schema 里的 Relay 风格 Connection 字段。请评审：(a) 每个 Connection 是否都暴露 edges、nodes、pageInfo；(b) pageInfo 是否含 hasNextPage 和 endCursor（支持反向分页时还要 hasPreviousPage / startCursor）；(c) cursor 是否不透明、跨次查询稳定；(d) 所有分页字段是否使用同一套 Connection 约定（参数名一致：first / after / last / before）；(e) 是否有应该改成 Connection 的裸 list 字段。标出不一致并提议修复。
{粘贴 schema}14. resolver 设计中的 N+1 检测
适用于： GraphQL
下面是 {粘贴类型} 的 resolver 定义。请逐字段走查。每个字段问：(a) 是否会触发 per-parent 拉取；(b) 哪里需要插入 DataLoader / 批处理 loader；(c) 字段看似无害但嵌套查询下会扇出（例如：author 列表 -> books -> reviews）。列出所有 N+1 风险，以及修复用的 DataLoader key 形状。
{粘贴 resolver}15. resolver 字段级鉴权
适用于： GraphQL
下面是带鉴权规则注释的 GraphQL schema。请评审：(a) 鉴权是 per-field 还是只 per-query；(b) 哪些 type-level 规则正确，哪些字段需要更细粒度；(c) 哪些字段会通过 partial-success 响应泄露数据；(d) 规则是否兼容 persisted query（不要有运行时参数依赖、行为不可预测的检查）；(e) 是否有字段鉴权依赖父级上下文但 resolver 拿不到。请输出一份 per-field 鉴权矩阵。
{粘贴 schema + 鉴权}REST vs GraphQL 评审差异点
REST 和 GraphQL 评审有部分共同检查（版本化、错误模型、契约漂移），但生产中真正会坑你的点不同。评审时分清侧重：
- 状态码 / 可缓存性: REST 评审非常在意 4xx vs 5xx 语义、Cache-Control header、CDN 行为。GraphQL 几乎一律返回 200、错误塞在 body，这一类基本不适用。
- N+1 与 resolver 成本: GraphQL 独有。REST 端点本来就是 eager 拉数据；GraphQL 里嵌套查询缺 DataLoader 就会无界扇出。
- 字段级鉴权: REST 在端点层鉴权；GraphQL 必须每个字段都鉴权。单看安全的字段，从嵌套路径过去可能就漏数据。
- persisted query 与成本限制: GraphQL 独有。公开 GraphQL 需要 persisted query（也叫 trusted documents：预先登记好的操作白名单，客户端按 ID 引用）或 query-cost 限制来防恶意嵌套查询。这是 Apollo GraphOS 与 GraphQL Foundation 一致推荐的生产做法。REST 则是按端点限流。
- 分页形状: REST 容许多种风格（offset、cursor、page token），只要每个端点自洽。GraphQL 默认全 schema 都遵守 Relay Connection 规范。
AI 能抓到什么、抓不到什么
这些 Prompt 是给资深评审者加的杠杆，不是替代品。在真实 spec 上跑下来，分工很稳定：
| AI 比较靠谱 | AI 不太靠谱 |
|---|---|
| 跨大量端点的命名不一致 | 422 还是 409 是否贴合你的业务语义 |
| 揪出一律 500、缺机器码 | 了解你真实的消费者及其容忍度 |
| 从 diff 里列出结构性 breaking change | 字段含义在业务层面变了 |
| 标出缺 DataLoader / N+1 候选 | 生产中真实的查询模式及其成本 |
| 起草符合 RFC 9457 的错误结构 | 某个字段的数据是否涉及合规敏感 |
先用 AI 跑一遍做分流，再把高严重度结论交给真人复核，并在 CI 里用 oasdiff 或 graphql-inspector 验证 breaking change，确保没有结构性问题悄悄溜过去。
常见问题
应该把这些 Prompt 喂给哪个模型？ 截至 2026 年 6 月，用 1M token 的模型，好让整份 spec 加示例一次塞进去：Claude Opus 4.7（SWE-bench Verified 第一，87.6%）或 Gemini 3.1 Pro（价格最低，每 1M token $2/$12）。在 ChatGPT Plus 里，应用内上下文大约 320 页；遇到很大的 OpenAPI spec，可能需要 $200 的 Pro 档或走 API 才能拿到完整窗口。
这些能替代 oasdiff 和 graphql-inspector 吗？
不能。那两个是确定性工具，应该放进 CI 当硬关卡；oasdiff 覆盖 OpenAPI 3.0 与 3.1 的 450+ 类 breaking change，graphql-inspector 会把每条 schema 变更标成 breaking / dangerous / safe。Prompt 补的是工具做不了的语义判断，比如字段还在但含义变了。
Prompt 应该对齐哪种错误格式？
RFC 9457 Problem Details（媒体类型 application/problem+json），它在 2023 年 7 月取代了 RFC 7807。它把 type、title、status、detail、instance 标准化，并预留扩展位放稳定的机器码。第 2、3 个 Prompt 会核这一点。
为什么 REST 和 GraphQL 要用不同 Prompt？ 失效模式不同。REST 评审围绕状态码语义和可缓存性；GraphQL 评审围绕 N+1 resolver 扇出、字段级鉴权和 query-cost 限制。上面那张拆分表说明各自的重点。
应该粘贴多少个示例？ 连同 spec，粘 5 到 10 组真实请求 / 响应。契约漂移（第 8 个 Prompt）只有在模型能把 spec 声称的和服务器实际返回的对照起来时才会暴露，造数据反而会把你要找的 bug 藏起来。