AIP-129 服务器修改的值和默认值

服务通常为资源的域提供默认值，偶尔也会在返回应答之前对用户输入进行规范化处理。本指南描述了应如何撰写文档记录此类行为，以使接口消费者收益。

指南

单一拥有者域

域 必须 只有一个拥有者，要么是客户端，要么是服务器。服务器拥有的域 必须 标记成 OUTPUT_ONLY 域行为。所有其他类型的域 必须 被视为客户端所拥有。服务器 必须 尊重所有客户端拥有域的值（或默认值），不能修改它们。

有效值

如果客户端没有设定值，此时服务将分配、生成或计算出一个值。例如客户端创建一个虚拟机，但没有指定静态IP地址。此时将使用动态IP地址分配。

这种类型的域的例子有：

• 生成的（UUID）
• 分配的（动态IP地址）
• 指派的（最新软件包版本）

具备有效值的属性 必须 在API中表示为两个域：

• 一个可变域，由用户按需要设置，服务器 不得 修改。
• 一个 OUTPUT_ONLY 域，记录由服务器决定的有效值。

示例：

message VirtualMachine {
  ...
  string ip_address = 4;
  string effective_ip_address = 5 [
    (google.api.field_behavior) = OUTPUT_ONLY
  ]

命名

有效值 必须 以可变域名字前加上 effective_ 前缀命名。

用户设定域

对于用户设定的域，服务应答中的值 必须 与创建或更新请求中提供的值相同。对于字符串域，这意味着返回的值不变，除了一个例外：

• 如果字符串域包含数据类型注解， 可以 返回值的规范化字符串。

规范化

由服务器进行规范处理的域 必须 用 google.api.field_info 扩展注解。关于这个注解的指南请参考AIP-202。支持的规范格式集有：

• uuid
• ipv4
• ipv6
• email

域的规范格式 必须 使用 google.api.field_info 注解描述。

理由

服务器修改的值和默认值通常让声明式客户端的开发更加困难。客户端难以判断这些域的期望状态和当前状态是否一致，因为服务器修改和返回值的规则复杂、不透明又不可重复。

使用单一拥有者域的理由

如果域没有单一拥有者，将会导致声明式客户端出现问题。这些客户端可能试图设置那些会被服务器覆写的域，导致客户端进入不断试图纠正状态的死循环。

命名的理由

统一的命名规则对于在多个API和多个域之间识别标准行为非常重要。用户设定值和有效值之间的程序化关联依赖于统一命名。

TODO 规范化的理由

规范化非常重要，它使得服务能够以标准的方式存储和返回值，同时告诉客户端哪些变化在语义上是等价的。

规范化对于允许服务以标准方式存储和返回值非常重要，同时向客户端传达哪些更改在语义上是相同的。在服务端对值进行规范化处理，可以让服务接受广泛的语义等价输入，无需将每个值作为原始字符串处理。返回客户端输入的规范化结果，让客户端可以比较发送和接收的值，比对差异。

例如对于在某个域上接受电子邮件地址的资源，客户端可能以多种格式设定电子邮件地址值。对于电子邮件 ada@example.com ，客户端可能设定为 ADA@example.com 、 aDa@example.com 或 AdA@example.com 。它们在语义上是等价的，都 应当 被服务接受。服务通过改成小写或规范化，将电子邮件地址改成规范格式进行存储和检索。请注意，返回给客户的域的规范化信息不会描述规范化算法自身，而是用于准确判断两值是否等价的的比较方法。

域值处理的理由

对于不能使用规范化的域，声明式客户端将无法识别哪些变化在语义上具有意义。当声明式客户端发送特定值时，要确保服务返回该值，以验证设定否正确。

修订记录

• 2023-10-31 将状态改为批准。