【快速上手ProtoBuf】proto 3 语法详解

1 🍑字段规则🍑

消息的字段可以⽤下⾯⼏种规则来修饰：

singular ：消息中可以包含该字段零次或⼀次（不超过⼀次）。 proto3 语法中，字段默认使⽤该规则。
repeated ：消息中可以包含该字段任意多次（包括零次），其中重复值的顺序会被保留。可以理解为定义了⼀个数组。

比如：

syntax = "proto3";
package contacts;
message PeopleInfo 
{
  string name = 1; 
  int32 age = 2; 
  repeated string phone_numbers = 3;
}

2 🍑消息类型的定义与使用🍑

2.1 🍎定义🍎

在单个 .proto ⽂件中可以定义多个消息体，且⽀持定义嵌套类型的消息（任意多层）。每个消息体中的字段编号可以重复。

嵌套写法:

syntax = "proto3";
package contacts;
message PeopleInfo 
{
  string name = 1; 
  int32 age = 2; 
  message Phone 
  {
    string number = 1;
  }
}

⾮嵌套写法:

syntax = "proto3";
package contacts;
message Phone 
{
  string number = 1;
}
message PeopleInfo 
{
  string name = 1; 
  int32 age = 2; 
}

2.2 🍎使用🍎

消息类型可作为字段类型使⽤：

syntax = "proto3";
package contacts;
message PeopleInfo 
{
  string name = 1; 
  int32 age = 2; 
  message Phone 
  {
    string number = 1; 
  }
 repeated Phone phone = 3; 
}

可导⼊其他 .proto ⽂件的消息并使⽤
例如 Phone 消息定义在 phone.proto ⽂件中：

syntax = "proto3";
package phone;
message Phone 
{
  string number = 1; 
}

contacts.proto 中的 PeopleInfo 使⽤ Phone 消息：

syntax = "proto3";
package contacts;
import "phone.proto"; // 使⽤ import 将 phone.proto ⽂件导⼊进来 !!!
message PeopleInfo 
{
  string name = 1; 
  int32 age = 2; 
 // 引⼊的⽂件声明了package，使⽤消息时，需要⽤ ‘命名空间.消息类型’ 格式 
 repeated phone.Phone phone = 3; 
}

注：在 proto3 ⽂件中可以导⼊ proto2 消息类型并使⽤它们，反之亦然。

3 🍑通讯录版本v2🍑

contacts.proto：

syntax = "proto3";
package contacts;

// 联系⼈
message PeopleInfo 
{
  string name = 1; // 姓名
  int32 age = 2; // 年龄
  message Phone 
  {
    string number = 1; // 电话号码
  }
  repeated Phone phone = 3; // 电话
}
// 通讯录
message Contacts 
{
  repeated PeopleInfo contacts = 1;
}

接着进⾏⼀次编译：

 protoc --cpp_out=. contacts.proto

3.1 🍎通讯录v2的写入实现🍎

main.cc:

#include <iostream>
#include <fstream>
#include "contacts.pb.h"
using namespace std;
using namespace contacts;
/**
 * 新增联系⼈
 */
void AddPeopleInfo(PeopleInfo *people_info_ptr)
{
    cout << "-------------新增联系⼈-------------" << endl;
    cout << "请输⼊联系⼈姓名: ";
    string name;
    getline(cin, name);
    people_info_ptr->set_name(name);
    cout << "请输⼊联系⼈年龄: ";
    int age;
    cin >> age;
    people_info_ptr->set_age(age);
    cin.ignore(256, '\n');//遇到'\n'结束，或者接受到的数据大于256
    for (int i = 1;; i++)
    {
        cout << "请输⼊联系⼈电话" << i << "(只输⼊回⻋完成电话新增): ";
        string number;
        getline(cin, number);
        if (number.empty())
        {
            break;
        }
        PeopleInfo_Phone *phone = people_info_ptr->add_phone();
        phone->set_number(number);
    }
    cout << "-----------添加联系⼈成功-----------" << endl;
}
int main(int argc, char *argv[])
{
    // GOOGLE_PROTOBUF_VERIFY_VERSION 宏: 验证没有意外链接到与编译的头⽂件不兼容的库版
    // 本。如果检测到版本不匹配，程序将中⽌。注意，每个 .pb.cc ⽂件在启动时都会⾃动调⽤此宏。在使
    // ⽤ C++ Protocol Buffer 库之前执⾏此宏是⼀种很好的做法，但不是绝对必要的。
    GOOGLE_PROTOBUF_VERIFY_VERSION;
    if (argc != 2)
    {
        cerr << "Usage: " << argv[0] << " CONTACTS_FILE" << endl;
        return -1;
    }
    Contacts contacts;

    // 先读取已存在的 contacts
    fstream input(argv[1], ios::in | ios::binary);
    if (!input)
    {
        cout << argv[1] << ": File not found. Creating a new file." << endl;
    }
    else if (!contacts.ParseFromIstream(&input))
    {
        cerr << "Failed to parse contacts." << endl;
        input.close();
        return -1;
    }
    // 新增⼀个联系⼈
    AddPeopleInfo(contacts.add_contacts());
    // 向磁盘⽂件写⼊新的 contacts
    fstream output(argv[1], ios::out | ios::trunc | ios::binary);
    if (!contacts.SerializeToOstream(&output))
    {
        cerr << "Failed to write contacts." << endl;
        input.close();
        output.close();
        return -1;
    }
    input.close();
    output.close();
    google::protobuf::ShutdownProtobufLibrary();
    return 0;
}

