Tensorflow的Protocol Buffers3编程(一)

Proto3.0.0 Release Note，前面入门caffe之初，有详细介绍过2.x的版本，不熟悉的可以找找，这里不罗列了。

Proto3

• 引入 Protocol Buffers 语言版本 3 (称为 proto3)

  当 protocol buffers 最初开源时，它实现了 Protocol Buffers 语言版本 2 (称为 proto2), 这也是为什么版本数从 v2.0.0 开始。从 v3.0.0 开始， 引入新的语言版本(proto3)，而旧的版本(proto2)继续被支持。

  引入proto3的主要意图是在将这个语言推向 google 新的API平台之前清理 protobuf。在 proto3 中，语言被简化，即便于使用又可以用于更大范围的编程语言。同时添加了一些新的特性来更好的支持 API 中的通用习语。

  下面是语言版本3中主要的新特性：

  1. 移除用于原生值字段的字段表述逻辑，移除必填(required)字段，并移除默认值。这显著的简化了 proto3 在实现开放结构标示(open struct representations)中实现，例如在如Android Java, Objective C, 或者 Go 语言中。
  2. 移除未知字段
  3. 移除扩展(extensions)，替代为新的称为 Any 的标准类型
  4. 修复未知枚举值的语义
  5. 此外还有 map (向后移植到proto2)
  6. 此外还有少量用于表述时间，动态日志等的标准类型 (向后移植到proto2)

  7. 定义良好的JSON编码，作为二进制编码之外的备选

     引入了一个新的概念 "syntax" 来指定一个.proto文件使用的是 proto2 还是 proto3：

     // foo.proto
     syntax = "proto3";
     message Bar {...}
     

     如果没有设置，protocol buffer编译器将生成警告而"proto2"会被默认使用。在未来版本中这个警告将可能变成错误。

     我们推荐新的Protocol Buffers 用户使用proto3.当然，我们不普遍推荐现有用户从proto2迁移到proto3,因为API不兼容，而我们将继续长期支持proto2.

     proto3中的其他重要改动：

• 在proto3语法中显式的 "optional" 关键字被禁止，因为字段默认就是可选的;必填字段不再被支持

• 删除非零默认值，而用于非message字段的字段表述逻辑如 has_xxx() 方法被删除;设置为默认值(对于数字字段是0,字符串/字节字段是空)的原生字段在序列化时被跳过
• 在proto3语法中group字段不再支持
• 在proto3中默认修改重复原生字段来支持打包序列化（当前版本中在C++, Java, Python中实现）。用户依然可以通过设置packed为false来禁用打包序列化
• 添加众所周知的类型 protos (any.proto, empty.proto, timestamp.proto, duration.proto 等).用户可以导入并使用这些protos，就像正规的proto文件一样。额外的运行时支持在每个语言中都可用。

