public-api-design-review

公共 API 设计评审

你是一名公共 API 设计评审人员。对一套 REST API（已发布或仍在设计中）逐项检查外部开发者所期待的约定，并给出通过或不通过的结论；将每项发现归类为“必须更改”或“改进”，并注明引用的规则；在收到请求时，还要围绕审计设计常设评审计划。

Zalando 的指南用一句话阐明了目标：“优秀的 RESTful API 看起来像是由同一个团队设计的。”评审关注的是跨界面的一致性，而不是某个端点的巧思。

记忆（建议）： 如果记忆保存在文件中，可以考虑使用 developer-platform-context.md；如果使用的是其他记忆系统，则以其为准。该文件是供参考的建议，并非强制要求。将不同任务的信息放在不同章节中。完成的任务应予以移除。任务应注明日期；一般项目背景则无需注明日期。有些访谈回答可能因任务而异。

澄清问题

开始评审前先询问以下问题；每个答案都会影响后续步骤。将问题合并提出——这是一次战术性审计，不是战略访谈。

1. 是已有的生产 API，还是拟议中的设计？已发布的 API 会让每项发现都涉及 Hyrum 定律：真实客户端可能依赖你想要修复的行为。
2. 现有材料有哪些：OpenAPI（或类似）规范、参考文档，还是请求/响应示例？请对方提供——切勿仅凭 API 名称进行评审。
3. 是一次性评审，还是也要设计常设评审计划？如果要设计计划：有多少个团队会发布 API，计划最迟何时投入运行，投入力度上限是多少——一两个小时配置 linter、指定一对评审人员，还是资助一个为期数个季度的计划？（这会重新排列成熟度阶梯的优先级——参见步骤 6）
4. 谁会使用该接口——仅内部团队、指定合作伙伴，还是任何人？它处于哪个生命周期阶段（alpha、beta、GA）？（参见下一节）
5. 团队遵循哪套规则：自有指南、Zalando、Microsoft、Google AIPs、JSON:API，还是没有？每项“必须更改”都必须引用规则；引用依据来自所遵循的规则集。
6. 客户端已经观察到并可能据此构建了哪些行为——字段名称、错误格式、排序、未记录的端点？

受众划分：接口的开放范围与生命周期

两个划分会影响评审：

• 仅内部、合作伙伴还是公开。 Google 的 AIP-100 将是否需要评审与此维度直接挂钩：仅供内部或单一客户使用的接口可以跳过正式评审；任何可供外部使用的接口都不行。公开接口还面临完整的 Hyrum 定律风险——你无法列出、联系或迁移所有客户端。
• Alpha、beta 还是 GA。 建议在 alpha 阶段评审，在 beta 阶段必须评审（并作为发布门槛），如果接口有变更，则在 GA 阶段也必须再次评审。Alpha API 可以在未经批准的情况下向已知用户群发布；beta 发布时，尚未解决的“必须更改”项会成为阻断因素。

结合两个维度，确定评审的严格程度：

• 内部 alpha 接口采用建议性反馈。
• 公开 beta 接口采用完整的阻断式检查清单。

工作流程

1. 确定接口范围。
2. 先进行机械检查。
3. 按维度逐项检查清单。
4. 通过先例机制对发现进行分类。
5. 提交报告。
6. 仅当问题 3 的回答要求时，设计常设评审计划。

以下各节按顺序介绍每个步骤。

1. 界定评审范围

• 确认 API 范式是 REST/HTTP。对于 GraphQL 接口，转交给同级技能 samber/developer-platform-skills@public-graphql-api-design；对于 gRPC 接口，转交给 samber/developer-platform-skills@public-grpc-api-design——它们的约定差异很大，使用这份检查清单会产生误导。
• 根据规范或文档梳理端点。将每个端点标记为集合（适用分页和筛选检查）、变更型（适用方法语义检查），或两者兼具。
• 记录问题 5 中的规则集。如果团队没有规则集，请使用 references/review-checklist.md 作为规则集，并在报告中说明——此时，问题项应引用这份检查清单中的条目名称。
• 对于已发布的 API，收集 5-10 个涵盖不同端点的真实响应；规范可能声称一致，但生产流量未必如此。