注意点代码中有解释。

验证：
在这里插入图片描述
查看⼆进制⽂件：

3.2 🍎通讯录v2的读取实现🍎

#include <iostream>
#include <fstream>
#include "contacts.pb.h"
using namespace std;
using namespace contacts;
/**
 * 打印联系⼈列表
 */
void PrintfContacts(const Contacts &contacts)
{
    for (int i = 0; i < contacts.contacts_size(); ++i)
    {
        const PeopleInfo &people = contacts.contacts(i);
        cout << "------------联系⼈" << i + 1 << "------------" << endl;
        cout << "姓名：" << people.name() << endl;
        cout << "年龄：" << people.age() << endl;
        int j = 1;
        for (const PeopleInfo_Phone &phone : people.phone())
        {
            cout << "电话" << j++ << ": " << phone.number() << endl;
        }
    }
}
int main(int argc, char *argv[])
{

    GOOGLE_PROTOBUF_VERIFY_VERSION;
    if (argc != 2)
    {
        cerr << "Usage: " << argv[0] << "CONTACTS_FILE" << endl;
        return -1;
    }
    // 以⼆进制⽅式读取 contacts
    Contacts contacts;
    fstream input(argv[1], ios::in | ios::binary);
    if (!contacts.ParseFromIstream(&input))
    {
        cerr << "Failed to parse contacts." << endl;
        input.close();
        return -1;
    }
    // 打印 contacts
    PrintfContacts(contacts);
    input.close();
    google::protobuf::ShutdownProtobufLibrary();
    return 0;
}

验证：
在这里插入图片描述

另⼀种验证⽅法--decode
我们可以⽤ protoc -h 命令来查看 ProtoBuf 为我们提供的所有命令 option。其中 ProtoBuf 提供⼀个命令选项 --decode ，表⽰从标准输⼊中读取给定类型的⼆进制消息，并将其以⽂本格式写⼊标准输出。消息类型必须在 .proto ⽂件或导⼊的⽂件中定义。

在这里插入图片描述

4 🍑enum 类型🍑

4.1 🍎定义规则🍎

语法⽀持我们定义枚举类型并使⽤。在.proto⽂件中枚举类型的书写规范为：

枚举类型名称使⽤驼峰命名法，⾸字⺟⼤写。例如： MyEnum
常量值名称全⼤写字⺟，多个字⺟之间⽤ _ 连接。例如： ENUM_CONST = 0;

我们可以定义⼀个名为 PhoneType 的枚举类型，定义如下：

enum PhoneType 
{
 MP = 0; // 移动电话
 TEL = 1; // 固定电话
}

要注意枚举类型的定义有以下⼏种规则：

0 值常量必须存在，且要作为第⼀个元素。这是为了与 proto2 的语义兼容：第⼀个元素作为默认值，且值为 0。
枚举类型可以在消息外定义，也可以在消息体内定义（嵌套）。
枚举的常量值在 32 位整数的范围内，但因负值⽆效因⽽不建议使⽤（与编码规则有关）。

4.2 🍎注意事项🍎

将两个 具有相同枚举值名称 的枚举类型放在单个 .proto ⽂件下测试时，编译后会报错：某某某常量已经被定义！所以这⾥要注意：

同级（同层）的枚举类型，各个枚举类型中的常量不能重名。
单个 .proto ⽂件下，最外层枚举类型和嵌套枚举类型，不算同级。
多个 .proto ⽂件下，若⼀个⽂件引⼊了其他⽂件，且每个⽂件都未声明 package，每个 proto ⽂件中的枚举类型都在最外层，算同级。
多个 .proto ⽂件下，若⼀个⽂件引⼊了其他⽂件，且每个⽂件都声明了 package，不算同级。

