Protocol Buffers(proto3) 指南

这个指南描述了如何使用 protocol buffer 语言来组织你的 protocol buffer 数据，包括 .proto 文件语法和如何从你的 .proto 文件生成数据访问类。

定义一个消息类型

首先我们来看一个简单的例子。假设你要定义一个请求消息格式，每个搜索请求有一个查询字符串，你想要查询特定页数的数据，并且指定每一页的大小。这里是定义消息类型的 .proto 文件。

syntax = "proto3";

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

• 第一行表示我们使用的是 proto3 的语法；如果不指定版本，protobuf 编译器会当作 proto2 处理。这行必须处于文件开头。

• SearchRequest 消息类型定义了三个字段，每个字段有一个名字和类型。

指定字段类型

在上面的例子中，所有字段都是标量类型：两个整数（page_number 和 result_per_page） 和一个字符串(query)。然而，你也可以组合不同类型的字段到一个字段中，作为一个新的消息类型。

分配字段编号

正如你所见，消息中每个字段都有一个唯一的数字。这些字段数字被用来作为二进制消息中的唯一标识，同时一旦消息类型被使用就不应该再修改这个唯一标识。请注意，范围为 1 到 15 的字段号需要一个字节来编码， 包括字段号和字段的类型。16 到 2047 之间的字段编号占用两个字节。因此，应该为经常出现的消息元素保留数字 1 到 15。请记住为将来可能添加的频繁出现的元素流出一些空间。

指定字段规则

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

• 单数：格式正确的消息可以包含零个或一个此字段（但不能超过一个）。这是 proto3 语法的默认字段规则。

• repeated：在格式正确的消息中，此字段可以重复任意次（包括零次）。重复值的顺序将保留。

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

添加更多消息类型

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

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

message SearchResponse {}

添加注释

要将注释添加到 .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.
}

保留字段

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

message Foo {
    rserved 2, 15, 9 to 11;
    reserved "foo", "bar";
}

请注意，你不能在同 reversed 一条语句中混用字段名称和字段编号。

你产生了什么 .proto ?

编译器会以你选择的语言生成代码，你将需要使用文件中描述的消息类型，包括获取和设置字段值，将消息序列化为输出流，并从输入流中解析消息。

• 对于 C++，编译器从每个 .proto 生成一个 .h 和 .cc 文件，并为文件中描述的每种消息类型提供一个类。

• 对于 Java，编译器将生成一个 .java 文件，其中包含每种消息类型的类以及 Builder 用于创建消息实例的特殊类。

• Python 稍有不同 - Python 编译器会生成一个模块，其中包含每种消息类型的静态描述符，.proto 然后将该模块与元类一起使用，以在运行时创建必要的 Python 数据访问类。

• 对于 Go，编译器 .pb.go 将为文件中的每种消息类型生成一个具有相应类型的文件。

• 对于 Ruby，编译器将 .rb 使用包含你的消息类型的 Ruby 模块生成文件。

默认值

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

• 对于字符串，默认值为空字符串

• 对于字节，默认值为空字节

• 对于布尔值，默认值为 false

• 对于数字类型，默认值为 0

• 对于枚举，默认值为第一个定义的枚举值，必须为 0

• 对于消息字段，未设置该字段。它的确切值取决于语言。

重复字段的默认值为空。

请注意，对于标量消息字段，一旦解析了一条消息，就无法告诉该字段是显式设置为默认值（例如，是否将 boolean 设置为 false）还是根本没有设置：你应该牢记这一点定义消息类型时。

枚举

定义消息类型时，你可能希望其字段之一仅具有一个预定义的值列表之一。例如，假设你想为每个 SearchRequest 添加一个 corpus 字段，这个字段可以是 UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS。你可以简单地添加一个枚举类型到 SearchRequest 中。

在如下例子中，我们添加了一个名为 Corpus 的枚举类型，包含了所有可能的值。

message SearchRequest {
    string query = 1;
    int32 page_number = 2;
    int32 result_per_page = 3;
    enum Corpus {
        UNIVERSAL = 0;
        WEB = 1;
        IMAGES = 2;
        LOCAL = 3;
        NEWS = 4;
        PRODUCTS = 5;
        VIDEO = 6;
    }
    Corpus corpus = 4;
}