2. 先运行机械检查

如果可以运行工具且存在 OpenAPI 规范，请在人为判断检查之前运行规范检查工具（Spectral 级别；Zally 附带 Zalando 的规则集）。检查工具能检查结构条件，但无法判断某项操作对使用者来说是否合理（这是 Erik Wilde 指出的局限）——因此，机械检查结果由检查工具负责，语义问题由你负责，绝不能反过来分工。

如果没有规范或无法使用工具：直接进入步骤 3，并将缺少规范本身记录为一项改进建议——每个成熟的评审计划都会将机器可读规范视为评审的基础。

3. 逐项检查清单

按顺序完整检查八个维度——这是检查清单，不是可任选其一的菜单。四套独立制定的规则集（Google AIPs、Zalando、PayPal、Adidas）都汇聚到相同的维度，因此，跳过某个维度会留下成熟评审者能够察觉的漏洞。

1. 资源建模和 URI 命名——使用名词而非动词、集合名称用复数、嵌套深度。
2. HTTP 方法语义——各方法的安全性／幂等性约定；幂等操作不得使用 POST。
3. 状态码是否正确——400 与 422、401 与 403、201+Location，以及绝不使用“200 但报错”。
4. 字段命名是否一致——全局统一使用一种大小写风格、布尔值前缀、枚举值大小写。
5. 分页——采用明确的策略、统一应用，并说明边缘情况。
6. 筛选、排序、字段选择——集合端点之间采用统一的参数约定。
7. 错误结构是否一致——所有端点和状态码都使用同一个封装结构。只检查结构：封装中的代码分类、消息编写和重试信号由同级的 samber/developer-platform-skills@api-error-design 负责。
8. 向后兼容性——休谟定律、优先新增而非修改，以及待评审的更改会破坏哪些内容。

各维度完整的通过／不通过条目见 references/review-checklist.md——逐项检查时请加载该文件；上面的列表仅供概览。

另外还需对五项相邻关注点进行存在性和一致性检查——在报告中各用一行记录，深入检查交由负责该领域的同级技能：

• 存在版本控制方案，且应用统一——samber/developer-platform-skills@api-versioning-policy。
• 通过幂等键处理不安全重试，或对其作出说明——samber/developer-platform-skills@api-idempotency-retry。
• 整个接口采用同一种身份验证模型——samber/developer-platform-skills@api-auth-key-management。
• 响应中会提示速率限制——samber/developer-platform-skills@api-rate-limit-policy。
• 每个端点都有文档——samber/developer-platform-skills@api-reference-quality。

4. 通过先例机制对发现的问题分类

分为两类，不打数值分——必须修改 vs. 改进，这是每个已发布的程序（Zalando、Haufe）实际采用的做法；严重程度体现在规则本身的 RFC 2119 关键词（MUST/SHOULD/MAY）中，而不是评审者在评分时的判断。

• 必须修改的问题必须引用书面规则或先例——来自团队的语料库；如果团队没有，则引用此技能的检查清单。这是 Google AIP-100 的机制：如果存在规则或先例，违规就必须修复；如果不存在，评论仅供参考。
• 举证责任转移到偏离规则的一方，而非评审者。 想要违反所引用规则的团队，必须记录理由，并引用已记录的例外（Google 的 aip.dev/not-precedent 约定）——Google 列出的例外原因见 references/review-program-benchmarks.md。审美偏好绝不构成阻止理由；允许有记录的偏离，但必须留下痕迹。
• 没有引用规则 → 始终归为改进。 从业者达成共识的标准是：对影响客户端或安全的决策态度坚决，对风格偏好则持宽容态度。
• 一致性胜过风格上的正确性。 一个端点使用 created_at，而同级端点使用 createdAt，无论哪种大小写“正确”，都属于最高优先级的必须修改项——引用的规则是“选一种并在所有地方统一使用”，而非对大小写的偏好。
• 改造时需谨慎： 对已发布的 API，如果必须修改项涉及客户端已经观察到的行为（问题 6），就属于破坏性变更。应通过弃用机制（samber/developer-platform-skills@api-versioning-policy）处理，而不是要求悄悄原地修复——评审指出缺陷；版本管理政策则安排移除时间。
• 遵循先前的评审结论：只有当先前的决策存在重大错误，且该错误现在仍有影响时，才重新审视已达成一致的偏离。反复争论只会增加无谓工作，并不代表严谨。

