系列文章
ProtoBuf 语法（二）
ProtoBuf 语法（三）

文章目录

前言
一、字段规则
二、消息类型的定义与使用
- 2.1 定义
- 2.2 使用
三、enum 类型
- 3.1 定义规则
- 3.2 注意事项
四、any 类型
- 4.1 类型说明
- 4.2 类型使用
五、oneof 类型
六、map 类型
七、默认值

前言

前面的文章介绍了 ProtoBuf 的基本概念，同时也展示了其基本使用方法，本文将详细的介绍 ProtoBuf 更多的字段以及语法。

一、字段规则

消息的字段可以用下面几种规则来修饰：

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

例如，更新 contacts.proto文件， PeopleInfo 消息中新增 phone字段，表示一个联系人有多个号码，可将其设置为 repeated，写法如下：

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

二、消息类型的定义与使用

2.1 定义

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

例如，更新contacts.proto文件，可以将phone提取出来，单独成为⼀个消息：

// -------------------------- 嵌套写法 -------------------------
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 使用

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

contacts.proto文件：

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

三、enum 类型

3.1 定义规则

proto3语法支持我们自己定义枚举类型，枚举类型在.proto文件中的编写规范如下：

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

例如，定义一个名为PhoneType的枚举类型：

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

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

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

3.2 注意事项

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

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

例如下面枚举的定义：

// ---------------------- 情况1：同级枚举类型包含相同枚举值名称--------------------
enum PhoneType {
	MP = 0; // 移动电话
	TEL = 1; // 固定电话
}
enum PhoneTypeCopy {
	MP = 0; // 移动电话 // 编译后报错：MP 已经定义
}

// ---------------------- 情况2：不同级枚举类型包含相同枚举值名称-------------------
enum PhoneTypeCopy {
	MP = 0; // 移动电话 // ⽤法正确
}
message Phone {
	string number = 1; // 电话号码
	enum PhoneType {
		MP = 0; // 移动电话
		TEL = 1; // 固定电话
	}
}

// ---------------------- 情况3：多⽂件下都未声明package--------------------
// phone1.proto
import "phone1.proto"
enum PhoneType {
	MP = 0; // 移动电话 // 编译后报错：MP 已经定义
	TEL = 1; // 固定电话
}
// phone2.proto
enum PhoneTypeCopy {
	MP = 0; // 移动电话
}

// ---------------------- 情况4：多⽂件下都声明了package--------------------
// phone1.proto
import "phone1.proto"
package phone1;
enum PhoneType {
	MP = 0; // 移动电话 // ⽤法正确
	TEL = 1; // 固定电话
}
// phone2.proto
package phone2;
enum PhoneTypeCopy {
	MP = 0; // 移动电话
}

上面4种情况，分别对应了以上的四个注意事项。

四、any 类型

4.1 类型说明

在proto3语法中，字段还可以声明为Any类型，可以理解为泛型类型。使用时可以在Any中存储任意消息类型。Any类型的字段也用repeated来修饰。

Any类型是google已经帮我们定义好的类型，在安装ProtoBuf时，其中的include目录下查找所有google已经定义好的.proto文件。

最初安装ProtoBuf的时候，我是将其安装到\usr\local目录下的，因此在该目录下查看即可：

4.2 类型使用

例如，在我们的contacts.proto中，为联系人增加一个地址信息，就可以使用Any类型的字段来存储地址信息，更新contacts.proto文件内容如下：

// 首行：语法指定
syntax = "proto3";
package contacts2; //指定作用域

import "google/protobuf/any.proto";

message Address
{
    string home_address = 1; //家庭住址
    string unit_address = 2; //单位地址
}

message PeopleInfo 
{
    string name = 1; //姓名
    int32 age = 2;   //年龄
    // repeated string phone_numbers = 3;

    // 嵌套定义message
    message Phone 
    {
        string number = 1;

        //使用枚举，增加电话类型
        enum PhoneType
        {
            MP = 0;  //移动电话
            TEL = 1; //固定电话
        }

        PhoneType type = 2;
    }

    repeated Phone phone = 3; //电话信息

    google.protobuf.Any data = 4;
}

//通讯录message
message Contacts 
{
    repeated PeopleInfo contacts = 1; 
}

