protobuf3基本语法

protobuf3语法模板

syntax = "proto3";//文件第一行指定使用的protobuf版本，如果不指定，默认使用proto2。如果指定，则必须在文件的非空非注释的第一行

package protobuf;//定义proto包名,可以为.proto文件新增一个可选的package声明符作为生成语言的namespace，用来防止不同的消息类型有命名冲突

import public "other_protos.proto";//引入其他protobuf文件
import  "google/protobuf/any.proto";

option optimize_for = SPEED;//可以被设置为 SPEED, CODE_SIZE,or LITE_RUNTIME。这些值将影响C++代码的生成,默认是SPEED，一般不需要设置。

//messaage可以理解为C++中的class关键字
 message Person {
     //变量（字段）的定义格式为：[修饰符（可选）][数据类型][变量名（字段名）] = [唯一标识符] ,其中唯一标识符是用来标识字段的，同一个message中字段的标识符不能相同
     string var1 = 1;
     //string var2 = 1;//该变量定义会编译报错，因为编号1已经被使用了

     /*
        protobuf中的基本数据类型----对应的c++基础数据类型
        int32     ----    int
        int64     ----    long
        double    ----    double
        float     ----    float
        bytes     ----    string
        bool      ----    bool
        此外，还有：
        uint32    ----    int
        uint64    ----    long
        sint32    ----    int
        sint64    ----    long
        fixed32   ----    int
        fixed64   ----    long
        sfixed32  ----    int
        sfixed64  ----    long
     */

     /*
        proto3取消了required和optional两个关键字
        repeated用来定义数组
     */
     repeated string list = 2;
     /*
       使用map
     */
     map<string, string> projects = 23;
     /*
        有时候你需要保留一些你以后要用到的编号或者变量名，使用reserved关键字
     */
     reserved 3, 15, 9 to 11;
     reserved "foo", "bar";

     //string var2 = 3;//编译会报错，因为3被保留了
     //string var3 = 10;//编译会报错，因为10被保留了
     //string foo = 12;//编译会报错，因为foo被保留了

     /*
     由于一些历史原因，基本数值类型的repeated的字段并没有被尽可能地高效编码。在新的代码中，用户应该使用特殊选项[packed=true]来保证更高效的编码。
     注意[packed=true]只能用在 repeated修饰的数字类型中
     */
     repeated int32 var11 = 28 [packed=true];

     /*
        关于字段的默认值：
        string类型的变量，默认值是空字符串
        bytes类型的变量，默认值是空byte数组
        bool类型的变量，默认值是false
        数字类型的变量，默认值是0
        枚举类型的变量，默认值是第一个枚举值,而且这个第一个枚举值的数字值必须是0

     */

     /*
        定义枚举
        一个enum类型的字段只能用指定的常量集中的一个值作为其值（如果尝试指定不同的值，解析器就会把它当作一个未知的字段来对待）
     */

     enum Corpus {
         UNIVERSAL = 0;//第一个枚举值，这里的数字必须是0，不然编译不通过
         WEB = 1;
         //WEB1 = 1;//这里编译不通过，数字1只能对应一个枚举值。
         IMAGES = 2;
         LOCAL = 3;
         NEWS = 4;
         PRODUCTS = 5;
         VIDEO = 6;
     }
     Corpus corpus = 4;

     /*
        你可以为枚举常量定义别名。 需要设置allow_alias option 为 true, 否则 protocol编译器会产生错误信息。
     */
     enum EnumAllowingAlias {
         option allow_alias = true;
         UNKNOWN = 0;
         STARTED = 1;
         RUNNING = 1;
     }

    /*
        Message Type 作为变量
    */
     Test test = 14;//同一个包下的other_protos.proto文件中的message Test作为变量的类型

    /*
        嵌套的message，message可以无限嵌套
    */
     message Result {
         string url = 1;
         string title = 2;
         repeated string snippets = 3;
     }
     repeated Result results = 16;
     repeated Person.Result results1 = 17;//也可以这样定义

     /*
        使用Any变量，用于定义任意的值
     */
     repeated google.protobuf.Any details = 21;

     /*
        使用Oneof变量
        如果你的消息中有很多可选字段， 并且同时至多一个字段会被设置， 你可以加强这个行为，使用oneof特性节省内存.
        Oneof字段就像可选字段， 除了它们会共享内存， 至多一个字段会被设置。 设置其中一个字段会清除其它oneof字段。 你可以使用case()或者WhichOneof() 方法检查哪个oneof字段被设置， 看你使用什么语言了.
        你可以增加任意类型的字段, 但是不能使用 required, optional, repeated 关键字.
        在产生的代码中, oneof字段拥有同样的 getters 和setters， 就像正常的可选字段一样. 也有一个特殊的方法来检查到底那个字段被设置. 你可以在相应的语言API中找到oneof API介绍
        设置oneof会自动清楚其它oneof字段的值. 所以设置多次后，只有最后一次设置的字段有值.
     */
     oneof test_oneof {
         string name = 24;
         Result sub_message = 29;
     }
}


