Language Guide (proto3 语言指南)

proto3# Language Guide (proto3 语言指南) (未完)

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 proto3 version of the protocol buffers language: for information on the older proto2 syntax, see the Proto2 Language Guide.

本指南介绍如何使用 Protocol buffer 语言构造 Protocol buffer 数据，包括 .proto 文件语法以及如何从 .proto 文件生成数据访问类。它涵盖了 protocol buffers 语言 proto3 版本：对老版 proto2 语法信息，请参看 [proto2 语言指南]。

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 (currently proto2 only; more proto3 documentation is coming soon).
该参考指南是使用循序渐进的例子来描述 protocal buffer 的特性，请参看[教程]你选择的语言（目前只有 proto2；更多 proto3 文文档稍后推出）。

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.

首先让我们看一个非常简单的例子。假设您想要定义一个搜索请求消息格式，其中每个搜索请求包含查询字符串、您期待的特定页数据和期望每页数据调条数。以下是用于定义该消息类型的 .proto 文件。

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

The first line of the file specifies that you’re using proto3 syntax: if you don’t do this the protocol buffer compiler will assume you are using proto2. This must be the first non-empty, non-comment line of the file.

该文件的第一行指定你用 proto3 语法：如果你不这样做的 protocol buffer 编译器会假设您使用的是 [proto2]。文件第一行必须非空的，非注释的。

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 消息定义指定的三个字段, 每一个你想要包含在消息中的数据数据都以(名称/值 对)形式存在。每个字段都有名称和类型。

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). However, you can also specify composite types for your fields, including enumerations and other message types.

在上面的例子中，所有的字段都是数值类型：两个整数（page_number 和 result_per_page）和一个字符串（query）类型。然而，你也可以指定复合类型，包括枚举和其他消息类型。

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, including the identifying number and the field’s type (you can find out more about this in Protocol Buffer Encoding). 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.

正如您所看到的，消息定义中的每个字段都有唯一的编号标记。这些标记用于标识消息二进制格式中的字段，并且在您的消息类型使用后不应更改该字段。请注意，标签取值范围在1到15之间，需要一个字节来编码，包括标识号和字段类型（您可以在 [Protocol Buffer Encoding] 中找到更多信息）。标签取值范围在16到2047内，需要两个字节。因此，您应该保留标签1到15为非常频繁使用的消息元素。记住留一些空间，频繁使用的元素，可能会在未来增加。

The smallest tag number you can specify is 1, and the largest is 2^29 - 1, or 536,870,911. You also cannot use the numbers 19000 through 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. Similarly, you cannot use any previously reserved tags.

您可以指定的最小标签数是1，最大的是2^29 - 1，或 536870911。你也不能用数字19000到19999（FieldDescriptor::KFirstReservedNumber 到FieldDescriptor:: KLastReservedNumber），这是 protocol buffer 预留的 - 当你在 .proto 文件中使用保留编号 protocol buffer 编译器将报警。同样，您不能使用任何保留的标签。