本指南介绍如何使用协议缓冲区语言来构建协议缓冲区数据，包括.proto文件语法以及如何从.proto文件生成数据访问类。它涵盖了协议缓冲区语言的proto3版本：有关proto2语法的信息，请参阅Proto2 语言指南。

这是一个参考指南——有关使用本文档中描述的许多功能的分步示例，请参阅您选择的语言的教程（当前仅 proto2；更多 proto3 文档即将推出）。

官方地址传送门：Proto3语言指南

首先让我们看一个非常简单的例子。假设您要定义一个搜索请求消息格式，其中每个搜索请求都有一个查询字符串、您感兴趣的特定结果页面以及每页的多个结果。这是.proto您用来定义消息类型的文件。

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

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

您可以指定的最小字段编号是 1，最大的是 536,870,911。您也不能使用数字 19000 到 19999 ( FieldDescriptor::kFirstReservedNumberthrough FieldDescriptor::kLastReservedNumber)，因为它们是为 Protocol Buffers 实现保留的——如果您在.proto. 同样，您不能使用任何以前保留的字段编号。

消息字段可以是以下之一：

在 proto3 中，repeated标量数值类型的字段packed默认使用编码。

您可以在Protocol Buffer Encoding中找到有关packed编码的更多信息。

可以在单个.proto文件中定义多种消息类型。如果您要定义多个相关消息，这很有用——例如，如果您想定义与您的SearchResponse消息类型相对应的回复消息格式，您可以将其添加到相同的.proto:

要向.proto文件添加注释，请使用 C/C++ 样式//和/* ... */语法。

如果您通过完全删除某个字段或将其注释掉来更新消息类型，未来的用户可以在对类型进行自己的更新时重用该字段编号。如果他们稍后加载相同的旧版本，这可能会导致严重问题.proto，包括数据损坏、隐私错误等。确保不会发生这种情况的一种方法是指定已删除字段的字段编号（和/或名称，这也可能导致 JSON 序列化问题）为reserved. 如果将来有任何用户尝试使用这些字段标识符，protocol buffer 编译器会抱怨。

请注意，您不能在同一reserved语句中混合字段名称和字段编号。

当您在 a 上运行协议缓冲区编译器.proto时，编译器会以您选择的语言生成代码，您需要使用文件中描述的消息类型，包括获取和设置字段值，将消息序列化到输出流，并从输入流中解析您的消息。

您可以按照所选语言的教程（即将推出 proto3 版本）了解有关使用每种语言的 API 的更多信息。有关更多 API 详细信息，请参阅相关API 参考（proto3 版本也即将推出）。

标量消息字段可以具有以下类型之一 - 该表显示.proto文件中指定的类型，以及自动生成的类中的相应类型：

当您在Protocol Buffer Encoding中序列化您的消息时，您可以了解有关这些类型如何编码的更多信息。

[1] Kotlin 使用 Java 中的相应类型，甚至是无符号类型，以确保在混合 Java/Kotlin 代码库中的兼容性。

[2]在 Java 中，无符号 32 位和 64 位整数使用它们的有符号对应物表示，最高位简单地存储在符号位中。

[3]在所有情况下，为字段设置值将执行类型检查以确保其有效。

[4] 64 位或无符号 32 位整数在解码时始终表示为 long，但如果在设置字段时给出 int，则可以是 int。在所有情况下，该值必须适合设置时表示的类型。见[2]。

[5] Python 字符串在解码时表示为 unicode，但如果给出 ASCII 字符串，则可以是 str（这可能会发生变化）。

[6]整数用于 64 位机器，字符串用于 32 位机器。

解析消息时，如果编码的消息不包含特定的奇异元素，则解析对象中的相应字段将设置为该字段的默认值。这些默认值是特定于类型的：

重复字段的默认值为空（通常是相应语言的空列表）。

请注意，对于标量消息字段，一旦解析了消息，就无法判断该字段是显式设置为默认值（例如布尔值是否设置为false）还是根本没有设置：您应该牢记这一点定义消息类型时。例如，false如果您不希望在默认情况下也发生该行为，则不要在设置为时打开某些行为的布尔值。另请注意，如果标量消息字段设置为其默认值，则该值将不会在线上序列化。

有关默认值如何在生成的代码中工作的更多详细信息，请参阅您选择的语言的生成代码指南。

