【Google Protocol Buffer】Language Guide中文翻译

╰半夏微凉° 2022-09-30 06:17 201阅读 0赞

# **Language Guide** **语言指南** #

注：这是本人的翻译，可能不准确，可能有错误，但是基本上可以理解，希望能对大家有所帮助！（转载请注明出处：本文来自learnhard的博客：[http://www.codelast.com/][http_www.codelast.com]& [http://blog.csdn.net/learnhard/][http_blog.csdn.net_learnhard]）

·[Defining A Message Type][]

·[Scalar Value Types][]

·[Optional And Default Values][]

·[Enumerations][]

·[Using Other Message Types][]

·[Nested Types][]

·[Updating A Message Type][]

·[Extensions][]

·[Packages][]

·[Defining Services][]

·[Options][]

·[Generating Your Classes][]

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****）。**

（转载请注明出处：本文来自learnhard的博客：[http://www.codelast.com/][http_www.codelast.com]& [http://blog.csdn.net/learnhard/][http_blog.csdn.net_learnhard]）

**Specifying Field Types** **指定字段类型**

In the above example, all the fields are [scalar types][Scalar Value Types]: two integers (page\_number and result\_per\_page) and a string (query). However, you can also specify composite types for your fields, including [enumerations][Enumerations] and other message types.

**在上面的例子中，所有字段都是标量类型（**[scalar types][Scalar Value Types]**）****:****两个整型（**page\_number**和**result\_per\_page**），一个****string****（**query**）。然而，你也可以为字段指定合成的类型，包括枚举（**[enumerations][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 229 \- 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****。当然，这个观点并不具有普遍性。**

**（转载请注明出处：本文来自learnhard的博客：[http://www.codelast.com/][http_www.codelast.com]& [http://blog.csdn.net/learnhard/][http_blog.csdn.net_learnhard]）**

**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][Generating Your Classes] 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][Generating Your Classes]**）的时候，编译器生成你所选择的语言的代码，这些代码可以操作你在****.proto****文件中定义的消息类型，包括获取、设置字段值，将你的消息序列化到一个输出流中，以及从一个输入流中解析你的消息。**

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****文件中的类型，以及与之对应的、在自动生成的访问类中定义的类型：**

<table style="width: 97%; border-collapse: collapse; margin-left: 9pt; mso-yfti-tbllook: 1184;"> 
 <tbody> 
 <tr style="mso-yfti-irow: 0; mso-yfti-firstrow: yes;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; background: #e5ecf9; padding-top: 4.5pt; border: #bbbbbb 1pt solid;"> .proto Type </td> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-left-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> Notes </td> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-left-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> C++ Type </td> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-left-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> Java Type </td> 
 </tr> 
 <tr style="mso-yfti-irow: 1;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> double </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;">&nbsp;</td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> double </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> double </td> 
 </tr> 
 <tr style="mso-yfti-irow: 2;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> float </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;">&nbsp;</td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> float </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> float </td> 
 </tr> 
 <tr style="mso-yfti-irow: 3;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> int32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. 使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint32。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int </td> 
 </tr> 
 <tr style="mso-yfti-irow: 4;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> int64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. 使用可变长编码方式。编码负数时不够高效——如果你的字段可能含有负数，那么请使用sint64。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> long </td> 
 </tr> 
 <tr style="mso-yfti-irow: 5;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> uint32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Uses variable-length encoding. 使用可变长编码方式。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> uint32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int[1] </td> 
 </tr> 
 <tr style="mso-yfti-irow: 6;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> uint64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Uses variable-length encoding. 使用可变长编码方式。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> uint64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> long[1] </td> 
 </tr> 
 <tr style="mso-yfti-irow: 7;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> sint32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. 使用可变长编码方式。有符号的整型值。编码时比通常的int32高效。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int </td> 
 </tr> 
 <tr style="mso-yfti-irow: 8;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> sint64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. 使用可变长编码方式。有符号的整型值。编码时比通常的int64高效。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> long </td> 
 </tr> 
 <tr style="mso-yfti-irow: 9;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> fixed32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Always four bytes. More efficient than uint32 if values are often greater than 228. 总是4个字节。如果数值总是比总是比228大的话，这个类型会比uint32高效。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> uint32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int[1] </td> 
 </tr> 
 <tr style="mso-yfti-irow: 10;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> fixed64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Always eight bytes. More efficient than uint64 if values are often greater than 256. 总是8个字节。如果数值总是比总是比256大的话，这个类型会比uint64高效。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> uint64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> long[1] </td> 
 </tr> 
 <tr style="mso-yfti-irow: 11;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> sfixed32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Always four bytes. 总是4个字节。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int32 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int </td> 
 </tr> 
 <tr style="mso-yfti-irow: 12;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> sfixed64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> Always eight bytes. 总是8个字节。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> int64 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> long </td> 
 </tr> 
 <tr style="mso-yfti-irow: 13;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> bool </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;">&nbsp;</td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> bool </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> boolean </td> 
 </tr> 
 <tr style="mso-yfti-irow: 14;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> string </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> A string must always contain UTF-8 encoded or 7-bit ASCII text. 一个字符串必须是UTF-8编码或者7-bit ASCII编码的文本。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> string </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> String </td> 
 </tr> 
 <tr style="mso-yfti-irow: 15; mso-yfti-lastrow: yes;"> 
 <td style="padding-bottom: 4.5pt; padding-left: 9pt; width: 8.48%; padding-right: 9pt; padding-top: 4.5pt; mso-border-alt: solid #BBBBBB .75pt; mso-border-top-alt: solid #BBBBBB .75pt; border: #bbbbbb 1pt solid;"> bytes </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 70.08%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> May contain any arbitrary sequence of bytes. 可能包含任意顺序的字节数据。 </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 10.2%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> string </td> 
 <td style="border-bottom: #bbbbbb 1pt solid; padding-bottom: 4.5pt; padding-left: 9pt; width: 11.22%; padding-right: 9pt; background: white; border-top: medium none; border-right: #bbbbbb 1pt solid; padding-top: 4.5pt; mso-border-left-alt: solid #BBBBBB .75pt;"> ByteString </td> 
 </tr> 
 </tbody> 
</table>

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

\[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][message binary format]**中，找到更多“序列化消息时各种类型如何编码”的信息。**

\[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://www.codelast.com/][http_www.codelast.com]& [http://blog.csdn.net/learnhard/][http_blog.csdn.net_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**的字段：**

message SearchRequest \{

required string query = 1;

optional int32 page\_number = 2;

optional int32 result\_per\_page = 3 \[default = 10\];

enum Corpus \{

UNIVERSAL = 0;

WEB = 1;

IMAGES = 2;

LOCAL = 3;

NEWS = 4;

PRODUCTS = 5;

VIDEO = 6;

optional Corpus corpus = 4 \[default = UNIVERSAL\];

Enumerator constants must be in the range of a 32-bit integer. Since enum values use varint encoding on the wire, negative values are inefficient and thus not recommended. You can define enums within a message definition, as in the above example, or outside – these enums can be reused in any message definition in your .proto file. You can also use an enum type declared in one message as the type of a field in a different message, using the syntax *MessageType*.*EnumType*.

When you run the protocol buffer compiler on a .proto that uses an enum, the generated code will have a corresponding enum for Java or C++, or a special EnumDescriptor class for Python that's used to create a set of symbolic constants with integer values in the runtime-generated class.

For more information about how to work with message enums in your applications, see the [generated code guide][API reference] for your chosen language.

**枚举常量必须在****32****位整型值的范围内。因为**enum**值是使用可变编码方式的，对负数不够高效，因此不推荐在****enum****中使用负数。如上例所示，你可以在一个消息定义的内部或外部定义枚举——这些枚举可以在你的****.proto****文件中的任何消息定义里重用。你也可以在一个消息中声明一个枚举类型，而在另一个不同的消息中使用它——采用***MessageType*.*EnumType***的语法格式。**

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

**关于如何在你的应用程序的消息中使用枚举的更多信息，请查看你所选择的语言的**[generated code guide][API reference]**。**

**Using Other Message Types** **使用其他消息类型**

You can use other message types as field types. For example, let's say you wanted to include Result messages in each SearchResponsemessage – to do this, you can define a Result message type in the same .proto and then specify a field of type Result in SearchResponse:

**你可以将其他消息类型用作字段类型。例如，假设你想在每一个**SearchResponse**消息中包含**Result**消息，你可以这样做——在相同的****.proto****文件中定义一个**Result**消息类型，然后在**SearchResponse**消息中指定一个**Result**类型的字段：**

message SearchResponse \{

repeated Result result = 1;

message Result \{

required string url = 1;

optional string title = 2;

repeated string snippets = 3;

**Importing Definitions** **导入定义**

In the above example, the Result message type is defined in the same file as SearchResponse – what if the message type you want to use as a field type is already defined in another .proto file?

**在上面的例子中，**Result**消息类型与**SearchResponse**是定义在同一文件中的——如果你要使用的消息类型已经在其他****.proto****文件中已经定义过了呢？**

You can use definitions from other .proto files by *importing* them. To import another .proto's definitions, you add an import statement to the top of your file:

**你可以通过导入（***importing***）其他****.proto****文件中的定义来使用它们。要导入其他****.proto****文件的定义，你需要在你的文件中添加一个导入声明：**

import "myproject/other\_protos.proto";

The protocol compiler searches for imported files in a set of directories specified on the protocol compiler command line using the \-I/–import\_path flag. If no flag was given, it looks in the directory in which the compiler was invoked.

**然后，****protocol****编译器就会在一系列目录中查找需要被导入的文件，这些目录通过****protocol****编译器的命令行参数**\-I/–import\_path**指定。如果不提供参数，编译器就在其调用目录下查找。**

**（转载请注明出处：本文来自learnhard的博客：[http://www.codelast.com/][http_www.codelast.com]& [http://blog.csdn.net/learnhard/][http_blog.csdn.net_learnhard]）**

**Nested Types** **嵌套类型**

You can define and use message types inside other message types, as in the following example – here the Result message is defined inside the SearchResponse message:

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

message SearchResponse \{

message Result \{

required string url = 1;

optional string title = 2;

repeated string snippets = 3;

repeated Result result = 1;

If you want to reuse this message type outside its parent message type, you refer to it as *Parent*.*Type*:

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

message SomeOtherMessage \{

optional SearchResponse.Result result = 1;

You can nest messages as deeply as you like:

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

message Outer \{ // Level 0

message MiddleAA \{ // Level 1

message Inner \{ // Level 2

required int64 ival = 1;

optional boolbooly = 2;

message MiddleBB \{ // Level 1

message Inner \{ // Level 2

required int32 ival = 1;

optional boolbooly = 2;

**Groups** **组**

**Note that this feature is deprecated and should not be used when creating new message types – use nested message types instead.**

**注意：这个特性已经被弃用了，在创建新的消息类型的时候，不应该再使用它——你应该使用嵌套消息类型来代替它。**

Groups are another way to nest information in your message definitions. For example, another way to specify a SearchResponse containing a number of Results is as follows:

**“组”是在你的消息定义中嵌套信息的另一种方法。例如，在**SearchResponse**中包含若干**Result**的另一种方法是****：**

message SearchResponse \{

repeated group Result = 1 \{

required string url = 2;

optional string title = 3;

repeated string snippets = 4;

A group simply combines a nested message type and a field into a single declaration. In your code, you can treat this message just as if it had aResult type field called result (the latter name is converted to lower-case so that it does not conflict with the former). Therefore, this example is exactly equivalent to the SearchResponse above, except that the message has a different [wire format][].

**一个“组”只是简单地将一个嵌套消息类型和一个字段捆绑到一个单独的声明中。在你的代码中，你可以把它看成是含有一个**Result**类型、名叫**result**的字段的消息（后面的名字被转换成了小写，所以它不会与前面的冲突）。**

**因此，除了数据传输格式（**[wire format][]**）不同之外，这个例子与上面的**SearchResponse**例子是完全等价的。**

**Updating A Message Type** **更新一个消息类型**

If an existing message type no longer meets all your needs – for example, you'd like the message format to have an extra field – but you'd still like to use code created with the old format, don't worry! It's very simple to update message types without breaking any of your existing code. Just remember the following rules:

**如果一个已有的消息无法再满足你的需求——例如，你想在消息中添加一个额外的字段——但是你同时还想让为旧版本写的代码仍然可用，不用怕！更新消息而不破坏已有代码是非常简单的。只要你记住下面的规则：**

·Don't change the numeric tags for any existing fields.

·Any new fields that you add should be optional or repeated. This means that any messages serialized by code using your "old" message format can be parsed by your new generated code, as they won't be missing any required elements. You should set up sensible [default values][Optional And Default Values] for these elements so that new code can properly interact with messages generated by old code. Similarly, messages created by your new code can be parsed by your old code: old binaries simply ignore the new field when parsing. However, the unknown fields are not discarded, and if the message is later serialized, the unknown fields are serialized along with it – so if the message is passed on to new code, the new fields are still available. Note that preservation of unknown fields is currently not available for Python.

·Non-required fields can be removed, as long as the tag number is not used again in your updated message type (it may be better to rename the field instead, perhaps adding the prefix "OBSOLETE\_", so that future users of your .proto can't accidentally reuse the number).

·A non-required field can be converted to an [extension][Extensions] and vice versa, as long as the type and number stay the same.

·int32, uint32, int64, uint64, and bool are all compatible – this means you can change a field from one of these types to another without breaking forwards- or backwards-compatibility. If a number is parsed from the wire which doesn't fit in the corresponding type, you will get the same effect as if you had cast the number to that type in C++ (e.g. if a 64-bit number is read as an int32, it will be truncated to 32 bits).

·sint32 and sint64 are compatible with each other but are *not* compatible with the other integer types.

·string and bytes are compatible as long as the bytes are valid UTF-8.

·Embedded messages are compatible with bytes if the bytes contain an encoded version of the message.

·fixed32 is compatible with sfixed32, and fixed64 with sfixed64.

l**不要更改任何已有的字段的数值标识（****tag****）。**

l**你添加的任何字段都必须是****optional****或****repeated****的。这就意味着任何使用你的“旧”消息格式的代码序列化的消息可以被你的新代码所解析，因为它们不会丢掉任何****required****的元素。你应该为这些元素设置合理的默认值（**[default values][Optional And Default Values]**），这样新的代码就能够正确地与老代码生成的消息交互了。类似地，你的新代码创建的消息也能被你的老代码解析：老的二进制程序在解析的时候只是简单地将新字段忽略。然而，未知的字段是没有被抛弃的，此后，如果消息被序列化，未知的字段会随之一起被序列化——所以，如果消息传到了新代码那里，则新的字段仍然可用。注意：对****Python****来说，对未知字段的保留策略是无效的。**

l**非****required****的字段可以移除——只要它们的标识号（****tag number****）在你的新消息类型中不再使用（更好的做法可能是重命名那个字段，例如在字段前添加“****OBSOLETE\_****”前缀，那样的话，你的****.proto****文件的用户将来就不会无意中重新使用了那些不该使用的标识号）。**

l**一个非****required****的字段可以转换为一个扩展（**[extension][Extensions]**），反之亦然——只要它的类型和标识号保持不变。**

lint32, uint32, int64, uint64,**和**bool**是全部兼容的，这意味着你可以将这些类型中的一个转换为另外一个，而不会破坏前向、后向的兼容性。如果解析出来的数字与对应的类型不相符，那么结果就像在****C++****中对它进行了强制类型转换一样（例如，如果把一个****64****位数字当作****int32****来读取，那么它就会被截断为****32****位的数字）。**

lsint32**和**sint64**是互相兼容的，但是它们与其他整数类型****不兼容****。**

lstring**和**bytes**是兼容的——只要**bytes**是有效的****UTF-8****编码。**

l**嵌套消息与**bytes**是兼容的——只要****bytes****包含该消息的一个编码过的版本。**

lfixed32**与**sfixed32**是兼容的，**fixed64**与**sfixed64**是兼容的。**

**Extensions** **扩展**

Extensions let you declare that a range of field numbers in a message are available for third-party extensions. Other people can then declare new fields for your message type with those numeric tags in their own .proto files without having to edit the original file. Let's look at an example:

**通过扩展，你可以将一个范围内的字段标识号声明为可被第三方扩展所用。然后，其他人就可以在他们自己的****.proto****文件中为你的消息类型声明新的字段，而不必去编辑原始文件了。让我们看个例子：**

message Foo \{

// …

extensions 100 to 199;

This says that the range of field numbers \[100, 199\] in Foo is reserved for extensions. Other users can now add new fields to Foo in their own.proto files that import your .proto, using tags within your specified range – for example:

**这个例子表明：在消息**Foo**中，范围****\[100,199\]****之内的字段标识号被保留为扩展用。现在，其他人就可以在他们自己的****.proto****文件中添加新字段到**Foo**里了，但是添加的字段标识号要在指定的范围内——例如：**

extend Foo \{

optional int32 bar = 126;

This says that Foo now has an optional int32 field called bar.

When your user's Foo messages are encoded, the wire format is exactly the same as if the user defined the new field inside Foo. However, the way you access extension fields in your application code is slightly different to accessing regular fields – your generated data access code has special accessors for working with extensions. So, for example, here's how you set the value of bar in C++:

**这个例子表明：消息**Foo**现在有一个名为**bar**的****optional** int32**字段。**

**当用户的**Foo**消息被编码的时候，数据的传输格式与用户在**Foo**里定义新字段的效果是完全一样的。**

**然而，你在程序代码中访问扩展字段的方法与访问普通的字段稍有不同——你生成的数据访问代码为扩展准备了特殊的访问函数来访问它。例如，下面是你如何在****C++****中设置**bar**的值：**

Foo foo;  
foo.SetExtension(bar,15);

Similarly, the Foo class defines templated accessors HasExtension(), ClearExtension(), GetExtension(), MutableExtension(), andAddExtension(). All have semantics matching the corresponding generated accessors for a normal field. For more information about working with extensions, see the generated code reference for your chosen language.

Note that extensions can be of any field type, including message types.

**类似地，****Foo****类也定义了模板函数**HasExtension()**，**ClearExtension()**，**GetExtension()**，**MutableExtension()**，以及**AddExtension()**。这些函数的语义都与对应的普通字段的访问函数相符。要查看更多使用扩展的信息，请参考相应语言的代码生成指南。**

**注意：扩展可以是任何字段类型，包括消息类型。**

（转载请注明出处：本文来自learnhard的博客：[http://www.codelast.com/][http_www.codelast.com] & [http://blog.csdn.net/learnhard/][http_blog.csdn.net_learnhard]）

文章来源：http://www.codelast.com/

**Nested Extensions** **嵌套的扩展**

You can declare extensions in the scope of another type:

**你可以在另一个类型的范围内声明扩展：**

message Baz \{

extend Foo \{

optional int32 bar = 126;

…

In this case, the C++ code to access this extension is:

**在此例中，访问此扩展的****C++****代码是：**

Foo foo;

foo.SetExtension(Baz::bar, 15);

In other words, the only effect is that bar is defined within the scope of Baz.

**换句话说，唯一的效果就是****bar****被定义在****Baz****的范围内。**

This is a common source of confusion: Declaring an extend block nested inside a message type ***does not*** imply any relationship between the outer type and the extended type. In particular, the above example ***does not*** mean that Baz is any sort of subclass of Foo. All it means is that the symbol bar is declared inside the scope of Baz; it's simply a static member.

**这是个引起混淆的来源：在一个消息类型中嵌套声明一个**extend**块并****没有****暗示外部类型（**outer type**）与扩展类型（**extended type**）之间有任何联系。特别地，上面的例子****没有****表明**Baz**是**Foo**的任何类型的子类。它所表明的仅仅是：符号**bar**是在**Baz**的内部声明的；它只是一个静态成员罢了。**

A common pattern is to define extensions inside the scope of the extension's field type – for example, here's an extension to Foo of type Baz, where the extension is defined as part of Baz:

**一个通常的设计模式就是：在扩展的字段类型的范围内定义该扩展——例如，下面是一个**Foo**的扩展（该扩展是**Baz**类型的），其中，扩展被定义为了**Baz**的一部分：**

**（译者注：这样的定义形式确很容易引起混淆，请继续往下看，以帮助你消除这种混淆）**

message Baz \{

extend Foo \{

optional Baz foo\_ext = 127;

…

However, there is no requirement that an extension with a message type be defined inside that type. You can also do this:

**然而，并没有强制要求一个消息类型的扩展一定要定义在那个消息中。你也可以这样做：**

message Baz \{

…

// This can even be in a different file.

extend Foo \{

optional Baz foo\_baz\_ext = 127;

In fact, this syntax may be preferred to avoid confusion. As mentioned above, the nested syntax is often mistaken for subclassing by users who are not already familiar with extensions.

**事实上，这种语法格式更能防止引起混淆。正如上面所提到的，嵌套的语法通常被错误地认为有子类化的关系——尤其是对那些还不熟悉扩展的用户来说。**

（转载请注明出处：本文来自learnhard的博客：[http://www.codelast.com/][http_www.codelast.com]& [http://blog.csdn.net/learnhard/][http_blog.csdn.net_learnhard]）

[http_www.codelast.com]: http://www.codelast.com/
[http_blog.csdn.net_learnhard]: http://blog.csdn.net/learnhard/
[Defining A Message Type]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#simple
[Scalar Value Types]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#scalar
[Optional And Default Values]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#optional
[Enumerations]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#enum
[Using Other Message Types]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#other
[Nested Types]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#nested
[Updating A Message Type]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#updating
[Extensions]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#extensions
[Packages]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#packages
[Defining Services]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#services
[Options]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#options
[Generating Your Classes]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/proto.html#generating
[tutorial]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/tutorials.html
[message binary format]: http://code.google.com/apis/protocolbuffers/docs/encoding.html
[API reference]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/reference/overview.html
[wire format]: http://code.google.com/intl/zh-CN/apis/protocolbuffers/docs/encoding.html