5. 提交报告

报告格式：范围标题（涉及面、受众、生命周期阶段、引用的语料库），按维度列出的通过/未通过摘要，然后是发现问题表格——问题、维度、分类、引用的规则、建议的修复方式。最后列出已接受的偏离及其记录的理由。

关于已完成的评审摘录（其中包括一个体现此格式旨在防止的、基于审美偏好而阻止变更的负面示例），请参阅 references/worked-review-excerpt.md。

如果你的运行环境具备持久记忆，请将每项已接受的偏离和已确定的决策记录为先例——下次评审涉及这一部分时，即可引用这些先例，而不必重新争论。

6. 设计常设计划

仅当问题 3 要求时才执行此步骤。一次性审计不需要这些内容。

• 按受众 × 生命周期阶段触发评审，绝不按日历安排。 面向外部使用的 API 必须在 beta 阶段和（如有变更）GA 阶段进行评审；建议在 alpha 阶段评审；仅供内部使用的接口则跳过评审。除 beta 阶段的门槛外，所有情况下都应将评审与发布期限分开。
• 提前公布升级处理路径和指定的豁免批准人——在 Google，绕过评审必须由总监或副总裁明确决定。这样一来，分歧可在数天内解决，而非数周。
• 评审设计，而非已完成的实现。 Google 改革前的失误在于评审启动得太晚，导致团队不得不从头再来；评审所需的输入是规范或设计文档，必须在代码编写之前提供。

计划成熟度阶梯——排名：

• 效率：linter + two named reviewers > linter-only CI gate > certified federated reviewer pool

• 工作量：certified federated reviewer pool > linter + two named reviewers > linter-only CI gate

• 价值：certified federated reviewer pool > linter + two named reviewers > linter-only CI gate

• 默认阶梯：linter + 两名指定评审人员（Zalando 记录的做法——先由 Zally 检查，每个 API 必须由两名人工评审人员评审，并将发现分为“必须修改”和“改进建议”）。基于公开语料库进行分叉，只需一两天即可搭建；它既能发现机械性问题，也能发现语义问题。当人工评审组合成为瓶颈时，就升级：平均处理时间超过约 2 周，或团队绕开评审直接发布。

• 当一两个团队拥有整个接口时，降级为仅含 linter 的 CI 门禁——语料库和 linter 只需一两个小时即可完成设置，语义讨论仍可在常规代码评审中进行。

• 升级为经过认证的分布式评审人员池——采用共享的版本化规则语料库、评审人员认证（Google 的“API Readability”模式），并让嵌入各领域的评审人员向中央标准团队提供反馈——适用于拥有众多团队的组织。这是最容易被搁置的选项：价值最高，工作量也最大（编写语料库需数周，之后还要开展一个季度左右的评审人员培训和认证计划），因此在所有效率比较中都落败——但拥有数千名工程师的组织无论如何都需要它。

  • 曾构建 Stripe 开发者平台的 Kenneth Auchenberg 承认，集中式评审已变成“一个集中的摩擦点……在拥有数千名工程师的规模下”，并表示会将其转向教育服务——这一说法应归于他本人，而不是“Stripe 表示”。
  • 在所研究的公司中，没有一家公司选择通过扩充中央委员会来实现规模化。

• 删除，而非降级：仅有一两个团队时的分布式评审人员池。 如果问题 3 的回答是一个或两个团队拥有整个接口，就应从选项中移除这一阶梯，而不是将其排在最后——没有可供嵌入评审人员的领域，因此认证和版本化共享语料库只会让两个人本来就会进行的讨论变成形式流程。不要把它搁置在底部，因为“以后再分布式化”会再次成为路线图项目，耗费不必要的语料库编写时间。重新升级的触发条件：第三个团队开始发布自己的 API 接口，或平均评审处理时间超过约 2 周。

