Protocol Buffers枚举类型

在定义消息类型时，你可能希望其字段之一仅具有预定义的值列表之一。例如，假设你要corpus为每个 添加一个字段，SearchRequest其中语料库可以是UNIVERSAL、WEB、IMAGES、LOCAL、NEWS或。你可以通过在消息定义中添加一个非常简单的方法来做到这一点，并为每个可能的值添加一个常量。PRODUCTS``VIDEO``enum

在下面的示例中，我们添加了一个包含所有可能值的enum调用Corpus，以及一个 type 字段Corpus：

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
  enum Corpus {
    UNIVERSAL = 0;
    WEB = 1;
    IMAGES = 2;
    LOCAL = 3;
    NEWS = 4;
    PRODUCTS = 5;
    VIDEO = 6;
  }
  Corpus corpus = 4;
}

Corpus枚举的第一个常量映射到零：每个枚举定义都必须包含一个映射到零的常量作为其第一个元素。这是因为：

• 必须有一个零值，以便我们可以使用 0 作为数字默认值。
• 零值必须是第一个元素，以与第一个枚举值始终为默认值的proto2语义兼容。

你可以通过将相同的值分配给不同的枚举常量来定义别名。为此，你需要将allow_alias选项设置为true，否则协议编译器将在找到别名时生成错误消息。

message MyMessage1 {
  enum EnumAllowingAlias {
    option allow_alias = true;
    UNKNOWN = 0;
    STARTED = 1;
    RUNNING = 1;
  }
}
message MyMessage2 {
  enum EnumNotAllowingAlias {
    UNKNOWN = 0;
    STARTED = 1;
    // RUNNING = 1;  // Uncommenting this line will cause a compile error inside Google and a warning message outside.
  }
}

枚举器常量必须在 32 位整数范围内。由于enum值在线路上使用varint 编码，因此负值效率低下，因此不推荐使用。你可以enum在消息定义中定义 ，如上例所示，也可以在外部定义 - 这些enums 可以在.proto文件中的任何消息定义中重复使用。你还可以使用enum在一条消息中声明的类型作为另一条消息中字段的类型，使用语法_MessageType_._EnumType_.

当你在.proto使用 的a 上运行协议缓冲区编译器时enum，生成的代码将有一个对应enum于 Java、Kotlin 或 C++ 的代码，或者一个EnumDescriptor用于 Python 的特殊类，用于在运行时创建一组具有整数值的符号常量——生成的类。

注意： 生成的代码可能会受到特定于语言的枚举数限制（一种语言的低千）。请查看你计划使用的语言的限制。

在反序列化期间，无法识别的枚举值将保留在消息中，尽管在反序列化消息时如何表示这取决于语言。在支持具有超出指定符号范围的值的开放枚举类型的语言中，例如 C++ 和 Go，未知的枚举值简单地存储为其底层整数表示。在 Java 等具有封闭枚举类型的语言中，枚举中的 case 用于表示无法识别的值，并且可以使用特殊的访问器访问底层整数。在任何一种情况下，如果消息被序列化，则无法识别的值仍将与消息一起序列化。

有关如何enum在应用程序中使用 message 的更多信息，请参阅为你选择的语言生成的代码指南。