在定义消息类型时，您可能希望其字段之一仅具有预定义的值列表之一。例如，假设您要corpus为每个 添加一个字段，SearchRequest其中语料库可以是UNIVERSAL、WEB、IMAGES、LOCAL、NEWS或。您可以通过在消息定义中添加一个非常简单的方法来做到这一点，并为每个可能的值添加一个常量。PRODUCTSVIDEOenum

在下面的示例中，我们添加了一个包含所有可能值的enum调用Corpus，以及一个 type 字段Corpus：

如您所见，Corpus枚举的第一个常量映射到零：每个枚举定义都必须包含一个映射到零的常量作为其第一个元素。这是因为：

您可以通过将相同的值分配给不同的枚举常量来定义别名。为此，您需要将allow_alias选项设置为true，否则协议编译器将在找到别名时生成错误消息。

枚举器常量必须在 32 位整数范围内。由于enum值在线路上使用varint 编码，因此负值效率低下，因此不推荐使用。您可以enum在消息定义中定义 s，如上例所示，也可以在外部定义 - 这些enums 可以在.proto文件中的任何消息定义中重用。您还可以使用enum在一条消息中声明的类型作为另一条消息中字段的类型，使用语法_MessageType_._EnumType_.

当您在.proto使用 的a 上运行协议缓冲区编译器时enum，生成的代码将有一个对应enum于 Java、Kotlin 或 C++ 的代码，或者一个EnumDescriptor用于 Python 的特殊类，用于在运行时创建一组具有整数值的符号常量——生成的类。

**警告：** 生成的代码可能会受到特定于语言的枚举数限制（一种语言的低千）。请查看您计划使用的语言的限制。

在反序列化期间，无法识别的枚举值将保留在消息中，尽管在反序列化消息时如何表示这取决于语言。在支持具有超出指定符号范围的值的开放枚举类型的语言中，例如 C++ 和 Go，未知的枚举值简单地存储为其底层整数表示。在 Java 等具有封闭枚举类型的语言中，枚举中的 case 用于表示无法识别的值，并且可以使用特殊的访问器访问底层整数。在任何一种情况下，如果消息被序列化，则无法识别的值仍将与消息一起序列化。

有关如何enum在应用程序中使用 message 的更多信息，请参阅所选语言的生成代码指南。

如果您通过完全删除枚举条目或将其注释掉来更新枚举类型，将来的用户可以在对类型进行自己的更新时重用该数值。如果他们稍后加载相同的旧版本，这可能会导致严重问题.proto，包括数据损坏、隐私错误等。确保不会发生这种情况的一种方法是指定已删除条目的数值（和/或名称，这也可能导致 JSON 序列化问题）为reserved. 如果将来有任何用户尝试使用这些标识符，protocol buffer 编译器会抱怨。max您可以使用关键字指定保留的数值范围达到最大可能值。

reserved请注意，您不能在同一语句中混合字段名称和数值。

您可以使用其他消息类型作为字段类型。例如，假设您想Result在每条SearchResponse消息中包含消息——为此，您可以Result在同一条消息中定义一个消息类型，.proto然后指定一个类型为Resultin的字段SearchResponse：

在上面的例子中，Result消息类型定义在同一个文件中SearchResponse——如果你想用作字段类型的消息类型已经在另一个.proto文件中定义了怎么办？

您可以通过导入.proto来自其他文件的定义来使用它们。要导入另一个的定义，请在文件顶部添加一个 import 语句：.proto

默认情况下，您只能使用直接导入.proto文件中的定义。但是，有时您可能需要将.proto文件移动到新位置。您可以在旧位置放置一个占位符文件，以使用该概念将所有导入转发到新位置，而不是直接移动.proto文件并在一次更改中更新所有调用站点。.protoimport public

请注意，公共导入功能在 Java 中不可用。

import publicimport public任何导入包含该语句的原型的代码都可以传递依赖依赖项。例如：

-I协议编译器使用/--proto_path标志在协议编译器命令行上指定的一组目录中搜索导入的文件。如果没有给出标志，它会在调用编译器的目录中查找。通常，您应该将--proto_path标志设置为项目的根目录，并为所有导入使用完全限定名称。