编译后，contacts.pb.h更新的部分代码展示：

新生成的 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_name方法，返回值为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。

五、oneof 类型

如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使用 oneof 字段来加强这个行为，也能有节约内存的效果。oneof 字段定义的格式为：oneof 字段名 { 字段1; 字段2; ... } 。

例如在contacts.protp文件中为联系人新增其他的联系方式，比如QQ或者微信二选一。这里就可以使用到oneof字段来实现这个多选一的行为。

更新contacts.proto文件内容如下：

// 首行：语法指定
syntax = "proto3";
package contacts2; //指定作用域

import "google/protobuf/any.proto";

message Address
{
    string home_address = 1; //家庭住址
    string unit_address = 2; //单位地址
}

message PeopleInfo 
{
    string name = 1; //姓名
    int32 age = 2;   //年龄
    // repeated string phone_numbers = 3;

    // 嵌套定义message
    message Phone 
    {
        string number = 1;

        //使用枚举，增加电话类型
        enum PhoneType
        {
            MP = 0;  //移动电话
            TEL = 1; //固定电话
        }

        PhoneType type = 2;
    }

    repeated Phone phone = 3; //电话信息

    google.protobuf.Any data = 4; //Any 类型存储地址

    // 如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使⽤ oneof 字段来加强这个⾏为，也能有节约内存的效果。
    oneof other_contact //其他联系方式，多种只存在其一，如果都设置了，只保留最后一次设置的字段
    {
        // repeated string qq = 5; //不能使用 repeated
        string qq = 5;
        string wexing = 6;
    }
}

//通讯录message
message Contacts 
{
    repeated PeopleInfo contacts = 1; 
}

注意事项：

可选字段的编号不能与其他非可选字段的编号冲突。
不能在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_name方法。

六、map 类型

在proto3语法中，支持创建⼀个关联映射的字段，也就是可以使用map类型去声明字段类型，格式为：

map<key_type, value_type> map_field = N;

注意事项：

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

例如在contacts.protp文件中为联系人新增备注信息。这里就可以使用到map类型的字段来存储备注信息。更新contacts.proto文件内容如下：

// 首行：语法指定
syntax = "proto3";
package contacts2; //指定作用域

import "google/protobuf/any.proto";

message Address
{
    string home_address = 1; //家庭住址
    string unit_address = 2; //单位地址
}

message PeopleInfo 
{
    string name = 1; //姓名
    int32 age = 2;   //年龄
    // repeated string phone_numbers = 3;

    // 嵌套定义message
    message Phone 
    {
        string number = 1;

        //使用枚举，增加电话类型
        enum PhoneType
        {
            MP = 0;  //移动电话
            TEL = 1; //固定电话
        }

        PhoneType type = 2;
    }

    repeated Phone phone = 3; //电话信息

    google.protobuf.Any data = 4; //Any 类型存储地址

    // 如果消息中有很多可选字段，并且将来同时只有⼀个字段会被设置，那么就可以使⽤ oneof 字段来加强这个⾏为，也能有节约内存的效果。
    oneof other_contact //其他联系方式，多种只存在其一，如果都设置了，只保留最后一次设置的字段
    {
        // repeated string qq = 5; //不能使用 repeated
        string qq = 5;
        string wechat = 6;
    }

    // 使用 map ⽀持创建⼀个关联映射字段，也就是可以使⽤?map?类型去声明字段类型，格式为：map<key_type, value_type> map_field = N;
    // key_type 是除了 float 和 bytes 类型以外的任意标量类型。 value_type 可以是任意类型。
    // map 字段不可以⽤ repeated 修饰
    // map 中存⼊的元素是⽆序的
    map<string, string> remark = 7; //备注信息
}

//通讯录message
message Contacts 
{
    repeated PeopleInfo contacts = 1; 
}

编译后，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_name方法，返回值为Map类型的指针，这类方法会为我们开辟好空间，可以直接对这块空间的内容进行修改。
获取：获取方法的方法名称与小写字段名称完全相同。

七、默认值

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

类型	默认值
string	空字符串
bytes	空字节
bool	false
数值类型	0
enum	默认值的第⼀个定义的枚举值为 0
repeated	默认为空
信息字段	未设置该字段，它的取值依赖所要编译的语⾔