正如你所看到的，枚举类型字段 Corpus 的第一个常量是 0，每个枚举类型必须包含一个映射为零的常量作为其第一个元素。这是因为：

• 必须有一个零值，以便我们可以使用 0 作为数字默认值

• 零值必须是第一个元素，以便与 proto2 语义兼容，其中第一个枚举值始终是默认值。

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

enum EnumAllowingAlias {
    option allow_alias = true;
    UNKNOWN = 0;
    STARTED = 1;
    RUNNING = 1;
}
enum EnumNotAllowingAlias {
    UNKNOWN = 0;
    STARTED = 1;
    // RUNNING = 1; // Uncommenting this line will cause a compile error inside Google and a warning message outside.
}

枚举常量必须在 32 位整数范围内。

保留值

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

enum Foo {
    reserved 2, 15, 9 to 11, 40 to max;
    reserved "FOO", "BAR";
}

请注意，你不能在同 reversed 一条语句中混合使用字段名和数字值。

使用其他消息类型

你可以使用其他消息类型作为字段类型。例如，假设你想包括 Result 每个消息的 SearchResponse 消息 - 要做到这一点，你可以定义一个 Result 在同一个消息类型 .proto，然后指定类型的字段为 SearchResponse。

message SearchResponse {
    repeated Result results = 1;
}

message Result {
    string url = 1;
    string title = 2;
    repeated string snippets = 3;
}

导入定义

在上面的示例中，Result 消息类型与以下文件定义在同一文件中 SearchResponse - 如果要用作字段的消息类型已在另一个 .proto 文件中定义，该怎么办？

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

import "myproject/other_protos.proro"

默认情况下，你只能使用直接导入 .proto 文件中的定义。但是，有时你可能需要将 .proto 文件移到新位置。

// new.proto
// All definitions are moved here

// old.proto
// This is the proto that all clients are importing
import public "new.proto";
import "other.proto"

// client.proto
import "old.proto";
// You use definitions from old.proto and new.proto, but not other.proto

协议编译器使用 -I/--proto_path 标志在协议编译器命令行上指定的一组目录中搜索导入的文件。

嵌套类型

你可以在其他消息类型内定义和使用消息类型，如以下示例所示 - 在此处，Result 消息是在消息内定义的 SearchResponse：

message SearcResponse {
    message Result {
        string url = 1;
        string title = 2;
        repeated string snippets = 3;
    }
    repeated Result results = 1;
}

如果要在其父消息类型之外重用此消息类型，则将其称为：Parent.Type

message SomeOtherMessag {
    SearchResponse.Result result = 1;
}

你可以根据深度嵌套消息：

message Outer {
    message MiddleAA {
        message Inner {
            int64 ival = 1;
            bool booly = 2;
        }
    }
    message MiddleBB {
        message Inner {
            int32 ival = 1;
            bool booly = 2;
        }
    }
}

更新消息类型

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

• 不要更改任何现有字段的字段编号。

• 如果添加新字段，则仍可以使用新生成的代码来解析使用 "旧" 消息格式通过代码序列化的任何消息。你应该记住这些元素的默认值，以便新代码可以与旧代码生成的消息正确交互。 同样，由新代码创建的消息可以由旧代码解析：旧的二进制文件在解析时只会忽略新字段。

• 只要在更新的消息类型中不再使用字段号，就可以删除字段。你可能想要重命名该字段，或者添加前缀 "OBSOLETE_"，或将字段编号保留，以便将来的用户不会意外地重用该编号。

• int32，uint32，int64，uint64 和 bool 都是兼容的。

未知字段

未知字段是格式正确的 proto buf 序列化数据，表示解析器无法识别的字段。例如，当旧二进制文件使用新字段解析新二进制文件发送的数据时，这些新字段将成为旧二进制文件中的未知字段。

最初，proto3 消息在解析过程中总是丢弃未知字段，但是在版本 3.5 中，我们重新引入了保留未知字段以匹配 proto2 行为的功能。