0.说明

ProtoBuf3语法指南，
又称为proto3，
是谷歌的Protocol Buffers第3个版本。
本文基于官方英文版本翻译，
加上了自己的理解少量修改，
一共分为上下两部分。

1.序言

本指南描述了如何使用protocol buffer语言来构造protocol buffer数据，
包括编写.proto文件的语法，
以及如何从.proto文件生成数据访问类。
本文涵盖了protocol buffer语言的proto3版本语法，
而有关proto2版本语法的信息，
请参阅proto2语法指南。

下面将通过一个一个示例，
逐步展示文档中描述的许多特性。

2.定义一个消息类型

先来看一个非常简单的例子。
假设你想定义一个"搜索请求"的消息格式，
每一个请求含有一个查询字符串、
你感兴趣的查询结果所在的页数，
以及每一页查询结果的条数。
下面是用于定义消息类型的.proto文件：

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

-文件的第一行指定了你正在使用proto3语法，如果你没有指定，编译器会默认使用proto2。这个必须是文件的非空非注释的第一个行。
-SearchRequest消息定义了3个字段(名称/值对)，每个字段对应了需要在消息中承载的数据，且都有一个名字和一种类型。

2.1.指定字段类型

在上面的例子中，所有字段都是标量类型:
两个整数类型(page_number和result_per_page)
和一个字符串类型(query)。
还可以为字段指定复合类型，
包括枚举和其他消息类型。

2.2.分配字段编号

消息定义中的每个字段都有一个唯一的数字编号。
这些编号用于在消息的二进制格式中标识字段，
一旦编号被使用就不应该再改变。
注意：[1,15]之内的编号在编码的时候会占用一个字节，
包括字段编号和字段类型，
可以在Protocol Buffer Encoding中找到更多有关信息,
[16,2047]之内的编号则占用2个字节。
因此应该为频繁出现的消息元素保留数字[1,15]之内的编号，
记住为将来可能添加的频繁出现的元素预留一些编号。
最小的标识号可以从1开始，最大到2^29 - 1, or 536,870,911。
不可以使用其中的[19000－19999]的标识号，
从FieldDescriptor::kFirstReservedNumber到FieldDescriptor::kLastReservedNumber，
Protobuf协议实现中对这些进行了预留。
如果非要在.proto文件中使用这些预留的编号，
编译时就会报警。
同样你也不能使用早期保留的编号。

2.3.指定字段规则

消息字段的修饰符必须是如下之一：

• singular：一个格式良好的消息中，应该有0个或者1个这种字段（但是不能超过1个）。这是proto3语法的默认字段规则。
• repeated：一个格式良好的消息中，这种字段可以重复任意多次（包括0次）。重复的值的顺序将保持不变。相当于Java中的List列表。
  在proto3中，标量数值类型的重复字段默认使用packed编码。
  可以在Protocol Buffer Encoding中找到关于打包编码的更多信息。

2.4.添加更多消息类型

在一个.proto文件中可以定义多个消息类型。
如果想定义SearchRequest的响应消息格式SearchResponse，
可以将它们添加到相同的.proto文件：

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

2.5.添加注释

要向.proto文件添加注释，
请使用C/C++/Java风格的双斜杠（//）和/… /语法：

/* SearchRequest represents a search query, with pagination options to* indicate which results to include in the response. */message SearchRequest {string query = 1;int32 page_number = 2;  // Which page number do we want?int32 result_per_page = 3;  // Number of results to return per page.
}

2.6.保留字段

当你需要修改消息类型时，
如果删除或者注释了某个字段，
后来的用户可以在修改该消息类型时，
可能会重用该字段的名称和数字编号。
如果以后不小心加载了相同的.proto文件的旧版本，
这可能会导致严重的问题，
包括数据损坏、隐私问题等等。
确保不会发生这种情况的一种方法是，
指定保留已删除字段的名称(因为这也会导致JSON序列化问题)和数字编号。
如果将来有任何用户试图使用这些字段标识符，
protocol buffer的编译器会发出警告。

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

注意不要在一行reserved声明中同时包括字段的名称和数字编号。

2.7.从.proto文件生成了什么？

当使用protocol buffer编译器来运行.proto文件时，
编译器将生成所选择语言的代码，
这些代码可以操作在.proto文件中定义的消息类型，
包括获取、设置字段值，
将消息序列化到一个输出流中，
以及从一个输入流中解析消息。

• 对于c++，编译器会从每个.proto生成一个.h和.cc文件，并为文件中描述的每个消息类型生成一个类。
• 对于Java，编译器为每一个消息类型生成了一个.java文件，以及用于创建消息类实例的特殊Builder类。
• 对于Python，稍有不同，Python编译器为.proto文件中的每个消息类型生成一个含有静态描述符的模块，该模块与一个元类（metaclass）在运行时（runtime）被用来创建所需的Python数据访问类。
• 对于Go，编译器会位每个消息类型生成了一个.pd.go文件。
• 对于Ruby，编译器会为每个消息类型生成了一个.rb文件。
• 对于Objective-C，编译器会为每个消息类型生成了一个pbobjc.h文件和pbobjcm文件，.proto文件中的每一个消息有一个对应的类。
• 对于c#，编译器会为每个消息类型生成了一个.cs文件，.proto文件中的每一个消息有一个对应的类。
• 对于Dart，编译器会为每个消息类型生成了一个.pb.dart文件，.proto文件中的每一个消息有一个对应的类。

