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.

This is a reference guide – for a step by step example that uses many of the features described in this document, see the tutorial for your chosen language.

语言指南

l 定义一个消息（message）类型

l 标量值类型

l 可选的（optional）字段以及默认值

l 枚举

l 使用其他消息类型

l 嵌套类型

l 更新一个消息类型

l 扩展

l 包（package）

l 定义服务（service）

l 选项（option）

l 生成访问类

本指南描述了怎样使用protocol buffer语言来构造你的protocol buffer数据，包括.proto文件语法以及怎样生成.proto文件的数据访问类。

本文是一个参考指南——如果要查看如何使用本文中描述的多个特性的循序渐进的例子，请在tutorial中查找你需要的语言的教程。

Defining A Message Type 定义一个消息类型

First let's look at a very simple example. Let's say you want to define a search request message format, where each search request has a query string, the particular page of results you are interested in, and a number of results per page. Here's the .proto file you use to define the message type.

首先看一个非常简单的例子。假设你想定义一个“搜索请求”（search request）的消息格式，每一个搜索请求含有一个查询字符串、你感兴趣的查询结果所在的页数，以及每一页多少条查询结果。那么下面这个就是用来定义消息类型的.proto文件了：

message SearchRequest {

required string query = 1;

optional int32 page_number = 2;

optional int32 result_per_page = 3;

}

The SearchRequest message definition specifies three fields (name/value pairs), one for each piece of data that you want to include in this type of message. Each field has a name and a type.

SearchRequest消息类型指定了3个字段（名/值 对），你想在消息中承载的数据分别对应于每一个字段。每个字段都有一个名字（name）和一个类型（type）。

Specifying Field Types 指定字段类型

In the above example, all the fields are scalar types: two integers (page_number and result_per_page) and a string (query). H owever, you can also specify composite types for your fields, including enumerations and other message types.

在上面的例子中，所有字段都是标量类型（scalar types）:两个整型（page_number和result_per_page），一个string（query）。然而，你也可以为字段指定合成的类型，包括枚举（enumerations）以及其他消息类型。

Assigning Tags 分配标识号

As you can see, each field in the message definition has a unique numbered tag. These tags are used to identify your fields in the message binary format , and should not be changed once your message type is in use. Note that tags with values in the range 1 through 15 take one byte to encode. Tags in the range 16 through 2047 take two bytes. So you should reserve the tags 1 through 15 for very frequently occurring message elements. Remember to leave some room for frequently occurring elements that might be added in the future.

The smallest tag number you can specify is 1, and the largest is 2²⁹ - 1, or 536,870,911. You also cannot use the numbers 19000 though 19999 (FieldDescriptor::kFirstReservedNumber through FieldDescriptor::kLastReservedNumber), as they are reserved for the Protocol Buffers implementation - the protocol buffer compiler will complain if you use one of these reserved numbers in your .proto.

如你所见，在消息定义中，每一个字段都有一个独一无二的标识号（unique numbered tag）。这些标识号是用来在消息二进制格式（message binary format）中识别你的字段的。注意：[1,15]之内的标识号在编码的时候会占用一个字节。[16,2047]之内的标识号则占用2个字节。所以你应该为那些频繁出现的消息元素保留[1,15]之内的标识号。切记：要为将来有可能添加的、频繁出现的标识号预留一些标识号。

Specifying Field Rules 指定字段规则

You specify that message fields are one of the following:

· required: a well-formed message must have exactly one of this field.

· optional: a well-formed message can have zero or one of this field (but not more than one).

· repeated: this field can be repeated any number of times (including zero) in a well-formed message. The order of the repeated values will be preserved.

你所指定的消息字段必须是如下之一：

l required：一个格式良好的消息一定要含有1个这种字段。

l optional：一个格式良好的消息可以有0个或1个这种字段（但不超过1个）。

l repeated：在一个格式良好的消息中，这种字段可以重复任意多次（包括0次）。重复的值的顺序会被保留。

（译者注：这一段内容我不太理解，因为Google提供的.proto示例文件似乎并没有按这个说法来编写...）