可以导入proto2消息类型并在您的 proto3 消息中使用它们，反之亦然。但是，proto2 枚举不能直接在 proto3 语法中使用（如果导入的 proto2 消息使用它们也没关系）。

您可以在其他消息类型中定义和使用消息类型，如下例所示 - 这里Result消息是在消息内部定义的SearchResponse：

如果您想在其父消息类型之外重用此消息类型，请将其称为_Parent_._Type_：

您可以随意嵌套消息：

如果现有的消息类型不再满足您的所有需求 - 例如，您希望消息格式有一个额外的字段 - 但您仍然希望使用使用旧格式创建的代码，请不要担心！在不破坏任何现有代码的情况下更新消息类型非常简单。只需记住以下规则：

未知字段是格式良好的协议缓冲区序列化数据，表示解析器无法识别的字段。例如，当旧二进制文件用新字段解析新二进制文件发送的数据时，这些新字段将成为旧二进制文件中的未知字段。

最初，proto3 消息在解析过程中总是丢弃未知字段，但在 3.5 版本中，我们重新引入了保留未知字段以匹配 proto2 行为。在 3.5 及更高版本中，未知字段在解析期间保留并包含在序列化输出中。

消息类型允许您将Any消息用作嵌入类型，而无需它们的 .proto 定义。AnAny包含任意序列化消息 as bytes，以及充当全局唯一标识符并解析为该消息类型的 URL。要使用该Any类型，您需要导入 google/protobuf/any.proto.

给定消息类型的默认类型 URL 是type.googleapis.com/_packagename_._messagename_。

不同的语言实现将支持运行时库助手以Any类型安全的方式打包和解包值——例如，在 Java 中，Any类型将具有特殊的pack()和unpack()访问器，而在 C++ 中则有PackFrom()和UnpackTo()方法：

目前，用于处理Any类型的运行时库正在开发中。

如果您已经熟悉proto2 语法，则Any可以保存任意 proto3 消息，类似于可以允许扩展的 proto2 消息。

如果您有一条包含多个字段的消息，并且最多同时设置一个字段，您可以强制执行此行为并使用 oneof 功能节省内存。

oneof 字段与常规字段一样，除了一个 oneof 共享内存中的所有字段外，最多可以同时设置一个字段。设置 oneof 的任何成员会自动清除所有其他成员。case()您可以使用特殊或方法检查 oneof 中设置的值（如果有）WhichOneof()，具体取决于您选择的语言。

要在您的中定义 oneof，请.proto使用oneof关键字后跟 oneof 名称，在这种情况下test_oneof：

然后，您将 oneof 字段添加到 oneof 定义中。您可以添加任何类型的字段，但map字段和repeated字段除外。

在您生成的代码中，oneof 字段具有与常规字段相同的 getter 和 setter。您还可以获得一种特殊的方法来检查 oneof 中设置了哪个值（如果有）。您可以在相关API 参考中找到有关所选语言的 oneof API 的更多信息。

SampleMessage message;message.set_name("name");CHECK(message.has_name());message.mutable_sub_message(); // Will clear name field.CHECK(!message.has_name());

SampleMessage message;SubMessage* sub_message = message.mutable_sub_message();message.set_name("name"); // Will delete sub_messagesub_message->set_... // Crashes here

SampleMessage msg1;msg1.set_name("name");SampleMessage msg2;msg2.mutable_sub_message();msg1.swap(&msg2);CHECK(msg1.has_sub_message());CHECK(msg2.has_name());

添加或删除其中一个字段时要小心。如果检查 oneof 的值返回None/ NOT_SET，则可能意味着 oneof 尚未设置或已设置为 oneof 不同版本中的字段。没有办法区分，因为无法知道线路上的未知字段是否是 oneof 的成员。

如果您想创建关联映射作为数据定义的一部分，protocol buffers 提供了一种方便的快捷语法：

...其中key_type可以是任何整数或字符串类型（因此，除浮点类型和之外的任何标量bytes类型）。请注意， enum 不是有效的key_type. value_type可以是任何类型，除了另一个地图。

因此，例如，如果您想创建一个项目映射，其中每条Project消息都与一个字符串键相关联，您可以这样定义它：

生成的地图 API 目前可用于所有 proto3 支持的语言。您可以在相关API 参考中找到有关所选语言的地图 API 的更多信息。

map 语法在网络上等同于以下内容，因此不支持 map 的协议缓冲区实现仍然可以处理您的数据：

