当前位置：首页 > news >正文

AIP-1 AIP目的和指南

news 来源：原创 2025/5/11 22:53:58

原文	AIP-1: AIP Purpose and Guidelines

随着Google API数量不断增加，API治理团队不断扩张，以满足API维护工作需求。越来越有必要为API生产者、审查者和其他相关方提供一套参考文档。API风格指南和一站式介绍文档简洁扼要。AIP集合提供了一种产出一致性API设计指南文档的方法。

什么是AIP？

AIP代表 API改进议案 ，是一个设计文档，为API开发提供高层次的简洁文档。AIP作为Google内部API相关文档的源头，也是API团队讨论协商API指南的工具。AIP以Markdown文件的形式维护，保存在AIP GitHub 仓库中。

AIP的类型

下面介绍了AIP的几种不同类型。AIP类型清单将会在必要时进行调整。

指南

描述API设计的指南，为API生产者提供指导，帮助编写简单、直观、一致的API。也被API审查者作为审查意见的基础。

流程

描述API设计流程，通常作用于AIP流程自身，用于改进AIP处理方法。

利益相关者

与任何流程一样，AIP的审查和使用涉及许多不同的利益相关者。下面是一份升级路径摘要，从API生产者开始。

如图所示，团队负责人是AIP流程的最终决策者，也是升级路径终点。

编辑者

编辑者是对AIP做出决策的人。总体目标是：AIP流程是协作式的，主要基于共识工作。不过还是有必要指定几个批准者，负责批准通用领域的AIP。

目前AIP编辑者列表如下：

Angie Lin (@alin04)
Jon Skeet (@jskeet)
Jose Juan Zavala Iglesias (@itsStrobe)
Louis Dejardin (@loudej)
Noah Dietz (@noahdietz)
Sam Levenick (@slevenick)
Sam Woodard (@shwoodard)

编辑者还负责AIP的管理和编辑方面的工作，包括发展AIP、管理AIP管道和工作流程。他们批准AIP拉取请求、分配议案编号、管理议程、设置AIP状态……。他们还确保AIP易于阅读（拼写准确、语法、句子结构、标记等）。

AIP编辑者资格通过当前编辑者邀请获得。

特定领域的AIP

一些AIP可能限制在某个特定领域内（例如仅适用于某个PA甚至某个团队内的API）。根据AIP-2，团队可以获得一个专用AIP编号区间，这些AIP有明确的适用范围。

状态

AIP仍在维护和改进。在不同时间点，AIP可能存在多种状态。以下是各个状态的简介。

草案

AIP初始状态是“草案”，表明AIP正在由最初的作者讨论和改进。编辑者可以在这个阶段参与工作，但不是强制的。

注意： 如果需要进行重要改造，最好在Google文档中起草AIP，而非使用拉取请求。如果得到了足够的批准，AIP从Google文档迁移到AIP系统时，可以跳过草案状态，直接进入审查。

审查

一旦对AIP的讨论基本结束，在正式接受之前，它将进入“审查”状态。这意味着作者已经达成一般共识，编辑者开始工作。在此阶段，编辑者可能会要求修改或提出备选方案，然后流程进入下一步。

注意： 作为重要事项，必须有AIP批准者（除了作者之外）提供的正式签署，AIP才会进入审查状态。并且不能有其他批准者提出正式反对意见（GitHub拉取请求上的“请求修改”）。

批准

一旦AIP获得批准，它将进入“批准”状态，并被视为“当前最佳实践”。

注意： 作为重要事项，**必须** 有两个AIP批准者（除了作者之外）提供正式签署，AIP才会进入批准状态。并且不能有其他批准者提出正式反对意见（在GitHub PR上“请求修改”）。

撤回

如果AIP被作者或负责人撤回，它将进入“撤回”状态。被撤回的AIP可以会被另一个负责人接手。

拒绝

如果AIP被编辑者拒绝，它将进入“拒绝”状态。被拒绝的AIP仍然存在，并提供文档和参考以供未来讨论。

延期

如果AIP在很长一段时间内没有被处理，编辑者可以将其标记为“延期”。

更换

如果AIP被另一个AIP更换，它将进入“更换”状态。编辑者负责提供通知，解释更换方案和理由（新AIP也应当清楚说明更换理由）。

通常，API生产者应当依赖“批准”状态的AIP。

工作流程

工作流程描述了提交AIP的过程，以及推动AIP从提案、实施到最终批准的过程。

概述

提出AIP

要提出AIP，首先创建问题，传播基本想法，获取初步反馈。通常几页的篇幅足以描述清楚。

准备好以后，在AIP目录中创建名为 aip/new.md 的文件，提交拉取请求。确保维护者可以编辑拉取请求。

多数情况下，编辑者将为议案分配AIP编号，将AIP设置为“审查”状态，提交拉取请求。编辑者可以直接拒绝AIP，如果存在充分理由（例如议案已在其他AIP中讨论并拒绝，或者根本不合理）。此时拉取请求不予合并。

讨论AIP

拉取请求合并之后，作者负责在后续批准过程中推进AIP。这意味着作者需要促成议案相关共识。通常需要在API治理团队定期会议上进行讨论。

讨论期间，作者可以修改AIP，向拉取请求提交评论。

批准AIP

编辑者将共同努力，确保合格议案不会长期停留在审查状态。

要获得最终批准，按最低要求，AIP 必须由负责AIP涵盖领域（设计或基础设施）的团队负责人和至少一名另外的编辑者批准，并且不能有编辑者主动要求修改。

注意： 如果AIP的主要作者是编辑者，则至少需要两名 另外的 编辑者批准。

AIP获得批准后，编辑者将更新AIP状态，反映工作进度，并提交拉取请求。

撤回或拒绝AIP

在进一步思考后，AIP作者可能决定不再推进AIP。此时作者撤回AIP，更新拉取请求，添加撤回通知并说明原因。此外作者可能无法在小组中推动共识，编辑者可以选择拒绝AIP。此时编辑者应当修改拉取请求，添加拒绝通知并说明原因。在这两种情况下，编辑者都会相应地更新API状态并提交拉取请求。

更换AIP

偶尔可能需要用新AIP更换现有AIP，这不是常见的做法。可以对已批准的AIP做少量修订，这也将是调整指南的常用方法。然而如果新指南从根本上改变了旧指南，编辑者应当创建新AIP，并在获得批准后更换旧AIP。旧AIP进入“更换”状态，并链接到新的现行AIP。

修订记录

2024-09-04: 更新编辑者名字，移除团队负责人。
2023-05-10: 更新编辑者和团队负责人名字。
2019-07-30: 澄清AIP法定人数要求。
2019-05-12: 将批准者和编辑者合并成一个职位，放宽全体同意的批准规则。
2019-05-04: 更新AIP，引用GitHub流程，不再引用内部流程。