For historical reasons, repeated fields of basic numeric types aren't encoded as efficiently as they could be. New code should use the special option [packed=true] to get a more efficient encoding. For example:

由于历史原因，基本数值类型的repeated的字段并没有被尽可能地高效编码。在新的代码（译者注：这里是指.proto文件的内容）中，用户应该使用特殊选项[packed=true]来保证更高效的编码。例如：

repeated int32 samples = 4 [packed=true];

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. Some engineers at Google have come to the conclusion that using required does more harm than good; they prefer to use onlyoptional and repeated. However, this view is not universal.

required是永久性的：在把一个字段标识为required的时候，你应该特别小心。如果在某些情况下你不想写入或者发送一个required的字段，那么将该字段更改为optional可能会遇到问题——旧版本的读者（译者注：即读取、解析消息的一方）会认为不含该字段的消息（message）是不完整的，从而有可能会拒绝解析。在这种情况下，你应该考虑编写特别针对于应用程序的、自定义的消息校验函数。Google的一些工程师得出了一个结论：使用required弊多于利；他们更愿意使用optional和repeated而不是required。当然，这个观点并不具有普遍性。

Adding More Message Types 添加更多消息类型

Multiple message types can be defined in a single .proto file. This is useful if you are defining multiple related messages – so, for example, if you wanted to define the reply message format that corresponds to your SearchResponse message type, you could add it to the same .proto:

在一个.proto文件中可以定义多个消息类型。在定义多个相关的消息的时候，这一点特别有用——例如，如果你想定义与你的SearchResponse消息类型对应的回复消息格式的话，你可以将它添加到相同的.proto文件中：

message SearchRequest {

required string query = 1;

optional int32 page_number = 2;

optional int32 result_per_page = 3;

}

message SearchResponse {

...

}

Adding Comments 添加注释

To add comments to your .proto files, use C/C++-style // syntax.

向.proto文件添加注释，可以使用C/C++风格的双斜杠（//） 语法格式。

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.

}

What's Generated From Your .proto? 从你的.proto文件生成了什么？

When you run the protocol buffer compiler on a .proto, the compiler generates the code in your chosen language you'll need to work with the message types you've described in the file, including getting and setting field values, serializing your messages to an output stream, and parsing your messages from an input stream.

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

