Protobuf 语言指南（proto3）

定义消息类型

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

syntax = "proto3";

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

注意以下几点:

• 该文件的第一行指定使用 proto3 语法; 如果不写则使用 proto2.
• 一个消息对应一个字段, 一个字段对应一个数据类型.

值得注意的是: 字段类型可以是枚举或其他数据类型.

字段编号

比如 string query = 1; 字段, 1 就是字段编号(unique number).

字段编号的范围为 1 到 536,870,911. 不能使用数字 19000 到 19999, 因为它们是为 Google Protobuf 保留的.

在同一个 .proto 文件中添加多个消息类型

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

message SearchResponse {
 ...
}

保留字段

当定义好字段后, 在后续开发中发现某个字段根本没用.

例如 string userName = 2; 字段, 这个时候最好不要进行注释或删除.

有可能以后加载相同的旧版本, 这可能会导致数据损坏, 隐私错误等. 确保不会发生这种情况的一种方法是指定要删除的字段为保留字段.

message SubscribeReq {
  
  reserved 2;
  
  int32 subReqID = 1;
  string userName = 2;
  string productName = 3;
  string address = 4;
}

顾名思义, 就是此字段会被保留可能在以后会使用此字段. 使用关键字 reserved 表示要保留字段编号为 2.

上面代码我们在生成 Java 文件的时候会出现 ubscribeReqPeoro.proto: Field "userName" uses reserved number 2 错误信息, 所以需要将 string userName = 2; 注释, 或者删除.

值得注意的是: 您不能在同一 reserved 语句中混合字段名称和字段编号. 下面是表准格式:

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

指定字段规则

所指定的消息字段修饰符必须是如下之一:

• singular: 一个格式良好的消息应该有0个或者1个这种字段 (但是不能超过1个).
• repeated: 一个格式良好的消息中, 这种字段可以重复任意多次 (包括 0 次). 重复值的顺序会被保留.

枚举

当需要定义一个消息类型的时候, 可能想为一个字段指定某 “预定义值序列” 中的一个值.

例如, 假设要为每一个 SearchRequest 消息添加一个 corpus 字段, 而 corpus 的值可能是 UNIVERSAL, WEB, IMAGES, LOCAL, NEWS, PRODUCTS 或 VIDEO 中的一个.

其实可以很容易地实现这一点: 通过向消息定义中添加一个枚举 (enum) 并且为每个可能的值定义一个常量就可以了.

在下面的例子中, 在消息格式中添加了一个叫做 Corpus 的枚举类型——它含有所有可能的值——以及一个类型为 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;
}

值得注意的是:
每个枚举类型必须将其第一个类型映射为 0, 这是因为:

• 必须有有一个 0 值, 我们可以用这个 0 值作为默认值.
• 这个零值必须为第一个元素, 为了兼容 proto2 语义, 枚举类的第一个值总是默认值.

另外, 枚举常量必须在 32 位整数范围内, 并且尽量不要使用负数.

你可以通过将不同的枚举常量指定为相同的值. 如果这样做你需要将 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.
}

其它消息类型

你可以将其他消息类型用作字段类型. 例如, 假设在每一个 SearchResponse 消息中包含 Result 消息, 此时可以在相同的 .proto 文件中定义一个 Result 消息类型, 然后在 SearchResponse 消息中指定一个 Result 类型的字段, 如:

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

嵌套类型

你可以在其他消息类型中定义、使用消息类型, 在下面的例子中, Result 消息就定义在 SearchResponse 消息内, 如:

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

如果你想在它的父消息类型的外部重用这个消息类型, 你需要以 Parent.Type 的形式使用它, 如:

message SomeOtherMessage {
  SearchResponse.Result result = 1;
}

当然, 你也可以将消息嵌套任意多层, 如:

message Outer {                  // Level 0
  message MiddleAA {  // Level 1
    message Inner {   // Level 2
      int64 ival = 1;
      bool  booly = 2;
    }
  }

  message MiddleBB {  // Level 1
    message Inner {   // Level 2
      int32 ival = 1;
      bool  booly = 2;
    }
  }
}

