AIP-8 AIP风格与指南

AIP代表 API 改进议案（API Improvement Proposal） ，是一个设计文档，为API设计和开发提供高层次的简要文档。AIP的目标是成为Google内部API相关文档的权威来源，并作为API团队讨论和达成共识的方式。

清晰、简洁并充分涵盖单一主题或问题的AIP最有效。AIP描述了API设计的规范模式和风格，同样的，AIP也遵循规范模式和风格。

指南

• AIP 必须 涵盖单一的独立主题，并提供清晰、可操作的指南。
• AIP 不得 与其他AIP重复或冲突。
• AIP 可以 包含禁止事项，但 不得 只包含禁止事项。
• 如果AIP指南存在前置条件（例如任务Job等设计模式），指南 必须 清楚说明在哪些条件下应当遵循该指南。

AIP指南 必须 对一种或多种类型的客户端或客户端开发者有益，包括但不限于：

• 用于审计和分析资源的资产清单。
• 用于交互式操作和简单自动化的命令行界面。
• 自定义控制器（例如自动伸缩程序），轮询实时状态，相应的调整资源配置。
• 用于编排和自动化多种资源的基础设施即代码（IaC）客户端。
• 提供API适用场景信息和用法指导的推荐工具。
• SDK，用于编程语言和API交互，通常主要用于数据平面操作。
• 安全编排、自动化和修复工具。
• 用于自动化或编排任务的简单脚本。
• 测试框架。
• 操作离线资源数据的工作。
• 用于可视化和简单手动操作的图形用户界面（GUI）。
• 用户。

改进的示例包括：

• 提供新的proto注解，允许客户端能够使用详细的解释性界面（例如允许在 google.api.resource 注解上使用 singular 和 plural ）。

AIP 指南 不得 显著损害客户端可用性、实现难度或维护难度。

损害的示例包括：

• 在标准方法中引入不一致的模式，导致所有客户端必须引入额外代码，却没有足够的收益（例如提供 List 方法，列出 除了 名称以Foo开头之外的资源）。
• 修改常用域的名字，只为了稍稍改进可读性（例如将 expire_time 更名为 lapse_time ，只因 lapse 是服务中的常用术语）。

虽然AIP的长度必然随问题的复杂度而有所差异，大多数AIP 应当 在两页纸左右的篇幅内阐明内容。

文件结构

AIP 必须 使用Markdown编写，文件 必须 以其四位数编号命名（例如： 0008.md ）。用于特定类别的AIP 必须 保存在对应的子目录中。

AIP 必须 有适当的前置内容。

---
id: 8
state: reviewing
created: 2019-05-28
permalink: /8
redirect_from:
  - /08
  - /008
  - /0008
---

AIP前置内容 必须 包括：

• aip 键：
  • id ：必需。分配给AIP的标识，是一个整数。
  • state ：必需。AIP的当前状态，使用小写字母。状态定义在AIP-1中，常见状态有 草稿 、 审查 和 批准 。
  • created ：必需。AIP的起草日期，ISO-8601格式（ yyyy-mm-dd ）。
  • updated ：AIP上次修订日期，ISO-8601格式（ yyyy-mm-dd ）。
  • scope ：AIP类别。 必须 与对应的目录名一致。对于ID >= 1000的AIP 是必需的，对于其他AIP则是禁止的。
• permalink 键（必需）： 必须 设置为 /{aip.scope}/{aip.id} 。如果没有所属类别，则使用 /{aip.id} 。
• redirect_from 键：包含任何读者可能会点击的 /{aip.id} 的列表，包括：
  • /{aip.id} （用于permalink已经类别的AIP）
  • 使用0填充的AIP标识，最多填充到四位（例如： /08 、 /008 、 /0008 ）。

文档结构

AIP 必须 以AIP标题作为顶级标题开头（ # 标题 ）。标题 应当 是名词（而非祈使句）。例如：使用“不良API先例”，而不使用“避免破坏API惯例”。