可以通过所选择的语言的教程(即将发布的proto3版本),
了解更多关于每种语言使用api的信息。
更多API细节，请参阅相关API参考(proto3版本也即将发布)。

3.标量值类型

一个标量消息字段可以是以下类型，
表格显示了.proto文件中支持的类型，
以及自动生成的类中对应语言的类型:

你可以在Protocol Buffer Encoding中，
找到更多"序列化消息时这些类型如何编码"的信息。

[1] 在java中，无符号32位和64位整型被表示成他们的相对的有符号整型类型，最高位储存在符号位中。
[2] 在所有的情况下，设定值的时候，会执行类型检查以确保此值是有效的。
[3] 64位或者无符号32位整型在解码时总是表示为long，但如果在设置字段时使用int，则可以表示为int。在所有情况下，值必须符合在设置时所使用的类型。请参阅[2]。
[4] Python字符串在解码时表示为unicode，但如果给定ASCII字符串，则可以表示为str(这可能会改变)。
[5] Integer在64位的机器上使用，string在32位机器上使用

4.默认值

在解析消息时，如果已编码的消息不包含特定的singular元素，
则解析对象中的对应字段将被设置为该字段的默认值。
对于不同类型的默认值如下：

• 对于string，默认值是一个空string。
• 对于byte，默认值是一个空的bytes。
• 对于bool，默认值是false。
• 对于数值类型，默认值是0。
• 对于枚举类型，默认值是第一个定义的枚举值，且必须为0。
• 对于消息类型，没有默认值，它的确切值取决于选择的语言，请参考生成的代码指南

可重复字段的默认值为空，
通常情况下是对应语言中空列表。
注意对于标量消息字段，
一旦消息被解析，
就无法判断一个字段是否显式地设置为默认值，
还是根本没有被设置:
例如boolean值是否被显示设置为false，
还是没有设置，而使用了默认值false。
你应该在定义消息类型时牢记这一点。
如果你不想让某个行为在默认情况下发生，
就不要设置一个布尔值来开启某个行为。
如果将标量消息字段设置为默认值，
则该值将不会在传输时被序列化。
有关默认值如何在生成代码中工作的详细信息，
请参考所选语言的生成的代码指南。

5.枚举

在定义消息类型时，
可能想为一个字段指定"预定义的值列表"中的一个值。
假设给SearchRequest添加一个corpus字段，
其中corpus的值可能是UNIVERSAL，WEB，IMAGES，LOCAL，NEWS，PRODUCTS或VIDEO中的一个
只需要向消息定义中添加一个枚举（enum），
并且为每个可能的值定义一个常量就可以了。
在下面的例子中，
添加了一个名为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，
否则编译器会在找到别名时报告错误。

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值传输时使用可变编码，
对负数不够高效，因此不推荐在enum中使用负数。
如上所示，
可以在一个消息定义的内部或外部定义枚举，
这些枚举可以在.proto文件中的任何消息定义里使用。
当然也可以在一个消息中定义一个枚举类型，
而在另一个不同的消息中使用它，
采用MessageType.EnumType的语法格式。

当对一个使用了枚举的.proto文件运行protocol buffer编译器的时候，
生成的代码中将有一个对应的enum（对Java或C++来说），
或者一个特殊的EnumDescriptor类（对 Python来说），
它被用来在运行时生成的类中创建一系列的整型值符号常量。

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

在反序列化的过程中，
无法识别的枚举值会被保存在消息中，
尽管在反序列化消息时如何表示该值取决于选择的语言。
在那些支持开放枚举类型超出指定范围之外的语言中（例如C++和Go），
无法识别的值会被简单的表示成所支持的整型。
在具有封闭枚举类型的语言中（例如Java），
使用枚举中的一个类型来表示无法识别的值，
并且可以使用特殊的访问器访问底层整数。
在其他情况下，如果消息被序列化，
那么无法识别的值仍将与消息一起序列化。

关于如何在应用程序的消息中使用枚举的更多信息，
请参考所选语言的生成的代码指南。

5.1.保留字段

枚举的保留字段和上面消息的保留字段基本相同：

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

6.使用其他消息类型

你可以将其他消息类型用作字段类型。
例如在SearchResponse消息中包含Result消息，
此时可以在相同的.proto文件中定义一个Result消息类型，
然后在SearchResponse消息中指定一个Result类型的字段：

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

6.1.导入定义

在上面的例子中，
Result消息类型与SearchResponse是定义在同一文件中的。
如果想要使用的消息类型已经在其他.proto文件中已经定义过了呢？
你可以通过导入其他.proto文件中的定义来使用它们。
要导入另一个.proto的定义，
需要在文件的顶部添加一条导入声明：

import "myproject/other_protos.proto";

