糟糕的 API 契约就是一笔 3 年迁移债——每一次字段改名、200 里偷偷加字段、分页方式不一致，都会通过 SDK 放大到所有下游。下面这些 Prompt 让 AI 像外部消费者一样走一遍：盯出说谎的状态码、没机器码的 500、藏在”minor”版本里的 breaking change、以及 OpenAPI 与真实返回之间的偏差。配合 数据库 schema 评审 Prompt 把存储层也压一压。
这套 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) 是否支持重试提示。提议改进。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 期 / 双写 / 版本）。
{粘贴}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 白名单或 query-cost 限制来防恶意查询；REST 是按端点限流。
- 分页形状: REST 容许多种风格（offset、cursor、page token），只要每个端点自洽。GraphQL 默认全 schema 都遵守 Relay Connection 规范。
容易踩的坑
- 命名跨端点不一致
- 一律 500 + 无错误码
- Breaking change 没 deprecation 期
- 不同端点分页方式不同
- 写操作没幂等键
- Spec 与实际逐渐漂移