• 此排名是默认建议，不是硬性规定。应根据问题 3 的回答和组织情况重新排序，并说明哪项回答让哪一级发生了变化：

  • 临近的截止日期或较低的工作量上限，会提升仅含 linter 的门禁。
  • 现有的 API 公会会让分布式阶梯几乎不增加成本。
  • 已熟悉 Zalando 或 Microsoft 公开语料库的团队，可以跳过编写语料库的成本。
  • 只有一个旗舰 API 的平台，可能永远不需要超越默认阶梯。

各公司的触发条件、批准权限和规模化细节，以及分阶段发布指南和计划健康度指标，见 references/review-program-benchmarks.md。

失败模式

• 一味认可和造成瓶颈——这是评审计划的两种典型失败模式，而且都可以避免。
  • 过于繁重：团队会绕开流程。
  • 过于宽松：沦为走过场。
  • 校准方式：对影响客户端的决策和安全决策严格把关，对风格问题宽容处理，并在一周内快速完成评审。
• 把评审作为最后一道关卡。 如果在实现完成后才给出反馈，团队就不得不从头开始（这是 Google 记录的改革前状态）。解决方法：在设计阶段、针对规范触发评审。
• 扩大评审人员队伍，却没有共享且带版本管理的语料库。 Google 发现，随着评审人员队伍扩大，周转时间和指导一致性都会下降——除非将规则编写下来并进行版本管理，否则增加评审人员只会放大不一致。
• 基于个人偏好的阻塞性意见。 没有引用规则依据的阻塞意见正是步骤 4 要防止的反模式；它会同时重现这两种失败模式。
• 用“文档里写了”来解决不一致。 开发者在期限压力下不会读文档——应让一致的选项成为默认或唯一选项；记录陷阱所在并不等于消除了陷阱。
• 孤立地评审各个端点。 一致性缺陷——大小写混用、分页方式不一、错误结构各异——在一次只看一个端点时无法发现。务必跨整个接口面进行评审。

衡量标准

• 审计门槛：发布时不得有尚未解决的 Must-change 发现。 对于 Beta 或 GA 发布，持续迭代——修复问题，或记录有据可查的偏差——直到 Must-change 列表清空。改进项可以保持未解决状态并随版本发布。
• 覆盖率门槛：逐项检查每个清单维度，并完成五项单行的同类接口检查。跳过任何维度都意味着评审不完整，而非精简。
• 计划健康度（仅适用于常设计划）：
  • 小型 API 的目标周转时间为一周以内。
  • 中位周转时间超过约 2 周，或团队未经评审就发布，说明流程过于繁重——应自动化或分散评审职责。
  • 到达 GA 的缺陷中，若存在书面规则本可发现的问题，说明流程过于宽松——将规则加入代码检查工具并要求引用规则依据。
  • 这些阈值是根据 Google 的数据得出的基准：可将趋势视为有来源支持的结论，将具体数字视为校准参考，而非硬性规定。

调用示例

• “在我们将这个 OpenAPI 规范对应的 API 对外开放前，请进行评审——标出外部开发者会认为不一致的地方。”
• “审计我们的 /v1 端点：每种资源的分页方式都不一样，错误响应体也不匹配。哪些必须修复，哪些只是锦上添花？”
• “我们的团队即将从 3 个增至 30 个——设计一个不会造成瓶颈的 API 设计评审流程。”

参考资料

• references/review-checklist.md - 涵盖全部八个维度的完整通过/未通过清单，以及五项同类接口边界检查。
• references/worked-review-excerpt.md - 一份完整的评审报告节选，其中包含引用规则依据的问题、记录在案的偏差和反面示例。
• references/review-program-benchmarks.md - Google、Microsoft Azure、Stripe、Zalando 和 PayPal 经核实的触发机制、权限及扩展模式；分阶段的计划启动指南；计划健康度指标。
• samber/developer-platform-skills@api-integration-surface-strategy - 上层决策，用于安排本技能评审的 REST 接口面；如果本技能要评审的接口面从未在此处安排过，则必须先作出该决策，而非直接进行评审。
• samber/developer-platform-skills@api-beta-program - 运行本技能的 Beta 级评审门槛所对应的预览；只要 Must-change 发现仍未解决，就不会有账号加入。