默认情况下，只能使用直接导入的.proto文件中的定义。
但是有时可能需要将.proto文件移动到新的位置。
可以在旧位置放置一个假的.proto文件，
使用import public将所有导入转向到新位置，
而不是直接移动.proto文件，
并且修改所有调用的位置。
任何导入包含import public的proto文件，
都可以通过传递依赖导入公共依赖项。
例如：

// new.proto
// All definitions are moved here

// old.proto
// This is the proto that all clients are importing.
import public "new.proto";
import "other.proto";

// client.proto
import "old.proto";
// You use definitions from old.proto and new.proto, but not other.proto

通过在编译器命令行参数中使用-I/--proto_path参数，
protocal编译器会在指定目录搜索要导入的文件。
如果没有指定目录，
则在调用编译器的目录中查找。
通常只需要配置proto_path为工程根目录，
并且正确配置需要导入的名称即可。

6.2.使用proto2消息类型

在proto3中导入proto2的消息类型也是可以的，
反之亦然，
然而proto2枚举不可以直接在proto3语法中使用，
如果仅仅在被导入的proto2消息中使用是可以的。

7.嵌套类型

可以在其他消息类型中定义和使用消息类型，
在下面的例子中，
Result消息就定义在SearchResponse消息内：

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

如果想在它的父消息类型的外部重用这个消息类型，
需要使用Parent.Type的形式的语法：

message SomeOtherMessage {SearchResponse.Result result = 1;
}

也可以将消息嵌套任意多层：

message Outer {                  // Level 0message MiddleAA {  // Level 1message Inner {   // Level 2int64 ival = 1;bool  booly = 2;}}message MiddleBB {  // Level 1message Inner {   // Level 2int32 ival = 1;bool  booly = 2;}}
}

8.更新一个消息类型

如果现有的消息类型不再满足新的需求，
如果要在消息中添加一个额外的字段，
但是同时保持旧版本写的代码仍然可用。
不用担心，
在不破坏任何现有代码的情况下更新消息类型非常简单，
只要记住以下规则:

• 不要更改任何现有字段的数字编号。
• 如果增加新的字段，那么使用旧格消息格式的代码序列化的任何消息，仍然可以被新产生的代码解析。你应该记住这些元素的默认值，这样新代码就可以正确的和旧代码生成的消息交互。类似的，通过新代码产生的消息也可以被旧代码解析：只不过新的字段在解析时会被忽略掉。更多详细信息，请参阅无法识别字段章节的内容。
  可以删除字段，只要字段号不在更新的消息类型中再次使用。
• 只要字段的数字编号在新的消息类型中不再使用，这些字段就可以移除，更好的做法可能是重命名那个字段，例如在字段前添加"OBSOLETE_"前缀，或者保留字段编号，以便将来不会意外地重用该数字。
• int32、uint32、int64、uint64和bool是都是兼容的，这意味着可以将字段从其中一种类型更改为另一种类型，而不会破坏向前或向后的兼容性。如果解析出来的数字与对应的类型不相符，那么结果就像在C++中对它进行了强制类型转换一样，例如把一个64位数字当作int32来 读取，那么它就会被截断为32位的数字。
• sint32和sint64是互相兼容的，但与其他整数类型不兼容。
• string和bytes是兼容的，只要bytes是有效的UTF-8编码。
• 嵌套消息与bytes是兼容的，只要bytes包含该消息的一个编码过的版本。
• fixed32与sfixed32是兼容的，fixed64与sfixed64是兼容的。
• 对于string、bytes和消息字段，optional与repeated是兼容的。给定重复字段的序列化数据作为输入，如果该字段是原始类型字段，则期望该字段是optional的，客户端将接受最后一个输入值;如果该字段是消息类型字段，则将合并所有输入元素。注意对于数值类型，包括布尔和枚举，这通常是不安全的。数值类型的repeated字段可以用packed格式序列化，然而对于optional字段时，将不能被正确解析。
• enum兼容int32、uint32、int64和uint64，注意不兼容的值将被截断。然而在客户端反序列化之后可能会有不同的处理方式:例如，无法识别的proto3枚举类型将保留在消息中，但是在对消息进行反序列化时如何表示它是依赖于语言的。int字段总是保留它们的值。
• 将一个值更改为一个新值的成员是安全的和二进制兼容的。如果保证代码不会一次设置多个字段，那么将多个字段移到一个新的字段中可能是安全的。将任何字段移动到现有字段中是不安全的。

9.未知字段

未知字段是格式良好的protocol buffer 序列化数据，
但是解析器无法识别的字段。
例如，当旧二进制文件解析带有新字段的新二进制文件发送的数据时，
这些新字段在旧二进制文件中成为未知字段。
最初，proto3总是在解析时丢弃未知字段，
但在3.5版本中，重新引入了保留未知字段的功能，
以匹配proto2的行为。
在版本3.5及更高版本中，
解析时会保留未知字段，并包含在序列化输出的数据中。

10.参考文章

Language Guide (proto3)
Protobuf3教程
ProtoBuf v3 语法简介
gRPC之proto语法