开发学院,分享开发教程和最新动态
章节列表 什么是ProtobufProtobuf3 定义数据类型Protobuf3 标量值类型Protobuf3 缺省值Protobuf3 枚举Protobuf3 使用其他消息类型Protobuf3 嵌套类型Protobuf3 更新消息类型Protobuf3 未知字段Protobuf3 Any类型Protobuf3 OneofProtobuf3 MapsProtobuf3 包Protobuf3 定义服务Protobuf3 JSON映射Protobuf3 可选项Protobuf3 生成属于自己的类Protobuf 风格指南Protobuf 编码(1)Protobuf 编码(2)Protobuf 编码(3)Protobuf 技术Protocol Buffer C++实例教程: 为什么使用Protocol Buffer?Protocol Buffer C++实例教程: 定义协议格式Protocol Buffer C++实例教程: 编译Protocol BufferProtocol Buffer C++实例教程: Protocol Buffer APIProtocol Buffer C++实例教程: 发送消息Protocol Buffer C++实例教程: 读取消息Protocol Buffer C++实例教程: 扩展Protocol BufferProtocol Buffer C++实例教程: 优化技巧和高级用法Protocol Buffer C#实例教程: 前言Protocol Buffer C#实例教程:定义协议格式Protocol Buffer C#实例教程:编译Protocol Buffer Protocol Buffer C#实例教程:解析和序列化Protocol Buffer Go实例教程:前言Protocol Buffer Go实例教程:定义协议格式Protocol Buffer Go实例教程:编译Protocol BufferProtocol Buffer Go实例教程:读写消息Protocol Buffer JAVA实例教程:前言Protocol Buffer JAVA实例教程:定义协议格式Protocol Buffer JAVA实例教程:编译Protocol BufferProtocol Buffer JAVA实例教程:Protocol Buffer APIProtocol Buffer JAVA实例教程:写消息Protocol Buffer JAVA实例教程:读消息Protocol Buffer JAVA实例教程:扩展Protocol BufferProtocol Buffer Python实例教程:前言Protocol Buffer Python实例教程:定义消息格式Protocol Buffer Python实例教程:编译Protocol BufferProtocol Buffer Python实例教程:Protocol Buffer APIProtocol Buffer Python实例教程:写消息Protocol Buffer Python实例教程:读取MessageProtocol Buffer Python实例教程:扩展Protocol Buffer

Protobuf3 枚举

Protobuf3 枚举

  定义消息类型时,您可能希望它的一个字段有一个预定义的值列表。例如,假设您希望为每个SearchRequest添加一个corpus字段,其中语料库可以是UNIVERSAL、WEB、IMAGES、LOCAL、NEWS、PRODUCTS 或VIDEO。您可以非常简单地通过在消息定义中添加枚举来实现这一点,每个可能的值都是一个常量。

  在下面的例子中,我们添加了一个名为Corpus 的枚举和一个类型为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,每个枚举定义必须包含一个映射到零的常量作为第一个元素。这是因为:

  必须有零值,这样我们就可以使用0作为数值默认值。

  零值必须为第一个元素,以便与proto 2语义兼容,其中第一个枚举值总是默认的。

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

enum EnumAllowingAlias {
  option allow_alias = true;
  UNKNOWN = 0;
  STARTED = 1;
  RUNNING = 1;
}
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值在传输中使用不同的编码,负值效率低下,因此不推荐使用。您可以在消息定义中定义枚举,如上例所示,也可以在消息定义之外定义枚举——这些枚举可以在 .proto文件中的消息定义中重用。您也可以使用语法MessageType.EnumType,将一条消息中声明的枚举类型用作另一条消息中字段的类型

  当你在.proto文件上使用枚举运行协议缓冲区编译器时,生成的代码将具有Java或c++的相应枚举,Python使用一个EnumDescriptor类,用于在运行时生成的类中创建一组具有整数值的符号常量。

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

  有关如何在应用程序中使用消息枚举的详细信息,请参阅为您选择的语言生成的代码指南。

保留值

  如果通过完全删除枚举条目或注释来更新枚举类型,将来的用户可以在对该类型进行自己的更新时重用数值。如果他们以后加载旧版本的相同 .proto内容,这可能会导致严重的问题。包括数据损坏、隐私漏洞等。确保不会发生这种情况的一种方法是指定保留已删除条目的数值(and/or名称,这也会导致JSON序列化问题)。如果将来有任何用户试图使用这些标识符,协议缓冲区编译器会报错。您可以使用max关键字指定保留的数值范围达到可能的最大值。

enum Foo {
  reserved 2, 15, 9 to 11, 40 to max;
  reserved "FOO", "BAR";
}

  请注意,不能在同一保留语句中混合字段名和数值。