导入定义

在上面的示例中, Result 和 SearchResponse 消息类型在同一文件中的, 如果要用作字段类型的消息类型在另一个 .proto 文件中定义, 该怎么办?

可以 .proto 通过导入来使用其他文件中的定义. 需要在文件顶部添加 import 语句:

import "myproject/other_protos.proto";

默认情况下, 使用直接导入的 .proto 文件中的定义.

但是, 有时可能需要将 .proto 文件移动到新位置. 如果直接移动文件位置可能要修改许多代码位置.

我们可以使用 import public 来解决这个问题.

实例代码:

// 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";
//您使用old.proto和new.proto中的定义，但不使用other.proto

Maps

如果要在数据定义中创建关联映射, 协议缓冲区提供了一种方便的快捷方式语法:

map < key_type ，value_type > map_field = N ;

key_type 可以是任何整数或字符串类型.
value_type 可以是除了 map 的其他类型.

例如, 如果要创建项目映射, 其中每条 Project 消息都与字符串键相关联, 则可以像下面这样定义它:

map < string，Project > projects = 3;

值得注意的是: map 不能使用 repeated.

包

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

package foo.bar;
message Open { ... }

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

message Foo {
  ...
  foo.bar.Open open = 1;
  ...
}

Any (任意类型)

// new.proto
syntax = "proto3";

import "google/protobuf/any.proto";

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  repeated google.protobuf.Any result_per_page = 3;
}

编译的时候需要将 google/protobuf/any.proto 和 new.proto 文件放到一起. 要注意目录结构.

然后执行下面命令进行编译:

sudo ./protoc -I=/home/sc-ik/桌面/  --java_out=./java /home/sc-ik/桌面/*.proto

在对 result_per_page 进行赋值时, 需要用到 Any 类中的 public static <T extends com.google.protobuf.Message> Any pack(T message) 方法.

在 java 代码中, 先创建 SearchRequest 对象, 然后对其他两个属性进行赋值.

New.SearchRequest.Builder searchRequest = New.SearchRequest.newBuilder();
searchRequest.setQuery("test");
searchRequest.setPageNumber(10086);

在对 result_per_page 进行赋值时, 需要注意: pack 方法的参数类型为 com.google.protobuf.Message 接口.

生成的 java 代码中, 类是继承自 GeneratedMessageV3.

public static final class SearchRequest extends
            com.google.protobuf.GeneratedMessageV3 implements
            // @@protoc_insertion_point(message_implements:SearchRequest)
            SearchRequestOrBuilder {
        private static final long serialVersionUID = 0L;

但是如果将result_per_page 赋值为 SearchRequest, 应该怎么操作呢?

重点就是继承的 GeneratedMessageV3 抽象类, 这个抽象类又继承了 AbstractMessage 抽象类, 而 AbstractMessage 抽象类就是 com.google.protobuf.Message 接口的实现.

public abstract class AbstractMessage
    // TODO(dweis): Update GeneratedMessage to parameterize with MessageType and BuilderType.
    extends AbstractMessageLite implements Message {

所以我们可以使用以下方法进行赋值.

searchRequest.addResultPerPage(
        com.google.protobuf.Any.pack(
                searchRequest.build()
        )
);

pack() 方法我个人理解为序列化, 那么和他对应的是反序列化 unpack().

// 将接收到的字节数组饭序列化.
New.SearchRequest.Builder builder2 = New.SearchRequest.newBuilder().mergeFrom(bytes1);

// 获取到 result_per_page 字段的值.
Any.Builder resultPerPageBuilder = builder2.getResultPerPageBuilder(0);

// 然后使用 unpack 将任意类型 进行反序列化, 得到想要的数据.
New.SearchRequest unpack1 = resultPerPageBuilder.build().unpack(New.SearchRequest.class);

编译

编译命令:

protoc -I=$SRC_DIR --java_out=$DST_DIR $SRC_DIR/*.proto

如下:

sudo ./protoc -I=/home/sc-ik/桌面/ --java_out=./java /home/sc-ik/桌面/*.proto

各种语言的文件参数以及 API
https://developers.google.com...