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 語言構(gòu)造 Protocol buffer 數(shù)據(jù)，包括 .proto 文件語法以及如何從 .proto 文件生成數(shù)據(jù)訪問類。它涵蓋了 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).
該參考指南是使用循序漸進(jìn)的例子來描述 protocal buffer 的特性，請參看[教程]你選擇的語言（目前只有 proto2；更多 proto3 文文檔稍后推出）。

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.

首先讓我們看一個非常簡單的例子。假設(shè)您想要定義一個搜索請求消息格式，其中每個搜索請求包含查詢字符串、您期待的特定頁數(shù)據(jù)和期望每頁數(shù)據(jù)調(diào)條數(shù)。以下是用于定義該消息類型的 .proto 文件。

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 編譯器會假設(shè)您使用的是 [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 消息定義指定的三個字段, 每一個你想要包含在消息中的數(shù)據(jù)數(shù)據(jù)都以(名稱/值 對)形式存在。每個字段都有名稱和類型。

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.

在上面的例子中，所有的字段都是數(shù)值類型：兩個整數(shù)（page_number 和 result_per_page）和一個字符串（query）類型。然而，你也可以指定復(fù)合類型，包括枚舉和其他消息類型。

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.

正如您所看到的，消息定義中的每個字段都有唯一的編號標(biāo)記。這些標(biāo)記用于標(biāo)識消息二進(jìn)制格式中的字段，并且在您的消息類型使用后不應(yīng)更改該字段。請注意，標(biāo)簽取值范圍在1到15之間，需要一個字節(jié)來編碼，包括標(biāo)識號和字段類型（您可以在 [Protocol Buffer Encoding] 中找到更多信息）。標(biāo)簽取值范圍在16到2047內(nèi)，需要兩個字節(jié)。因此，您應(yīng)該保留標(biāo)簽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.

您可以指定的最小標(biāo)簽數(shù)是1，最大的是2^29 - 1，或 536870911。你也不能用數(shù)字19000到19999（FieldDescriptor::KFirstReservedNumber 到FieldDescriptor:: KLastReservedNumber），這是 protocol buffer 預(yù)留的 - 當(dāng)你在 .proto 文件中使用保留編號 protocol buffer 編譯器將報警。同樣，您不能使用任何保留的標(biāo)簽。