/*
    定义服务
*/
//service SearchService {
//    rpc Search (SearchRequest) returns (SearchResponse);
//}

定义一个消息类型

假设你想定义一个“搜索请求”的消息格式，每一个请求含有一个查询字符串、你感兴趣的查询结果所在的页数，以及每一页多少条查询结果。可以采用如下的方式来定义消息类型的.proto文件了：

syntax = "proto3";

package services;

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

修饰符

字段的修饰符可以是以下值：

• singular（默认）：在一个格式良好的消息应该有0个或者1个这种字段（但是不能超过1个）。
• repeated：repeated一般用来定义数组。在一个格式良好的消息中，这种字段可以重复任意多次（包括0次），重复的值的顺序会被保留。默认情况下，标量数值类型的repeated字段使用packed的编码方式。

数据类型

标量数据类型

一个标量消息字段可以含有一个如下的类型：double、float、int32、uint32、uint64、sint32、sint64fixed32、fixed64、sfixed32、sfixed64、bool、string、bytes。

枚举数据类型

当想为一个字段指定某“预定义值序列”中的一个值时，向消息定义中添加一个枚举（enum）类型就可以了。enum类型里的第一个枚举值后面的标识符必须为0。一个enum类型的字段只能用指定的常量集中的一个值作为其值。

你可以为枚举常量定义别名。 需要设置allow_alias option 为 true, 否则 protocol编译器会产生错误信息。

message SearchRequest {
  //定义一个枚举类型Corpus
  enum Corpus {
  	option allow_alias = true;
    UNIVERSAL = 0;//第一个枚举值，这里的数字必须是0，不然编译不通过
    WEB = 1;
    //WEB1 = 1;这里编译不通过，数字1只能对应一个枚举值。
    IMAGES = 2;
    LOCAL = 3;
    NEWS = 4;
    PRODUCTS = 5;
    VIDEO = 6;
  }
  //定义一个Corpus类型的corpus
  Corpus corpus = 4;
}

map

如果你希望创建一个关联映射，protocol buffer提供了一种快捷的语法：

map<key_type, value_type> map_field = N;

其中key_type可以是除了floating和bytes的任意标量类型，value_type可以是任意类型。

例如，如果你希望创建一个project的映射，每个Projecct使用一个string作为key，你可以像下面这样定义：

map<string, Project> projects = 23;

数据类型的默认值

当一个消息被解析的时候,如果在编码后的消息结构中某字段没有初始值，相应的字段在被解析的对象中会被设置默认值。这些默认值都是类型相关的。

• 字符串默认值为空字符串。
• 字节类型默认值是空字节。
• 布尔类型默认值为 false。
• 数值类型默认值为 0。
• 枚举类型默认值是其定义中的第一个值，它必须为 0。
• 消息类型的默认值没有设置。它的具体值与使用的编程语言有关。
  repeated字段的默认值为空（通常是相应编程语言的空列表）。

注意：对于标量消息字段，当消息被解析时，我们没有办法知道某个字段是否被显示地设定为默认值（例如一个布尔类型的字段值是否被设置为 false），也许这个字段压根就没有被设定值。当我们定义一个消息类型时，我们需要牢记这点。例如，如果一个布尔类型的字段在其值被设置为false时，会导致某种行为的发生，而我们并不想让这种行为在默认情况下也会发生，那么我们就不要定义这个bool类型的字段。 还要注意的是，在序列化的时候，如果标量消息字段的值设为默认值，这个值是不会被序列化的。