任何支持映射的协议缓冲区实现都必须生成和接受上述定义可以接受的数据。

您可以将可选package说明符添加到.proto文件中，以防止协议消息类型之间的名称冲突。

然后，您可以在定义消息类型的字段时使用包说明符：

包说明符影响生成代码的方式取决于您选择的语言：

协议缓冲区语言中的类型名称解析与 C++ 类似：首先搜索最内部的范围，然后搜索下一个最内部的范围，依此类推，每个包都被认为是其父包的“内部”。一个领先的'.' （例如，.foo.bar.Baz）表示从最外面的范围开始。

协议缓冲区编译器通过解析导入的.proto文件来解析所有类型名称。每种语言的代码生成器都知道如何引用该语言中的每种类型，即使它有不同的范围规则。

如果您想在 RPC（远程过程调用）系统中使用您的消息类型，您可以在一个.proto文件中定义一个 RPC 服务接口，并且协议缓冲区编译器将以您选择的语言生成服务接口代码和存根。因此，例如，如果你想定义一个 RPC 服务，它的方法接受你的SearchRequest并返回 a SearchResponse，你可以在你的.proto文件中定义它，如下所示：

与协议缓冲区一起使用的最直接的 RPC 系统是gRPC：由 Google 开发的一种语言和平台中立的开源 RPC 系统。gRPC 特别适用于协议缓冲区，并允许您.proto使用特殊的协议缓冲区编译器插件直接从文件中生成相关的 RPC 代码。

如果您不想使用 gRPC，也可以将协议缓冲区与您自己的 RPC 实现一起使用。您可以在Proto2 语言指南中找到更多相关信息。

还有一些正在进行的第三方项目为 Protocol Buffers 开发 RPC 实现。有关我们了解的项目的链接列表，请参阅第三方附加组件 wiki 页面。

Proto3 支持 JSON 中的规范编码，从而更容易在系统之间共享数据。下表中按类型描述了编码。

如果 JSON 编码的数据中缺少某个值，或者其值为，则在解析到协议缓冲区时null将被解释为适当的默认值。如果某个字段在协议缓冲区中具有默认值，则在 JSON 编码的数据中默认将其省略以节省空间。实现可以提供选项以在 JSON 编码的输出中发出具有默认值的字段。

proto3 JSON 实现可以提供以下选项：

文件中的各个声明.proto可以用许多选项进行注释。选项不会改变声明的整体含义，但可能会影响它在特定上下文中的处理方式。可用选项的完整列表在 中定义google/protobuf/descriptor.proto。

一些选项是文件级选项，这意味着它们应该在顶级范围内编写，而不是在任何消息、枚举或服务定义中。一些选项是消息级别的选项，这意味着它们应该写在消息定义中。一些选项是字段级选项，这意味着它们应该写在字段定义中。选项也可以写在枚举类型、枚举值、oneof字段、服务类型、服务方法上；但是，目前不存在任何有用的选项。

以下是一些最常用的选项：

option java_package = "com.example.foo";

option java_outer_classname = "Ponycopter";

option java_multiple_files = true;

option optimize_for = CODE_SIZE;

int32 old_field = 6 [deprecated = true];

Protocol Buffers 还允许您定义和使用自己的选项。这是大多数人不需要的高级功能。如果您确实认为需要创建自己的选项，请参阅Proto2 语言指南了解详细信息。请注意，创建自定义选项使用extensions，这仅允许用于 proto3 中的自定义选项。

要生成需要使用.proto文件中定义的消息类型的 Java、Kotlin、Python、C++、Go、Ruby、Objective-C 或 C# 代码，您需要protoc在.proto. 如果您尚未安装编译器，请下载软件包并按照 README 中的说明进行操作。对于 Go，您还需要为编译器安装一个特殊的代码生成器插件：您可以在 GitHub 上的golang/protobuf存储库中找到此插件和安装说明。

协议编译器调用如下：

作为额外的便利，如果以orDST_DIR结尾，编译器会将输出写入具有给定名称的单个 ZIP 格式存档文件。输出也将按照 Java JAR 规范的要求提供一个清单文件。请注意，如果输出存档已经存在，它将被覆盖；编译器不够聪明，无法将文件添加到现有存档中。.zip.jar.jar