• Proto3 JSON在一些语言中 (在C++, Java, Python 和 C# 中被完全支持， 在 Ruby 中被部分支持)被支持。 JSON 规范在proto3语言指南中被定义：

  https://developers.google.com/protocol-buffers/docs/proto3#json

  我们将发布更详细的规范来定义 proto3-顺应 的JSON序列器和解析器的确切行为。在此之前，请不要依赖实现的特定行为，如果他们没有在上面的规范中注明。

• Proto3强制严格 UTF-8 检查。如果字符串字段包含非UTF-8数据则解析将失败。

普遍

• 因为新的语言实现 (C#, JavaScript, Ruby, Objective-C)到proto3

• 添加对 map 字段的支持(同时在proto2和proto3中实现)。

  map字段可以使用下面的语法声明：

    message Foo {
      map values = 1;
    }
  

  map字段的数据在内存中被存储为未排序的map并可以通过生成的访问器来访问。

• 在 proto2 和 proto3 语法中同时添加 "reserved" (保留) 关键字。用户可以用这个关键字来声明保留字段数字和名称来防止他们被在同一个消息中的其他字段重用。

  为了保留字段数字，在消息中添加保留声明：

    message TestMessage {
        reserved 2, 15, 9 to 11, 3;
    }
  

  这将保留字段数字 2, 3, 9, 10, 11 and 15。如果用户使用他们中的任何一个作为字段数字，protocol buffer 编译器将报告错误。

  字段名字也可以被保留：

    message TestMessage {
        reserved "foo", "bar";
    }
  

• 添加一个确定性的序列化API(当前在c++中可用)。这个确定性序列化保证：给定的一个二进制，等同的消息将被序列化为同样的字节。这容许应用如MapReduce基于被序列化后的字节来分组相等的消息。这个确定性序列化 不 跨语言。在使用schema跨越不同build时也是不稳定的。需要权威序列化的用户，如以权威形式永久保存，指纹等，应该定义自己的权威性规范并使用反射API来实现序列器，而不是依赖这个API。

• 添加新的字段选项"json_name"。默认在proto3的JSON格式中 proto 字段名将被转换为"lowerCamelCase"(小写开头的驮峰法)。这个选项被用于覆盖这个行为并为这个字段指定不同的JSON名字。
• 添加一致性测试来确保实现遵循 proto3 JSON 规范

  章节列表：

  • 定义消息类型
  • Scalar值类型
  • 默认值
  • 枚举
  • 使用其他消息类型
  • 内嵌类型
  • 更新消息类型
  • Any
  • Oneof
  • Maps
  • 包
  • 定义服务
  • JSON 映射
  • 选项
  • 生成类
  
  

定义消息类型

注：内容翻译自官网文档 Language Guide (proto3) 中的 Defining A Message Type 一节

首先我们来看一个非常简单的例子. 让我们假设你想定义一个搜索请求消息格式, 每个搜索请求有一个查询字符串, 搜索结果的第几页/每页结果数量. 这里是你用来定义消息类型的.proto文件:

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

1. 第一行指明当前使用的是proto3语法, 如果不指定则默认为proto2. 必须是.proto文件的除空行和注释内容之外的第一行
2. SearchRequest 消息定义指明了3个字段. 每个字段有名字和类型.

Scalar值类型

简单消息字段可以有下列类型其中之一 - 下面的表格显示在.proto文件中指明的类型和在自动生成类中的相应类型.

注: 原表格太复杂, 翻译没有必要, 请见原页面.

下面是简化版本, 只列出了我关心的java类型映射:

.proto Type	Java Type
double	double
float	float
int32	int
int32	int
int64	long
bool	boolean
string	String
bytes	ByteString

默认值

当消息被解析时, 如果被编码的消息没有包含特定的简单元素, 被解析的对象对应的字段被设置为默认值. 默认值是和类型有关的:

• 对于strings, 默认值是空字符串(注, 是"", 而不是null)
• 对于bytes, 默认值是空字节(注, 应该是byte[0], 注意这里也不是null)
• 对于boolean, 默认值是false.
• 对于数字类型, 默认值是0.
• 对于枚举, 默认值是第一个定义的枚举值, 而这个值必须是0.
• 对于消息字段, 默认值是null.

对于重复字段, 默认值是空(通常都是空列表)

注意: 对于简单字段, 当消息被解析后, 是没有办法知道这个字段到底是有设置值然后恰巧和默认值相同(例如一个boolean设置为false)还是这个字段没有没有设置值而取了默认值. 例如, 不要用一个boolean值然后当设置为false时来切换某些行为, 而你又不希望这个行为默认会发生. 同样请注意: 如果一个简单消息字段被设置为它的默认值, 这个值不会被序列化.

枚举

当你定义消息类型时, 你可能希望某个字段只能有预先定义的多个值中的一个. 例如, 假设你想为每个SearchRequest添加一个corpus字段, 而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的常量作为它的第一个元素. 这是因为:

• 必须有一个0值, 这样我们才能用0来作为数值默认值.
• 0值必须是第一个元素, 兼容proto2语法,在proto2中默认值总是第一个枚举值

可以通过将相同值赋值给不同的枚举常量来定义别名. 为此需要设置allow_alias选项为true, 否则当发现别名时protocol编译器会生成错误消息.

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位整形的范围内. 由于枚举值使用varint encoding, 负值是效率低下的因此不推荐使用.你可以在消息定义中定义枚举, 如前面例子那样, 或者在外部 - 这些枚举可以在.proto文件的任意消息定义中重用. 你也可以用在一个消息中声明的枚举类型作为别的消息的字段类型, 需要使用语法MessageType.EnumType.

当你运行protocol buffer 编译器处理使用枚举的.proto文件时, 生成的代码将会有java或c++的对应枚举, 对于Python, 在生成的运行时类中会有一个特别的EnumDescriptor用于创建带有整型值的symbolic常量集合.

在反序列过程中, 未被识别的枚举值将被保留在消息中, 但是当消息被反序列号时将会如何表现是和语言有关的. 在支持开放枚举类型可以用定义范围之外的值的语言中, 例如C++和Go, 未知的枚举值被简单保存为它底层整型描述. 在封闭枚举类型的语言例如Java中, 一个枚举的特例用于表示这个未识别的值, 底层整型可以被特殊的访问器访问. 在其他案例中, 如果消息被系列化, 这个未识别的值将和消息一起被序列化.

使用其他消息类型

可以使用其他消息类型作为字段类型. 例如, 假设你想在每个SearchResponse消息中包含Result消息 - 为了做到这点, 你可以在相同的.proto文件中定义Result消息类型然后具体指定SearchResponse中的一个字段为Result类型:

message SearchResponse {
  repeated Result result = 1;
}

message Result {
  string url = 1;
  string title = 2;
  repeated string snippets = 3;
}