从事网站建设在线资源搜索神器
| 编号 | 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。