赞
踩
系列文章
ProtoBuf 语法(二)
ProtoBuf 语法(三)
前面的文章介绍了 ProtoBuf 的基本概念,同时也展示了其基本使用方法,本文将详细的介绍 ProtoBuf 更多的字段以及语法。
消息的字段可以用下面几种规则来修饰:
例如,更新
contacts.proto
文件,PeopleInfo
消息中新增phone
字段,表示一个联系人有多个号码,可将其设置为repeated
,写法如下:
syntax = "proto3";
package contacts;
message PeopleInfo {
string name = 1;
int32 age = 2;
repeated string phone = 3;
}
在单个.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; }
消息类型可作为字段类型使用:
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;
}
proto3
语法支持我们自己定义枚举类型,枚举类型在.proto
文件中的编写规范如下:
MyEnum
_
连接,例如:ENUM_CONST = 0;
例如,定义一个名为
PhoneType
的枚举类型:
enum PhoneType {
MP = 0; // 移动电话
TEL = 1; // 固定电话
}
需要注意枚举类型的定义有以下规则:
proto2
的语法兼容:第一个元素作为默认值,且值为 0。将两个 具有相同枚举值名称
的枚举类型放在单个.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种情况,分别对应了以上的四个注意事项。
proto3
语法中,字段还可以声明为Any
类型,可以理解为泛型类型。使用时可以在Any
中存储任意消息类型。Any
类型的字段也用repeated
来修饰。Any
类型是google
已经帮我们定义好的类型,在安装ProtoBuf
时,其中的include
目录下查找所有google
已经定义好的.proto
文件。
最初安装ProtoBuf的时候,我是将其安装到
\usr\local
目录下的,因此在该目录下查看即可:
例如,在我们的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 字段名 { 字段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
方法。在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 | 默认为空 |
信息字段 | 未设置该字段,它的取值依赖所要编译的语⾔ |
另外,对于 消息字段
、 oneof
字段和any
字段 ,C++ 和 Java 语言中都有has_
方法来检测当前字段是否被设置。
Copyright © 2003-2013 www.wpsshop.cn 版权所有,并保留所有权利。