AIP 应当 接下来以介绍开头（没有额外标题），然后是 ## 指南 标题。在需要时，AIP 可以 在指南之后包括以下任何内容，按顺序排列：

• “进一步阅读” 包含其他AIP链接的列表，有助于深入理解当前AIP。
• “附录” 包含对AIP的进一步解释。这并不常见，但对于需要反复权衡的AIP很重要。通常主要是对备选方案的说明，有助于解释指南。
• “修订记录” 是自起草后对AIP所做的修订。

指南章节 可以 包括进一步详细说明的子章节。子章节将自动创建目录条目和引用锚点。

以下包含了全部主要章节的示例AIP模板：

# AIP标题

解释AIP背景和原因的介绍文本。提出基本问题，但没有给出方法。

## 指南

“指南” 章节帮助读者了解具体方法。常见格式是具有一定抽象层次的祈使句，并带有示例。接着是解释示例的列表。

### 子章节

子章节可以被独立引用，进一步说明细节。

## 理由

“理由” 章节是可选的，帮助读者理解AIP中特定指南背后的动机。

对设计理由和权衡的深入解释 **必须** 放在这一章节，不能放到其他章节，以确保其余章节可以作为易于操作的参考手册。

## 历史

“历史” 章节是可选的，记录了AIP重大修订的情况和背景。例如，重写AIP的原委应当包含在本节中。

修订记录是AIP变更的单行摘要列表，而历史章节应当以易于理解的格式，详细说明重大修订。

历史章节 **不得** 用于详尽列举所有修订。这是修订记录的内容。

## 进一步阅读

其他AIP的列表，格式如下：

- [AIP-1](./1)：AIP目的和指南

## 修订记录

按时间倒序排列的变更列表，格式如下：

- **2020-02-18**：设置排列顺序。
- **2019-07-01**：添加详细介绍XYZ的子章节。

AIP 应当 尽量遵循这个格式。在需要时，AIP 可以 修改格式（尤其是当AIP变得对即使是熟悉规范格式的读者来说也难以理解时）。

注意： 除了标题外，AIP 必须 仅使用第二级（ ## ）或更高级别标题。AIP 应当 仅使用第二级和第三级标题（ ## 、 ### ）。

需求关键词

AIP 应当 使用以下需求级别关键词：“必须”、“不得”、“应当”、“不应” 和 “可以”，词汇含义与RFC-2119一致。

在AIP中使用这些词汇时， 必须 使用小写字母和 粗体 。这些词汇 不应 以其他方式使用。

使用词汇“应当”或“不应”时， 必须 包含有效示例，说明建议不适用的可能原因。

重要： 理由章节旨在提供背景和全面理解，但 不得 包含指南（也 不得 使用RFC-2119词汇）。

代码示例

AIP中的API设计示例 应当 使用Protocol Buffers。示例 应当 只包含足以阐明概念的语法。在示例中使用RPC时， 应当 包含 google.api.http 注解。

引用AIP

在AIP种引用其他AIP时，文本 必须 使用格式 AIP-XXXX ，不含填充字符（例如 AIP-8 ，而非 AIP-0008 ），且 必须 链接到相关的AIP。AIP链接 可以 指向AIP的特定章节（如果需要）。

重要： AIP 链接 必须 使用存储库中文件的相对路径（例如，核心 AIP 的 `./0008.md`，或子目录中 AIP 的 `../0008.md`）；这确保链接在 AIP 站点、GitHub 上查看 Markdown 文件、使用本地开发服务器或分支时都能工作。

理由

适用广泛客户端的设计

API指南与软件类似，在有明确目的和目标受益者时最有用。

改进API设计的受益者是用户。用户根据自己的使用场景（如上文所述），通过多种客户端与API交互。

因此API指南必须考虑对广泛客户端的影响。

修订记录

• 2023-05-20: 增加API指南类别，包含更多客户端种类。
• 2023-03-30: 从模板中删除附录章节，添加理由和历史章节。
• 2020-02-18: 为修订记录设置时间倒序排列顺序。
• 2019-08-23: 添加内部AIP链接指南。