AIP-202 域

google.api.FieldInfo 类型通过扩展 google.api.field_info ，在基本的名字、类型信息之外，提供了更丰富的域的模式。

指南

只有在AIP或其他涉及 google.api.FieldInfo 信息AIP中明确说明时，才需要使用 google.api.field_info 注释域。因此本文中的指南也适用于这些场景。

格式

具有原始类型的域也可以特定的格式。要表达特定格式，可以使用 (google.api.field_info).format 扩展域和 FieldInfo.Format 枚举。以下指南介绍了每个 FieldInfo.Format 值的含义和使用要求。

UUID4

UUID4 格式表示由 RFC 4122 规定的UUID版本4的值。 必须 仅用于 string 类型域。

服务 可以 将值改写成规范的小写字母形式。例如，值 F47AC10B-58CC-0372-8567-0E02B2C3D479 将改写成规范的 f47ac10b-58cc-0372-8567-0e02b2c3d479 。

因此 不得 使用简单的文本比较来判定等价。相反，**必须** 使用符合 RFC 4122 的方法。

IPv4

IPV4 格式表示由 RFC 791 规定的IPv4地址。 必须 仅用于 string 类型域。

服务 可以 压缩这个值，移除每个八位字节中的前导零。例如 001.022.233.040 被压缩为 1.22.233.40 。

因此 不得 使用简单的文本比较来判定等价。相反，**必须** 使用符合 RFC 791 的方法。

IPv6

IPV6 格式表示由 RFC 4291 规定的IPv6地址。 必须 仅用于 string 类型域。

服务 可以 按照 RFC 5952 规定，将值改写成规范的小写字母形式，并压缩零字符。例如，值 2001:0DB8:0::0 将被改写为规范的 2001:db8:: 。

因此 不得 通过简单的文本比较来判定等价。相反，**必须** 使用符合 RFC 4291 的方法。

IPv4或IPv6

IPV4_OR_IPV6 值表示域可以是IPv4或IPv6地址，如 IPv4 和 IPv6 部分所述。

格式兼容性

向现有未指定格式的域添加格式限定符 不是 向后兼容的，*除非* 这个域始终符合指定格式。

在任何时候，将现有格式限定符修改为不同的格式限定符都 不是 向后兼容的。

扩展格式

任何新的 FieldInfo.Format 值 必须 符合 IETF批准的RFC 或 Google批准的AIP 规定。

理由

为何使用格式限定符？

原始类型域的格式对可用性非常重要。一些编程语言可能将特定类型格式表达为独立类型，如Java中的UUID。大多数语言都有特定的结构规定，由服务进行验证，因此提前向用户传达格式要求，对用户体验至关重要。

为何不推荐简单文本比较？

格式的文本表示存在许多细微差别，全部转换为规范形式并非易事。因此，在每个消费者和每个服务之间实现无缝对接是不可行的。

为何统一值的规范形式？

虽然不推荐简单文本比较，但返回值的统一的规范形式，对于设定消费者预期和创建用户友好接口非常重要。

为何要求新格式需要RFC或AIP批准？

那些充分标准化的，值得进入RFC或AIP的格式，足够稳定又广为人知，可以作为支持格式在Google API中使用。这个额外的指南意味着管理格式规范不是 FieldInfo.Format 枚举本身的责任。