Protocol Buffers 介绍

Protocol Buffers

Protocol Buffers ，协议缓冲区。什么是Protocol Buffers呢？或者我们简称PB 吧。那么Protocol Buffers 是一种与语言无关、与平台无关的可扩展机制，用于序列化结构化的数据。
example

message Person {
    optional string name = 1;
    optional int 32 id = 2;
    optional string email = 3;
}

自定义一个协议

Person john = Person.newBuilder()
    .setId(1234)
    .setName("John Doe")
    .setEmail("[email protected]")
    .build();
output = new FileOutputStream(args[0]);
john.writeTo(output);

Person john = Person.newBuilder().setId(1234).setName("John Doe").setEmail("[email protected]").build();
output = new FileOutputStream(args[0]);
john.writeTo(output);

使用生成的类持久化数据

什么是Protocol Buffers ?
协议缓冲区是谷歌的语言中立、平台中立、可扩展的机制，用于序列化结构化数据。比如xml,但是相比较xml 更小，更快，更简洁。您可以定义一次数据的结构化方式，然后可以使用特殊生成的源代码，使用各种语言，轻松地将结构化数据写入各种数据流和从各种数据流中读取结构化的数据。

支持的语言？
协议缓冲区目前支持java、python、objective-c 和c++ 中生成的代码。有了我们新的proto3语言版本，还可以使用Kotlin、Dart、Go、Ruby、PHP和C#,以及更多的语言。

怎么工作？
1、下载按照pb（协议缓冲区） 编译器
2、阅读概要
3、试试你选择的语言教程

Proto 2

This guide describes how to use the protocol buffer language to structure your protocol buffer data,including .proto file syntax and how to generate data access classes from your .proto files.It covers the proto2 version of the protocol buffers language:for infomation on proto3 syntax,see the Proto3 Language Guide.
本指南介绍了如何使用协议缓冲区语言来构建协议缓冲区数据，包括.proto文件语法以及如何从.proto文件生成数据访问类。它涵盖了proto2版本的协议缓冲语言：有关proto3语法的信息，请参阅proto3语言指南。

定义一个消息类型

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

指定字段类型

在上面的示例中，所有字段都是标量类型：两个整数（page_number和result_per_page）和一个字符串（query）。您也可以像为字段指定其他消息类型一样指定枚举和复合类型

指定字段编号

消息定义中的每个字段都有一个唯一的数字。这些数字用于标识消息二进制格式的字段，一旦使用消息类型，就不应该更改这些数字。范围为1到15的字段号需要一个字节进行编码，包括字段号和字段类型（您可以在协议缓冲区编码中找到更多信息）。16到2047范围内的字段编号占用两个字节。因此，您可以为频繁出现的消息元素保留字段编号1到15.请记住为将来可能添加的频繁出现的元素留出一些空间。
您可以指定的最小字段号为1，最大字段号为229-1或536870911。您也不能使用数字19000到19999（FieldDescriptor:：kFirstReservedNumber到FieldDescriptor：：kLastReservedNumber），因为它们是为协议缓冲区实现保留的-如果您在.proto中使用这些保留数字中的一个，协议缓冲区编译器会抱怨。同样，您不能使用任何以前保留的字段数字

指定字段规则

您可以指定消息字段是以下字段之一：
必需：一个格式良好的消息必须恰好包含其中一个字段。
可选：格式良好的消息可以有零个或一个此字段（但不能超过一个）。
repeated：此字段可以在格式良好的消息中重复任意次数（包括零次）。重复值的顺序将被保留。
由于历史原因，标量数字类型的重复字段（例如，int32、int64、enum）的编码效率不如预期。新代码应该使用特殊选项[packed=true]来获得更高效的编码。例如：

repeated int32 samples = 4 [packed = true];
repeated ProtoEnum results = 5 [packed = true];

You can find out more about packed encoding in Protocol Buffer Encoding.

Important
Required Is Forever You should be very careful about marking fields as required. If at some point you wish to stop writing or sending a required field, it will be problematic to change the field to an optional field – old readers will consider messages without this field to be incomplete and may reject or drop them unintentionally. You should consider writing application-specific custom validation routines for your buffers instead.

A second issue with required fields appears when someone adds a value to an enum. In this case, the unrecognized enum value is treated as if it were missing, which also causes the required value check to fail

添加更多的消息类型

在一个.proto文件中可以定义多个消息类型。如果您正在定义多个相关消息，这很有用，例如，如果您想定义与SearchResponse消息类型相对应的回复消息格式，可以将其添加到相同的格式中。proto：

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

message SearchResponse {
 ...
}

组合消息会导致膨胀虽然可以在单个.proto文件中定义多个消息类型（如消息、枚举和服务），但当在单个文件中定义大量具有不同依赖关系的消息时，也会导致依赖关系膨胀。建议每个.proto文件包含尽可能少的消息类型

添加注释

To add comments to your .proto files, use C/C+±style // and /* … */ syntax.

/* SearchRequest represents a search query, with pagination options to
 * indicate which results to include in the response. */

message SearchRequest {
  required string query = 1;
  optional int32 page_number = 2;  // Which page number do we want?
  optional int32 result_per_page = 3;  // Number of results to return per page.
}

// 单行
/**/多行

保留字段

如果通过完全删除字段或注释掉字段来更新消息类型，则未来的用户可以在对该类型进行自己的更新时重用字段号。如果他们以后加载相同.proto的旧版本，包括数据损坏、隐私漏洞等，这可能会导致严重问题。确保这种情况不会发生的一种方法是指定已删除字段的字段号（和/或名称，这也可能导致JSON序列化问题）是保留的。如果将来有用户试图使用这些字段标识符，协议缓冲区编译器将发出抱怨。

message Foo {
  reserved 2, 15, 9 to 11;
  reserved "foo", "bar";
}

保留字段编号范围包括在内（9到11与9、10、11相同）。请注意，不能在同一保留语句中混用字段名和字段号

What’s Generated From Your .proto?

当你在.proto上运行协议缓冲区编译器时，编译器会用你选择的语言生成代码，你需要使用文件中描述的消息类型，包括获取和设置字段值，将消息序列化到输出流，以及从输入流解析消息。
对于C++，编译器从每个.proto生成一个.h和.cc文件，文件中描述的每个消息类型都有一个类。

对于Java，编译器为每种消息类型生成一个.Java文件，其中包含一个类，以及用于创建消息类实例的特殊Builder类。

Python有点不同——Python编译器生成一个模块，其中包含.proto中每个消息类型的静态描述符，然后与元类一起使用，以在运行时创建必要的Python数据访问类。

对于Go，编译器会生成一个.pb.Go文件，其中包含文件中每个消息类型的类型

可选字段和默认值

如上所述，消息描述中的元素可以标记为可选。格式良好的消息可以包含也可以不包含可选元素。解析消息时，如果消息不包含可选元素，则访问解析对象中的相应字段将返回该字段的默认值。默认值可以指定为消息描述的一部分。例如，假设您希望为SearchRequest的result_per_page值提供默认值10。

optional int32 result_per_page = 3 [default = 10];

如果没有为可选元素指定默认值，则使用特定类型的默认值：对于字符串，默认值为空字符串。对于字节，默认值为空字节字符串。对于bools，默认值为false。对于数字类型，默认值为零。对于枚举，默认值是枚举的类型定义中列出的第一个值。这意味着在向枚举值列表的开头添加值时必须小心。有关如何安全更改定义的指导方针，请参阅“更新消息类型”部分