tommwq.work/aip

AIP-200

· [tommwq@126.com]
编号 200
原文链接 https://google.aip.dev/200
状态 批准
创建日期 2018-06-28
更新日期 2018-06-28

很多时候，API的编写方式会违反新的指导原则。此外，有时出于特定原因也需要打破标准，例如与现有系统保持一致、满足严格的性能要求或其他因素。最后，尽管API在发布前受到仔细审查，有时还会遗漏一些错误。

由于很难修复历史错误或者让每个API都遵守最新标准，API可能长期保留一些例外。此外，由于新API通常遵照现有API进行设计（名字、类型、结构等），一个API中的例外情况可能会蔓延到其他API，即使最初导致例外的因素已经不再成立。

因此，防止例外蔓延到新API的“止血”工作非常重要，要记录每个例外的原因，以免丢失历史智慧。

指南

如果由于某种原因，API违反了AIP标准， 必须 在内部注释中链接本文档，以保证其他人不会重复违规行为，或声称存在“已批准API”先例。

注释应当包括所违反的标准，及其必要性原因。例如：

message DailyMaintenanceWindow {
message DailyMaintenanceWindow {
  // Time within the maintenance window to start the maintenance operations.
  // It must use the format "HH MM", where HH : [00-23] and MM : [00-59] GMT.
  // (-- aip.dev/not-precedent: This was designed for consistency with crontab,
  //     and preceded the AIP standards.
  //     Ordinarily, this type should be `google.type.TimeOfDay`. --)
  string start_time = 2;

  // Output only. Duration of the time window, automatically chosen to be
  // smallest possible in the given scenario.
  // (-- aip.dev/not-precedent: This preceded the AIP standards.
  //     Ordinarily, this type should be `google.protobuf.Duration`. --)
  string duration = 3;
}

重要： 只有Beta版本或发行版本的API才可以作为先例。

局部一致性

如果API全部违反标准，为了遵守全局标准而破坏现有模式，将会让用户感到不适和沮丧。

例如，如果API的所有资源都使用 creation_time （而不是AIP-142中要求的标准字段 create_time ），那么API中的新资源应当继续采用局部模式。

然而，其他可能会参照这个API的人应当知晓这是违反标准的，不应在发布新API时作为先例引用。

// ...
message Book {
  // (-- aip.dev/not-precedent: This field was present before there was a
  //     standard field.
  //     Ordinarily, it should be spelled `create_time`. --)
  google.protobuf.Timestamp creation_time = 1;
}

// ...
message Author {
  // (-- aip.dev/not-precedent: `Book` had `creation_time` before there was
  //     a standard field, so we match that here for consistency. Ordinarily,
  //     this would be spelled `create_time`. --)
  google.protobuf.Timestamp creation_time = 1;
}

先已存在的功能

有时在发布前被忽略违反标准的情况，而API已经变得稳定，不易修改。此外，一个稳定API可能是在新标准之前发布的。

此时很难让API符合标准。API应当注明这个功能是违反标准的，以便其他API不会重复犯错，或作为其错误设计应当被批准的理由。

遵守外部规范

有时API必须违反标准。某些特定API请求是按照外部规范（例如OAuth）实现的，外部规范可能与AIP指南存在冲突。此时遵守外部规范是合适的。

遵守现有系统传统

与上述外部规范例子类似，为了以某种方式适应现有系统，API可以违反AIP指南。本质上是贴近客户需求。另一个例子是与合作伙伴的API集成，或提供相似API。

时效性

有时用户需要在紧迫的时间内获得API界面，否则将面临钱财损失。由于大多数API为业务目标服务，有时API可以做得更好，但无法在截止日期前交付到用户手中。此时API审查委员会 可以 批准例外，允许因时间和业务限制，发布违反指南的API。

技术问题

内部系统有时存在非常具体的实现需求（例如需要使用UTF-16而不是UTF-8的操作转换），遵守AIP指南需要额外的工作，但不会为API消费者增加多少价值。未来需要发布API的系统在设计时应当考虑到这一点，避免建立让AIP指南难以遵守的基础架构。

修订记录

  • 2020-03-27 按照AIP-8修改大量措辞，删除了第一和第二人称。语义没有修改。
  • 2019-05-04 将文中链接改为公共链接（https://google.aip.dev/200），将词汇“风格指南”改为更通用“标准”（以适应向AIP的普遍转变）。