(本文来自learnhard的优快云博客：http://blog.youkuaiyun.com/learnhard/)

For C++, the compiler generates a .h and .cc file from each .proto, with a class for each message type described in your file.

For Java, the compiler generates a .java file with a class for each message type, as well as a special Builder classes for creating message class instances.

对C++来说，编译器为每一个.proto文件生成了一个.h文件和一个.cc文件，.proto文件中的每一个消息有一个对应的类。

对Java来说，编译器为每一个消息类型生成了一个.java文件，以及一个特殊的Builder类（这个类是用来创建消息类接口的）。

Python is a little different – the Python compiler generates a module with a static descriptor of each message type in your .proto, which is then used with a metaclass to create the necessary Python data access class at runtime.

You can find out more about using the APIs for each language by following the tutorial for your chosen language. For even more API details, see the relevant API reference.

对Python来说，有点不一样——Python编译器为.proto文件中的每个消息类型生成一个模型，其含有一个静态描述符（static descriptor，译者注：没用过Python，不清楚这样翻译正确与否），该模型与一个元类（metaclass）在运行时（runtime）被用来创建必需的Python数据访问类。

你可以从每种语言的教程中找到更多使用使用API的方法。如欲查看更详细的API信息，请阅相关的文章API reference。

Scalar Value Types 标量数值类型

A scalar message field can have one of the following types – the table shows the type specified in the .proto file, and the corresponding type in the automatically generated class:

一个标量消息字段可以含有一个如下的类型——该表格展示了定义于.proto文件中的类型，以及与之对应的、在自动生成的访问类中定义的类型：

.proto Type	Notes	C++ Type	Java Type
double		double	double
float		float	float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. 使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint32。	int32	int
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. 使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint64。	int64	long
uint32	Uses variable-length encoding. 使用可变长编码方式。	uint32	int^[1]
uint64	Uses variable-length encoding. 使用可变长编码方式。	uint64	long^[1]
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. 使用可变长编码方式。有符号的整型值。编码时比通常的int32高效。	int32	int
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. 使用可变长编码方式。有符号的整型值。编码时比通常的int64高效。	int64	long
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2²⁸. 总是4个字节。如果数值总是比总是比2²⁸大的话，这个类型会比uint32高效。	uint32	int^[1]
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2⁵⁶. 总是8个字节。如果数值总是比总是比2⁵⁶大的话，这个类型会比uint64高效。	uint64	long^[1]
sfixed32	Always four bytes. 总是4个字节。	int32	int
sfixed64	Always eight bytes. 总是8个字节。	int64	long
bool		bool	boolean
string	A string must always contain UTF-8 encoded or 7-bit ASCII text. 一个字符串必须是UTF-8编码或者7-bit ASCII编码的文本。	string	String
bytes	May contain any arbitrary sequence of bytes. 可能包含任意顺序的字节数据。	string	ByteString

You can find out more about how these types are encoded when you serialize your message in Protocol Buffer Encoding.

^[1] In Java, unsigned 32-bit and 64-bit integers are represented using their signed counterparts, with the top bit simply being stored in the sign bit.

你可以在文章Protocol Buffer Encoding中，找到更多“序列化消息时各种类型如何编码”的信息。

^[1]在Java中，无符号32位和64位整型以它们对应的有符号类型来表示。

Optional Fields And Default Values Optional的字段和默认值

As mentioned above, elements in a message description can be labeled optional. A well-formed message may or may not contain an optional element. When a message is parsed, if it does not contain an optional element, the corresponding field in the parsed object is set to the default value for that field. The default value can be specified as part of the message description. For example, let's say you want to provide a default value of 10 for a SearchRequest's result_per_page value.

如上所述，消息描述中的一个元素可以被标记为“可选的”（optional）。一个格式良好的消息可以包含一个optional的元素，也可以不包含。当解析一个消息的时候，如果它不包含optional的元素，那么解析出来的对象中的对应字段就被置为默认值。默认值可以在消息描述文件中指定。例如，要为SearchRequest消息的result_per_page字段指定默认值10，可以这样做：

optional int32 result_per_page = 3 [default = 10];

If the default value is not specified for an optional element, a type-specific default value is used instead: for strings, the default value is the empty string. For bools, the default value is false. For numeric types, the default value is zero. For enums, the default value is the first value listed in the enum's type definition.

如果没有为optional的元素指定默认值，那么就会使用与特定类型相关的默认值：对string来说，默认值是空字符串。对bool来说，默认值是false。对数值类型来说，默认值是0。对枚举来说，默认值是枚举类型定义中的第一个值。

(本文来自learnhard的优快云博客：http://blog.youkuaiyun.com/learnhard/)

Enumerations 枚举

When you're defining a message type, you might want one of its fields to only have one of a pre-defined list of values. For example, let's say you want to add a corpus field for each SearchRequest, where the corpus can be UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS or VIDEO. You can do this very simply by adding an enum to your message definition - a field with an enum type can only have one of a specified set of constants as its value (if you try to provide a different value, the parser will treat it like an unknown field). In the following example we've added an enum called Corpuswith all the possible values, and a field of type Corpus:

当你定义一个消息类型的时候，你可能想为一个字段指定某“预定义值序列”（pre-defined list of values）中的一个值。例如，假设你想为每一个SearchRequest消息添加一个corpus字段，而corpus的值可能是UNIVERSAL，WEB，IMAGES，LOCAL，NEWS，PRODUCTS或VIDEO中的一个。你可以很容易地实现这一点：通过向你的消息定义中添加一个枚举（enum）就可以了。一个enum类型的字段只能用指定的常量集（specified set of constants）中的一个值作为其值（如果你尝试指定不同的值，解析器就会把它当作一个未知的字段来对待）。在下面的例子中，我们已经添加了一个叫做Corpus的枚举（enum）——它含有所有可能的值——以及一个类型为Corpus的字段：