| 编号 | 128 |
|---|---|
| 原文链接 | AIP-128: Declarative-friendly interfaces |
| 状态 | 批准 |
| 创建日期 | 2020-10-06 |
| 更新日期 | 2020-10-06 |
许多服务需要与常见的DevOps工具交互，特别是创建和管理可网络寻址资源（如虚拟机、负载均衡器、数据库实例等）的工具。这些工具采用“配置即代码”原则：用户设定一个完整的目标状态，工具负责执行必要的操作，实现用户设定的规范。
这些工具是 声明式 的：不指定具体要执行的操作，而是指定期望的目标。操作是根据当前状态与目标状态之间的差异推导出来的。
此外，流行的DevOps工具数量众多，每年又会出现大量的新工具。将数百种资源类型与多个工具进行集成，需要统一接口，以便自动执行集成工作。
指南
资源
声明友好资源 必须 始终使用标准方法管理资源生命周期，这将允许工具广泛支持这些资源，同时也符合声明友好指南的其他要求（参考进一步阅读）。
声明友好资源 应该 指明其遵守声明友好风格：
message Book {option (google.api.resource) = {type: "library.googleapis.com/Book"pattern: "publishers/{publisher}/books/{book}"style: DECLARATIVE_FRIENDLY};// Name and other fields...
}
协调
如果更新资源需要较长时间（超过几秒），资源 应该 包含一个 bool reconciling 域，告知更改正在进行。这个域 必须 是仅输出的。
如果资源的当前状态与用户预期的状态不一致，并且系统正在协调处理，资源 必须 将 reconciling 域设置为 true ，无论开始协调的根本原因是用户操作或系统动作。
注意： 处理
GET请求的服务 必须 返回资源的当前状态（而非预期状态）。
进一步阅读
关于声明友好接口存在大量更严格的指南，因为它关注于对资源的自动化操作。下面的列表是其他AIPs中关于声明友好接口指南的汇总：
- 资源 不应 使用自定义方法：参考AIP-136。
- 资源 必须 使用
UPDATE方法处理重复域：参考AIP-144。 - 资源 必须 包含特定的标准域：参考AIP-148。
- 资源 必须 具有
etag域：参考AIP-154。 - 资源 应该 提供验证更改的方法：参考AIP-163。
- 资源 不应 实现软删除。如果资源标识不能重复使用，资源 必须 实现软删除和撤销删除RPC：参考AIP-164。
注解
参考AIP-148注解。
修订记录
- 2023-07-13 将
annotations移动到AIP-148。 - 2023-06-17 删除关于平面的定义，移动到AIP-111。
- 2023-05-11 删除对resource_id域的“必须”要求，该要求已移动到通用的“必须”规范中。