唯一标识符

在消息定义中，每个字段都有唯一的一个数字标识符。这些标识符是用来在消息的二进制格式中识别各个字段的，一旦开始使用就不能够再改变。最小的标识符可以从1开始，最大到2²⁹ - 1, or 536,870,911。不可以使用其中的[19000－19999]的标识符。

注：[1,15]之内的标识号在编码的时候会占用一个字节。[16,2047]之内的标识号则占用2个字节。所以应该为那些频繁出现的消息元素保留 [1,15]之内的标识符。

切记：要为将来有可能添加的、频繁出现的标识号预留一些标识符。

预留标识符（Reserved）

假如一个旧版本.proto文件将某个字段完全删除或注释，之后生成了一个新版本的.proto文件。用户在对新版本.proto文件进行操作时，可能会重用那些已经被删除的字段的标识符或名称，如果以后加载相同.proto文件的旧版本，这可能会导致严重问题，比如数据损坏。

为了确保不会发生这种情况，我们指定已删除字段的字段编号或字段名称为“reserved”。 如果将来的任何用户尝试使用这些字段标识符，则编译会出错。

message Foo {
  reserved 2, 15, 9 to 11;//预留字段名称
  reserved "foo", "bar";//预留字段标识符
}

注意：不能在同一 “reserved” 语句中将字段名称和字段标识符混合在一起指定。

在一个.proto文件中使用多个message

直接定义多个message

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

message SearchResponse {
  repeated Result results = 1;
}

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

导入message

在上面的例子中，Result消息类型与SearchResponse是定义在同一文件中的。如果想要使用的message已经在其他.proto文件中已经定义过了呢？

你可以通过导入（importing）其他.proto文件中的定义来使用其他文件的message。要导入其他.proto文件的message的定义，你需要在你的文件中添加一个导入声明，如：

import "myproject/other_protos.proto";

默认情况下你只能使用直接导入的.proto文件中的定义。然而， 有时候你需要移动一个.proto文件到一个新的位置。现在，你可以在旧位置放置一个虚拟 .proto 文件，以使用命令 import public将所有导入转发到新位置，而不是直接移动 .proto 文件并在一次更改中更新所有调用点。导入包含 import public 语句的 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 让 protocol 编译器在指定的一组目录中搜索要导入的文件。如果没有给出这个命令选项，它将查找调用编译器所在的目录。通常，你应将 --proto_path 设置为项目的根目录，并对所有导入使用完全正确的名称。

使用protobuf2的message

在你的proto3message中导入proto2的message也是可以的，反之亦然，但是proto2枚举不可以直接在proto3的标识符中使用（如果仅仅在proto2消息中使用是可以的）。

嵌套message

你可以在其他 message 类型中定义和使用 message 类型，如下例所示，此处Result消息在SearchResponse 消息中嵌套定义，SearchResponse 消息为Result消息的父消息。

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;
}

.proto支持嵌套多层消息：

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;
    }
  }
}

Any字段

使用Any，可以定义任意类型的字段。指定消息类型的默认类型URL是type.googleapis.com/packagename.messagename.

import "google/protobuf/any.proto";

message ErrorStatus {
  string message = 1;
  repeated google.protobuf.Any details = 21;
}

在c++中有PackFrom()和UnpackTo()方法以typesafe方式打包和解压缩ANY类型的值：

// Storing an arbitrary message type in Any.
NetworkErrorDetails details = ...;
ErrorStatus status;
status.add_details()->PackFrom(details);

// Reading an arbitrary message from Any.
ErrorStatus status = ...;
for (const Any& detail : status.details()) {
  if (detail.Is<NetworkErrorDetails>()) {
    NetworkErrorDetails network_error;
    detail.UnpackTo(&network_error);
    ... processing network_error ...
  }
}

oneof字段

如果你的 message 包含许多可选字段，并且最多只能同时设置其中一个字段，则可以使用 oneof 功能强制执行此行为并节省内存。