5 🍑Any 类型🍑

字段还可以声明为 Any 类型，可以理解为泛型类型。使⽤时可以在 Any 中存储任意消息类型。Any 类型的字段也⽤ repeated 来修饰。
Any 类型是 google 已经帮我们定义好的类型，在安装 ProtoBuf 时，其中的 include ⽬录下查找所有google 已经定义好的 .proto ⽂件。

在这里插入图片描述

此时我们可以再升级通讯录版本：
.proto文件：

syntax = "proto3";
package contacts;
import "google/protobuf/any.proto"; // 引⼊ any.proto ⽂件
// 地址
message Address
{
  string home_address = 1; // 家庭地址
  string unit_address = 2; // 单位地址
}
// 联系⼈
message PeopleInfo 
{
  string name = 1; // 姓名
  int32 age = 2; // 年龄
 message Phone 
 {
   string number = 1; // 电话号码
   enum PhoneType 
   {
     MP = 0; // 移动电话
     TEL = 1; // 固定电话
   }
   PhoneType type = 2; // 类型
 }
 repeated Phone phone = 3; // 电话
 google.protobuf.Any data = 4;
}
// 通讯录
message Contacts 
{
 repeated PeopleInfo contacts = 1;
}

使用protoc编译器编译后：

// 新⽣成的 Address 类
class Address final : public ::PROTOBUF_NAMESPACE_ID::Message 
{
public:
 using ::PROTOBUF_NAMESPACE_ID::Message::CopyFrom;
 void CopyFrom(const Address& from);
 using ::PROTOBUF_NAMESPACE_ID::Message::MergeFrom;
 void MergeFrom( const Address& from) 
 {
 	Address::MergeImpl(*this, from);
 }
 // string home_address = 1;
 void clear_home_address();
 const std::string& home_address() const;
 template <typename ArgT0 = const std::string&, typename... ArgT>
 void set_home_address(ArgT0&& arg0, ArgT... args);
 std::string* mutable_home_address();
 PROTOBUF_NODISCARD std::string* release_home_address();
 void set_allocated_home_address(std::string* home_address);
 // string unit_address = 2;
 void clear_unit_address();
 const std::string& unit_address() const;
 template <typename ArgT0 = const std::string&, typename... ArgT>
 void set_unit_address(ArgT0&& arg0, ArgT... args);
 std::string* mutable_unit_address();
 PROTOBUF_NODISCARD std::string* release_unit_address();
 void set_allocated_unit_address(std::string* unit_address);
};
// 更新的 PeopleInfo 类
class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message 
{
public:
 // .google.protobuf.Any data = 4;
 bool has_data() const;
 void clear_data();
 const ::PROTOBUF_NAMESPACE_ID::Any& data() const;
 PROTOBUF_NODISCARD ::PROTOBUF_NAMESPACE_ID::Any* release_data();
 ::PROTOBUF_NAMESPACE_ID::Any* mutable_data();
 void set_allocated_data(::PROTOBUF_NAMESPACE_ID::Any* data);
};

上述的代码中，对于 Any 类型字段：设置和获取：获取⽅法的⽅法名称与⼩写字段名称完全相同。设置⽅法可以使⽤ mutable_ ⽅法，返回值为Any类型的指针，这类⽅法会为我们开辟好空间，可以直接对这块空间的内容进⾏修改。

之前讲过，我们可以在 Any 字段中存储任意消息类型，这就要涉及到任意消息类型和 Any 类型的互转。这部分代码就在 Google为我们写好的头⽂件 any.pb.h 中。对 any.pb.h 部分代码展⽰：

class PROTOBUF_EXPORT Any final : public ::PROTOBUF_NAMESPACE_ID::Message 
{
 bool PackFrom(const ::PROTOBUF_NAMESPACE_ID::Message& message) 
 {
 ...
 }
 bool UnpackTo(::PROTOBUF_NAMESPACE_ID::Message* message) const 
 {
 ...
 }
 template<typename T> bool Is() const 
 {
 return _impl_._any_metadata_.Is<T>();
 }
};

上述代码中：

使⽤ PackFrom() ⽅法可以将任意消息类型转为 Any 类型。
使⽤ UnpackTo() ⽅法可以将 Any 类型转回之前设置的任意消息类型。
使⽤ Is() ⽅法可以⽤来判断存放的消息类型是否为 typename T。

6 🍑oneof 类型🍑

