AIP-100 API设计审查常见问题解答

API设计审查可以保证API集合提供简单、直观、一致的API体验。

我需要API设计审批吗？

简述： 如果计划发布Beta版本或正式版本质量级别的API，（现在或将来）提供给用户编码调用，通常需要API设计审批。

API设计审查的根本目的是保证为用户提供简单一致的体验，因此只针对用户直接编码调用的API。

下面的流程图展示了API是否需要通过设计审查流程：

谁会编写代码直接调用这个API？

一个更复杂（译注：与前文“我需要API设计审批吗？”相比）的问题是：“谁会编写代码直接调用这个API？”API设计审查主要关注API的使用者。这意味着我们关心的是谁可以编写HTTP/gRPC调用访问服务，以及谁能够阅读文档。（我们关心服务是否发布在公共网络上这类问题。）

如果预计任何人都可以阅读文档、编写代码与服务交互，则需要进行设计审查。

以下情况 不需要 设计审查：

• 只有内部员工或内部工具使用的API（如Pantheon）。
• 只会被内部发布的可执行程序调用的API（即使API可以通过逆向工程从程序文件中破译）。
• 由于合同约束，只有一个客户或极少量客户调用，并且 永远不会 大范围公开的API。（此时仍然建议进行设计审查，但不是强制的。）

Alpha版本

对于Alpha版本，API设计审查是可选的，但仍建议进行。通常快速获得客户的初步反馈是有意义的，发布Alpha版本是获取数据，确定某些可用性问题最佳方案的一种方；此时跳过审查是可取的。另一方面，发布Alpha版本需要构建一个实现，如果在Beta阶段的设计审查中发现问题，需要花费时间修改。考虑到API设计审查可以在具体构建工作之前进行，我们建议对Alpha版本进行设计审查。

为什么设计审查很重要？

简述： 产品卓越性。

设计审查流程旨在保证向客户提供的API是 简单 、 直观 、 一致 的。审查者从新手用户的角度观察API，思考API提供的资源和操作，尝试让API接口尽量易于访问和扩展。

审查者不仅仅评估API，还会检查API是否与现有API集合一致。许多客户会使用多个API，因此API的名字和约定必须符合客户的期望。

我应该期待什么？

审查过程需要多长时间？

审查者会尽力跟进所负责的审查任务，经常提供反馈，避免造成不必要的延误。但还是最好尽早开始审查过程，以防延误。

根据API接口的规模和复杂性不同，设计审查过程也有所差异：

• 对现有API的增量修改通常需要几天时间。
• 小型API通常需要大约一周时间。
• 大量全新的API接口通常需要至少一周时间。在接口非常多的情况下（例如Cloud AutoML），审查过程可能需要一个月或更长时间。

审查者如何审查API？

审查者试图以用户的角度审查API，主要关注API接口和面向用户的文档。在理想情况下，审查者会指出可能引发用户困惑的问题（并推动API在初始阶段减少此类问题）。

什么是先例？

通常我们希望API集合尽量一致。让用户学会第一个API后，学习第二个（接着是第三个，依此类推）时更轻松，因为我们始终提供同样的模式。

我们所说的 先例 是现存API已经做出的设计决策，这些决策通常应该对相似的新API具有效力。最常见的例子是命名：我们有一个标准域列表，规定了如何使用 name 、 create_time 等常见术语，以及如何将 相同 名字关联到同一个概念上。

先例也适用于 模式 。所有API都应该以相同的方式实现分页。运行时间长的操作、导入和导出等操作也是如此。模式建立之后，要在相关之处以同一种方式实现模式。

我应该做什么？

…如果发布时间紧迫？

最好尽早启动设计审查。此外，提醒审查者时间紧迫，让他们尽量提供优先服务。 希望 你尽可能按时完成任务。

对于时间紧迫的 Alpha版本 ，API 可以 在没有获得设计审查批准的情况下发布。此类发布 必须 仅限于已知用户群。此时审查者将提供评论，供API团队在后续阶段考虑。

警告： 在Alpha阶段发布 API 时，不完整的设计审查过程 不会 认可该API设计决策。要将API升级到Beta版本，设计审查是必要条件。如果存在设计问题，审查者将阻止Beta版本发布。

对于Alpha阶段之后的发布，API设计审查是强制的，因为涉及对用户体验的全面影响。不一致性会产生全局影响。

有时，在产品卓越性、工作量或发布时间之间进行选择是困难的。这是艰难的商业决策，我们认为这往往是必要的。如果将这些因素置于产品卓越性之前，跳过设计审查阶段或拒绝审查意见，必须由总监或副总裁做出明确决定。

…如何审查得更快？

一些提示：

• 尽早开始API审查，时常跟进。
• 提前执行API linter。（如果禁用了linter，请解释原因。审查者经常发现linter由于正常工作而被禁用。）
• 保证每个消息、RPC和域都包含 有效 注释。注释应该使用语法正确的文本，并具有实际意义。
• 如果审查者要求提供补充说明，在proto中添加注释，不要在审查中口头说明，往往可以避免重复审查。

…如果某位审查者没有回应？

在Gogole Chat上联系审查者。如果联系不上，联系另一位审查者进行协调。如果仍然联系不上，根据AIP-1升级问题。

…如果我的设计存在问题？

首先查看API风格指南、AIP索引和Google的其他公共API。公共API非常有价值；通常有人已经在类似的场景下解决了问题。

…如果我遇到了AIP没有覆盖的问题？

联系api-design@google.com提出问题。

通常在你寻找与API设计相关的具体问题的指导时效果最好，要清楚的说明场景并提供示例。

注意： 该列表上的成员几乎都是兼职，大部分时间忙于其他工作。我们会尽力迅速响应，也请保持耐心。

…如果一个问题很复杂，在代码评审中迟迟无法解决？

代码审查工具是解决实际问题的最好方法，但有时问题非常复杂，难以在代码审查工具中处理。此时联系审查者安排一次会议。通常大多数问题可以在30分钟内讨论清楚。

这种情况下，确保有人将讨论内容写入文档，保留历史记录。

…如果API需要违反标准？

明确记录（使用proto注释）违反API设计指南的情况及理由。注释 必须 添加 `aip.dev/not-precedent` 前缀。

通常，违反设计指南的理由 应当 符合AIP-200中列出的原因之一。否则请与审查者一起确定适当的做法。

…如果审查者提出了一个早已经解决的问题？

如果先前阶段存在另一位审查者，这种情况可能发生。一般来说，最好的方法是直接引用决定该问题的代码审查。审查者希望避免反复，通常会尊重先前的审查结果。这往往可以迅速解决问题。

有时审查者可能认为前一个审查者存在错误，修正错误非常重要。此时请和审查者应该一起确定最好的行动方案。

…如果设计团队和审查者无法达成一致？

根据AIP-1升级。

我的产品领域或团队有特殊的指南吗？

云产品领域有特殊指南，以保证云服务的额外需求，云API有自己的审查者清单。其他团队可能采用类似（但未必完全一样）的规则和系统。一些提供多套API的团队（例如机器学习）也可能存在适用于特定API的指南。

无论那种情况，我们努力将这些指南编制成AIP；高范围AIP编号保留给特定的产品领域和团队使用（见AIP-2），这些AIP列在AIP索引中。