AIP-126 枚举

编号	126
原文链接	AIP-126: Enumerations
状态	批准
创建日期	2019-07-24
更新日期	2019-07-24

一个域的值集合是一组数量有限的具体值，这是很常见的。此时使用枚举（缩写为“enums”）可有助于明确表达值集合的范围。

指南

API 可以 为不经常更改的值集合建立枚举对象：

// A representation of a book.
message Book {// Other fields...// Possible formats in which the book may be published.enum Format {// Default value. This value is unused.FORMAT_UNSPECIFIED = 0;// The printed format, in hardback.HARDBACK = 1;// The printed format, in paperback.PAPERBACK = 2;// An electronic book format.EBOOK = 3;// An audio recording.AUDIOBOOK = 4;}// The format of the book.Format format = 99;// Other fields...
}

• 枚举值 必须 使用 UPPER_SNAKE_CASE 。
• 枚举的第一个值 应该 是枚举类型名字，加上后缀 _UNSPECIFIED 。
  • 本规则存在例外情况。如果存在一个明显有意义的零值，特别是如果枚举需要表示 UNKNOWN ，通常使用零值比同时使用零值和 UNSPECIFIED 更加明确和有效。
• 只在单个消息中使用的枚举 应该 内嵌在消息中。此时枚举的声明位置 应该 紧邻并在使用处之前。
  • 内嵌枚举定义的非零值 不应 以枚举名字作为前缀。这将导致用户编写类似 MyState.MYSTATE_ACTIVE 的代码，增加不必要的冗长代码。
• 多个消息使用的枚举 应该 在包级别定义， 应该 将定义放置在proto文件底部（参考AIP-191）。
  • 某些编程语言（包括C++）将枚举值提升到上级命名空间，可能导致同一proto包中具有相同值的枚举相互冲突。为了避免共享值，API 应该 将枚举名字作为前缀，添加到包级枚举值。
• 应该 在文档中记录枚举是处于冻结状态，还是计划在将添加新值。

何时使用枚举

在许多情况下，枚举比字符串或布尔值更易于使用和阅读，但枚举集合的变动会增加工作量。因此枚举 应该 偶尔添加新值。虽然对“偶尔”的定义可能因场景而变化，但一个经验法则是每年不超过一次。对于经常变化的枚举，API 应该 使用字符串并以文档记录格式。

此外枚举 不应 用于存在相似的、被广泛采用的标准表示（例如语言代码或媒体类型）时。

注意： 如果需要在多个API之间共享枚举值， 可以 使用枚举，但枚举值与为其分配的整数 必须 一致。

备选方案

对于允许值集合频繁变栋的枚举值，API 应该 使用 string 域，并且 必须 以文档记录允许的值。包含枚举值的字符串域，其值 应该 使用 kebab-case 格式。

对于存在相似且被广泛采用的标准表示（通常是字符串，但不一定）的枚举值， 应该 使用该标准表示。即使只允许其中一小部分值，这也是合理的，因为在这种情况下使用枚举将导致在同时使用多个API时需要用到令人沮丧的查找表。

在明确不需要更多灵活性的情况下 可以 使用布尔域，默认值 必须 为 false 。

注意： protobuf无法分辨 false 和未设置值的情况。如果需要区分二者， 可以 使用枚举作为更好的设计选择（也可以使用 google.protobuf.BoolValue ）。

进一步阅读

• 状态是一种特殊类型的枚举，请参考AIP-216。