如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使⽤ oneof 加强这个⾏为，也能有节约内存的效果。

注意:

可选字段中的字段编号，不能与⾮可选字段的编号冲突。
不能在 oneof 中使⽤ repeated 字段。
将来在设置 oneof 字段中值时，如果将 oneof 中的字段设置多个，那么只会保留最后⼀次设置的成员，之前设置的 oneof 成员会⾃动清除。

contacts.pb.h 更新的部分代码展⽰：

// 更新的 PeopleInfo 类
class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message 
{
 enum OtherContactCase 
 {
 kQq = 5,
 kWeixin = 6,
 OTHER_CONTACT_NOT_SET = 0,
 };
 // string qq = 5;
 bool has_qq() const;
 void clear_qq();
 const std::string& qq() const;
 template <typename ArgT0 = const std::string&, typename... ArgT>
 void set_qq(ArgT0&& arg0, ArgT... args);
 std::string* mutable_qq();
 PROTOBUF_NODISCARD std::string* release_qq();
 void set_allocated_qq(std::string* qq);
  // string weixin = 6;
 bool has_weixin() const;
 void clear_weixin();
 const std::string& weixin() const;
 template <typename ArgT0 = const std::string&, typename... ArgT>
 void set_weixin(ArgT0&& arg0, ArgT... args);
 std::string* mutable_weixin();
 PROTOBUF_NODISCARD std::string* release_weixin();
 void set_allocated_weixin(std::string* weixin);
 void clear_other_contact();
 OtherContactCase other_contact_case() const;
};

上述的代码中，对于 oneof 字段：

会将 oneof 中的多个字段定义为⼀个枚举类型。
设置和获取：对 oneof 内的字段进⾏常规的设置和获取即可，但要注意只能设置⼀个。如果设置多个，那么只会保留最后⼀次设置的成员。
清空 oneof 字段：clear_ ⽅法
获取当前设置了哪个字段：_case ⽅法

7 🍑map 类型🍑

语法⽀持创建⼀个关联映射字段，也就是可以使⽤ map 类型去声明字段类型，格式为：

map<key_type, value_type> map_field = N;

要注意的是：

key_type 是除了 float 和 bytes 类型以外的任意标量类型。 value_type 可以是任意类型。
map 字段不可以⽤ repeated 修饰。
map 中存⼊的元素是⽆序的。

contacts.pb.h 更新的部分代码展⽰：

// 更新的 PeopleInfo 类
class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message 
{
 // map<string, string> remark = 7;
 int remark_size() const;
 void clear_remark();
 const ::PROTOBUF_NAMESPACE_ID::Map< std::string, std::string >&
 remark() const;
 ::PROTOBUF_NAMESPACE_ID::Map< std::string, std::string >*
 mutable_remark();
};

上述的代码中，对于Map类型的字段：

清空map: clear_ ⽅法。
设置和获取：获取⽅法的⽅法名称与⼩写字段名称完全相同。设置⽅法为 mutable_ ⽅法，返回值为Map类型的指针，这类⽅法会为我们开辟好空间，可以直接对这块空间的内容进⾏修改。

8 🍑默认值🍑

反序列化消息时，如果被反序列化的⼆进制序列中不包含某个字段，反序列化对象中相应字段时，就会设置为该字段的默认值。不同的类型对应的默认值不同：

对于字符串，默认值为空字符串。
对于字节，默认值为空字节。
对于布尔值，默认值为 false。
对于数值类型，默认值为 0。
对于枚举，默认值是第⼀个定义的枚举值，必须为 0。
对于消息字段，未设置该字段。它的取值是依赖于语⾔。
对于设置了 repeated 的字段的默认值是空的（通常是相应语⾔的⼀个空列表）。对于消息字段、 oneof字段和 any字段，C++ 和 Java 语⾔中都有 has_ ⽅法来检测当前字段是否被设置。

9 🍑更新消息🍑

9.1 🍎更新规则🍎

如果现有的消息类型已经不再满⾜我们的需求，例如需要扩展⼀个字段，在不破坏任何现有代码的情况下更新消息类型⾮常简单。遵循如下规则即可：

