语法指南 (proto3)
Defining A Message Type
Scalar Value Types
Default Values
Enumerations
Using Other Message Types
Nested Types
Updating A Message Type
Unknown Fields
Any
Oneof
Maps
Packages
Defining Services
JSON Mapping
Options
Generating Your Classes
本指南介绍了如何使用协议缓冲区语言来构造协议缓冲区数据（包括.proto文件语法）以及如何从.proto文件生成数据访问类。 它涵盖了协议缓冲区语言的proto3版本：有关proto2语法的信息，请参见《Proto2语言指南》。
这是参考指南–有关使用本文档中描述的许多功能的分步示例，请参见所选择语言的教程（当前仅适用于proto2；即将推出更多proto3文档）。
首先，让我们看一个非常简单的示例。 假设您要定义一个搜索请求消息格式，其中每个搜索请求都有一个查询字符串，您感兴趣的特定结果页面以及每页结果数量。 这是用于定义消息类型的.proto文件。
syntax = "proto3"; message SearchRequest { string query = 1; int32 page_number = 2; int32 result_per_page = 3; }文件的第一行指定您使用的是proto3语法：如果不这样做，则协议缓冲区编译器将假定您使用的是proto2。 这必须是文件的第一行非空，非注释行。
SearchRequest消息定义指定三个字段（名称/值对），每个字段要包含在此类型的消息中，每个字段对应一个。 每个字段都有一个名称和类型。
Specifying Field Types在上面的示例中，所有字段均为标量类型：两个整数（page_number和result_per_page）和一个字符串（查询）。 但是，您也可以为字段指定复合类型，包括枚举和其他消息类型。
Assigning Field Numbers如您所见，消息定义中的每个字段都有一个唯一的编号。这些字段号用于标识消息二进制格式的字段，一旦使用了消息类型，就不应更改这些字段号。请注意，范围为1到15的字段编号需要一个字节来编码，包括字段编号和字段的类型（您可以在协议缓冲区编码中找到更多有关此内容的信息）。 16到2047之间的字段号占用两个字节。因此，您应该为经常出现的消息元素保留数字1到15。切记为将来可能添加的频繁出现的元素留出一些空间。
您可以指定的最小字段号是1，最大字段号是229-1或536,870,911。您也不能使用数字19000到19999（FieldDescriptor :: kFirstReservedNumber到FieldDescriptor :: kLastReservedNumber），因为它们是为协议缓冲区实现保留的-如果在.proto中使用这些保留数之一，协议缓冲区编译器会抱怨。同样，您不能使用任何以前保留的字段号。
Specifying Field Rules消息字段可以是以下内容之一：
单数：格式正确的邮件可以包含零个或一个此字段（但不能超过一个）。 这是proto3语法的默认字段规则。
重复：此字段可以在格式正确的消息中重复任意次（包括零次）。 重复值的顺序将保留。
在proto3中，标量数字类型的重复字段默认情况下使用打包编码。
您可以在协议缓冲区编码中找到有关打包编码的更多信息。
可以在单个.proto文件中定义多种消息类型。 如果要定义多个相关消息，这很有用–例如，如果要定义与SearchResponse消息类型相对应的答复消息格式，可以将其添加到相同的.proto中：
message SearchRequest { string query = 1; int32 page_number = 2; int32 result_per_page = 3; } message SearchResponse { ... } Adding Comments要将注释添加到.proto文件，请使用C / C ++样式//和/ * ... * /语法。
/* 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. } Reserved Fields如果您通过完全删除字段或将其注释掉来更新消息类型，则将来的用户在自己对该类型进行更新时可以重用该字段号。 如果他们以后加载同一.proto的旧版本，可能会导致严重的问题，包括数据损坏，隐私错误等。 确保不会发生这种情况的一种方法是指定保留已删除字段的字段编号（和/或名称，这也可能导致JSON序列化问题）。 如果将来有任何用户尝试使用这些字段标识符，则协议缓冲区编译器会抱怨。
message Foo { reserved 2, 15, 9 to 11; reserved "foo", "bar"; }请注意，您不能在同一保留语句中混用字段名称和字段编号。
What's Generated From Your .proto?在.proto上运行协议缓冲区编译器时，编译器会以您选择的语言生成代码，您将需要使用该文件处理文件中描述的消息类型，包括获取和设置字段值，将消息序列化为输出流，并从输入流中解析消息。
对于C ++，编译器从每个.proto生成.h和.cc文件，并为文件中描述的每种消息类型提供一个类。
对于Java，编译器会生成一个.java文件，其中包含每种消息类型的类以及用于创建消息类实例的特殊Builder类。