Oneof 共享内存中的所有字段，并且最多只能同时设置一个字段。设置 oneof 的任何成员会自动清除所有其他成员。你可以使用特殊的 case() 或 WhichOneof() 方法检查 oneof 字段中当前是哪个值（如果有）被设置，具体方法取决于你选择的语言。

oneof的使用

要在 .proto 中定义 oneof，请使用 oneof 关键字，后跟你的 oneof 名称，在本例中为 test_oneof：

message SampleMessage {
  oneof test_oneof {
     string name = 4;
     SubMessage sub_message = 9;
  }
}

然后，将 oneof 字段添加到test_oneof的定义中。你可以在test_oneof添加任何类型的字段，但不能使用 required，optional 或 repeated 关键字。如果需要向 oneof 添加重复字段，可以使用包含重复字段的 message。

在生成的代码中，oneof 字段与常规 optional 方法具有相同的 getter 和 setter。你还可以使用特殊方法检查 oneof 中的值（如果有）。

oneof的特性

• 设置 oneof 字段将自动清除 oneof 的所有其他成员。因此，如果你设置了多个字段，则只有你设置的最后一个字段仍然具有值。

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

• 如果解析器遇到同一个 oneof 的多个成员，则在解析的消息仅使用看到的最后一个成员。
• oneof 不支持扩展
• oneof 不能使用 repeated
• 反射 API 适用于 oneof 字段
• 如果你使用的是 C++，请确保你的代码不会导致内存崩溃。以下示例代码将崩溃，因为已通过调用 set_name() 方法删除了 sub_message。

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

• 同样在 C++中，如果你使用 Swap() 交换了两条 oneofs 消息，则每条消息将以另一条消息的 oneof 实例结束：在下面的示例中，msg1 将具有 sub_message 而 msg2 将具有 name。

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

定义服务（RPC）

如果要将 message 类型与 RPC（远程过程调用）系统一起使用，则可以在 .proto 文件中定义 RPC 服务接口，protocol buffer 编译器将以你选择的语言生成服务接口和stub（桩）。因此，例如，如果要定义一个 RPC 服务，其中包含一个根据 SearchRequest 返回 SearchResponse 的方法，可以在 .proto 文件中定义它，如下所示：

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

message SearchResponse {
  string result = 1;
}

service SearchService {
  rpc Search (SearchRequest) returns (SearchResponse);
}

与 ProtoBuf 直接搭配使用的 RPC 系统是 gRPC :一个 Google 开发的平台无关语言无关的开源 RPC 系统。gRPC 和 ProtoBuf 能够非常完美的配合，你可以使用专门的 ProtoBuf 编译插件直接从.proto 文件生成相关 RPC 代码。

包（Packages）

你可以将可选的package说明符添加到 .proto 文件作为生成语言的namespace，以防止不同message 类型之间的名称冲突。

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

你可以在定义 message 类型的字段时使用package说明符：

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

package 对生成的代码的影响取决于你所选择的语言，在 C++ 中，生成的类包含在 C++ 命名空间中。例如，Open 将位于命名空间 foo::bar 中。

Protocol buffer语言中类型名称的解析与C++是一致的：首先从最内部开始查找，依次向外进行，每个包会被看作是其父类包的内部类。当然对于 （foo.bar.Baz）这样以“.”分隔的意味着是从最外围开始的。

ProtocolBuffer编译器会解析.proto文件中定义的所有类型名。 对于不同语言的代码生成器会知道如何来指向每个具体的类型，即使它们使用了不同的规则。

选项（Options）

在定义.proto文件时能够标注一系列的options。Options并不改变整个文件声明的含义，但却能够影响特定环境下处理方式。完整的可用选项可以在google/protobuf/descriptor.proto找到。

一些选项是文件级别的，意味着它可以作用于最外范围，不包含在任何消息内部、enum或服务定义中。一些选项是消息级别的，意味着它可以用在消息定义的内部。当然有些选项可以作用在域、enum类型、enum值、服务类型及服务方法中。到目前为止，并没有一种有效的选项能作用于所有的类型。