禁⽌修改任何已有字段的字段编号。
若是移除⽼字段，要保证不再使⽤移除字段的字段编号。正确的做法是保留字段编号（reserved），以确保该编号将不能被重复使⽤。不建议直接删除或注释掉字段。
int32， uint32， int64， uint64 和 bool 是完全兼容的。可以从这些类型中的⼀个改为另⼀个，⽽不破坏前后兼容性。若解析出来的数值与相应的类型不匹配，会采⽤与 C++ ⼀致的处理⽅案（例如，若将 64 位整数当做 32 位进⾏读取，它将被截断为 32 位）。
sint32 和 sint64 相互兼容但不与其他的整型兼容。
string 和 bytes 在合法 UTF-8 字节前提下也是兼容的。
bytes 包含消息编码版本的情况下，嵌套消息与 bytes 也是兼容的。
fixed32 与 sfixed32 兼容， fixed64 与 sfixed64兼容。
enum 与 int32，uint32， int64 和 uint64 兼容（注意若值不匹配会被截断）。但要注意当反序列化消息时会根据语⾔采⽤不同的处理⽅案：例如，未识别的 proto3 枚举类型会被保存在消息中，但是当消息反序列化时如何表⽰是依赖于编程语⾔的。整型字段总是会保持其的值。
oneof：
- 将⼀个单独的值更改为新 oneof 类型成员之⼀是安全和⼆进制兼容的。
- 若确定没有代码⼀次性设置多个值那么将多个字段移⼊⼀个新 oneof 类型也是可⾏的。
- 将任何字段移⼊已存在的 oneof 类型是不安全的。

9.2 🍎保留字段 reserved🍎

如果通过删除或注释掉字段来更新消息类型，未来的⽤⼾在添加新字段时，有可能会使⽤以前已经存在，但已经被删除或注释掉的字段编号。将来使⽤该 .proto 的旧版本时的程序会引发很多问题：数据损坏、隐私错误等等。

确保不会发⽣这种情况的⼀种⽅法是：使⽤ reserved 将指定字段的编号或名称设置为保留项。当我们再使⽤这些编号或名称时，protocol buffer 的编译器将会警告这些编号或名称不可⽤。

9.3 🍎未知字段🍎

未知字段：解析结构良好的 protocol buffer 已序列化数据中的未识别字段的表⽰⽅式。例如，当旧程序解析带有新字段的数据时，这些新字段就会成为旧程序的未知字段。

本来，proto3 在解析消息时总是会丢弃未知字段，但在 3.5 版本中重新引⼊了对未知字段的保留机制。所以在 3.5 或更⾼版本中，未知字段在反序列化时会被保留，同时也会包含在序列化的结果中。

9.4 🍎前后兼容性🍎

向前兼容：⽼模块能够正确识别新模块⽣成或发出的协议。
向后兼容：新模块也能够正确识别⽼模块⽣成或发出的协议。

前后兼容的作⽤：当我们维护⼀个很庞⼤的分布式系统时，由于你⽆法同时升级所有模块，为了保证在升级过程中，整个系统能够尽可能不受影响，就需要尽量保证通讯协议的“向后兼容”或“向前兼容”。

10 🍑选项 option🍑

.proto ⽂件中可以声明许多选项，使⽤ option 标注。选项能影响 proto 编译器的某些处理⽅式。

10.1 🍎常用选项列举🍎

optimize_for : 该选项为⽂件选项，可以设置 protoc 编译器的优化级别，分别为 SPEED 、CODE_SIZE 、 LITE_RUNTIME 。受该选项影响，设置不同的优化级别，编译 .proto ⽂件后⽣成的代码内容不同。
- SPEED : protoc 编译器将⽣成的代码是⾼度优化的，代码运⾏效率⾼，但是由此⽣成的代码编译后会占⽤更多的空间。 SPEED 是默认选项。
- CODE_SIZE : proto 编译器将⽣成最少的类，会占⽤更少的空间，是依赖基于反射的代码来实现序列化、反序列化和各种其他操作。但和 SPEED 恰恰相反，它的代码运⾏效率较低。这种⽅式适合⽤在包含⼤量的.proto⽂件，但并不盲⽬追求速度的应⽤中。
- LITE_RUNTIME : ⽣成的代码执⾏效率⾼，同时⽣成代码编译后的所占⽤的空间也是⾮常少。这是以牺牲Protocol Buffer提供的反射功能为代价的，仅仅提供 encoding+序列化功能，所以我们在链接 BP 库时仅需链接libprotobuf-lite，⽽⾮libprotobuf。这种模式通常⽤于资源有限的平台，例如移动⼿机平台中。

option optimize_for = LITE_RUNTIME;

allow_alias ：允许将相同的常量值分配给不同的枚举常量，⽤来定义别名。该选项为枚举选项。
举个例⼦：

enum PhoneType 
{
 option allow_alias = true;
 MP = 0;
 TEL = 1;
 LANDLINE = 1; // 若不加 option allow_alias = true; 这⼀⾏会编译报错
}