【ProtoBuf】文件编写及序列化
【ProtoBuf】文件编写及序列化
ProtoBuf文件编写及序列化
快速上手ProtoBuf
为了快速上手以及完整的使用ProtoBuf，我们将编写一个小项目，并根据PB学习程度对这个项目来逐渐改版，每一个版本对应PB的新知识点。在后续内容中，会使用简单的通讯录作为项目实现。
首先来确定第一版的通讯录要求：
- 对一个联系人的信息使用PB进行序列化，并将结果打印出来。
- 对序列化后的内容使用PB进行反序列化，解析出联系人信息并打印出来。
- 联系人包含以下信息：姓名、年龄。
通过这个通讯录1.0版本，我们能快速了解并使用PB初步要掌握的内容，以及体验到PB的完整使用流程。
创建.proto 文件
文件规范：
- 创建
.proto⽂件时，⽂件命名应该使⽤全⼩写字⺟命名，多个字⺟之间⽤ _ 连接。 例如：lower_snake_case.proto。 - 书写
.proto⽂件代码时，应使⽤ 2 个空格的缩进。
我们为通讯录1.0新建文件：contacts.proto
注释：
注释类型与C/C++中注释相同，使用 “//” 或者 “/* xxx*/”
指定Proto3语法
Protocol Buffers 语⾔版本3，简称 proto3，是 .proto ⽂件最新的语法版本。proto3 简化了 Protocol Buffers 语⾔，既易于使⽤，⼜可以在更⼴泛的编程语⾔中使⽤。它允许你使⽤ Java，C++，Python等多种语⾔⽣成 protocol buffer 代码。
在 .proto ⽂件中，要使⽤ syntax = "proto3"; 来指定文件语法为 proto3，并且必须写在除去注释内容的第⼀行。 如果没有指定，编译器会默认使用proto2语法。在通讯录 1.0 的 contacts.proto 文件中，可以为文件指定 proto3 语法，内容如下：
syntax = "proto3";Package声明符
package是一个可选的声明符，能表示.proto文件的命名空间（相当于C++中的namesapce），在项目中要有唯一性。
在通讯录1.0的contacts.proto文件中，我们可以声明命名空间如下：
syntax = "proto3";
package contacts;定义消息(message)
消息（message）: 要定义的结构化对象，我们可以给这个结构化对象中定义其对应的属性内容。这⾥再提⼀下为什么要定义消息？
在网络传输中，我们需要为传输双⽅定制协议。定制协议说白了就是定义结构体或者结构化数据， 比如，tcp，udp 报文就是结构化的。再⽐如将数据持久化存储到数据库时，会将⼀系列元数据统一用对象组织起来，再进行存储。
所以 ProtoBuf 就是以 message 的⽅式来⽀持我们定制协议字段，后期帮助我们形成类和⽅法来使⽤。在通讯录 1.0 中我们就需要为 联系⼈ 定义⼀个 message。
在.proto文件中定义一个消息类型的格式为：
message 消息类型名 // 建议使用驼峰命名法
{}为contacts.proto新增联系人message内容如下：
syntax = "proto3"; // 需要指定为proto3，否则默认为proto2语法
package contacts; // package是命名空间
// 定义联系人message
message PeopleInfo
{}定义消息字段
在message中我们可以定义其属性字段，字段定义格式为：字段类型 字段名 = 字段唯一编号;
- 字段名称命名规范：全小写字母，多个字母之间用_ 连接。
- 字段类型分为：标量数据类型 和 特殊类型（包括枚举、其他消息类型等）。
- 字段唯⼀编号：⽤来标识字段，⼀旦开始使⽤就不能够再改变。
以下表格展⽰了定义于消息体中的标量数据类型，以及编译 .proto ⽂件之后⾃动⽣成的类中与之对应的 字段类型。在这⾥展⽰了与 C++ 语⾔对应的类型：
.proto Type | Notes | C++ Type |
|---|---|---|
double | double | |
float | float | |
int32 | 使⽤变⻓编码[1]。负数的编码效率较低⸺若字段可能为负值，应使⽤ sint32 代替。 | int32 |
int64 | 使⽤变⻓编码[1]。负数的编码效率较低⸺若字段可能为负值，应使⽤ sint64 代替。 | int64 |
uint32 | 使⽤变⻓编码[1] | uint32 |
uint64 | 使⽤变⻓编码[1] | uint64 |
sint32 | 使⽤变⻓编码[1]。符号整型。负值的编码效率⾼于常规的 int32 类型 | int32 |
sint64 | 使⽤变⻓编码[1]。符号整型。负值的编码效率⾼于常规的 int64 类型 | int64 |
fixed32 | 定⻓ 4 字节。若值常⼤于2^28 则会⽐ uint32 更⾼效 | uint32 |
fixed64 | 定⻓ 8 字节。若值常⼤于2^56 则会⽐ uint64 更⾼效 | uint64 |
sfixed32 | 定长4字节 | int32 |
sfixed64 | 定长8字节 | int64 |
bool | bool | |
string | 包含 UTF-8 和 ASCII 编码的字符串，⻓度不能超过2^32 | string |
bytes | 可能包含任意的字节序列但长度不能超过2^32 | string |
- 注意：【1】变长编码是指：经过protobuf编码后，原本4字节或8字节的数可能会被变为其他字节数。
更新contacts.proto, 新增姓名、年龄字段：
// 首行：语法指定行（去除注释外的第一行）
/*首行：语法指定行（去除注释外的第一行）*/
syntax = "proto3"; // 需要指定为proto3，否则默认为proto2语法
package contacts; // package是命名空间
// 定义联系人message
// 结构中，给每个成员都赋值，这是语法必须规定，作为字段编号, 用来标识字段
message PeopleInfo
{
string name = 1; // 姓名
int32 age = 2; // 年龄
}字段唯一编号是有一定范围的：
1 ~ 536,870,911(2^29 - 1)，其中19000~19999不可用
19000~19999不可用是因为：在PB协议实现中，对这些数进行了预留。如果非要在.proto文件中使用这些预留标识号，例如将name字段的编号设置为19000，编译时机会报警。
值得⼀提的是，范围为 1 ~ 15 的字段编号需要⼀个字节进⾏编码， 16 ~ 2047 内的数字需要两个字节 进⾏编码。编码后的字节不仅只包含了编号，还包含了字段类型。所以 1 ~ 15 要⽤来标记出现⾮常频 繁的字段，要为将来有可能添加的、频繁出现的字段预留⼀些出来。
编译命令
编译命令的格式为：
protoc [--proto_path=IMPORT_PATH] --cpp_out=DST_DIR path/to/file.proto
protoc 是 Protocol Buffer 提供的命令⾏编译⼯具。
--proto_path 指定 被编译的.proto⽂件所在⽬录，可多次指定。可简写成 -I IMPORT_PATH 。如不指定该参数，则在当前⽬录进⾏搜索。
当某个.proto ⽂件 import 其他.proto ⽂件时, 或需要编译的 .proto ⽂件不在当前⽬录下，这时就要⽤-I来指定搜索⽬录。
--cpp_out= 指编译后的⽂件为 C++ ⽂件。
OUT_DIR 编译后⽣成⽂件的⽬标路径。
path/to/file.proto 要编译的.proto⽂件。编译contacts.proto文件命令如下：
protoc --cpp_out=. contacts.proto我们在终端使用这个命令后：
我们发现在同级目录中自动生成了contacts.pb.h文件和contacts.pb.cc文件，分别用来存放类的声明和类的实现。
Contacts.pb.h部分demo展示：
class PeopleInfo final : public ::PROTOBUF_NAMESPACE_ID::Message {
public:
using ::PROTOBUF_NAMESPACE_ID::Message::CopyFrom;
void CopyFrom(const PeopleInfo& from);
using ::PROTOBUF_NAMESPACE_ID::Message::MergeFrom;
void MergeFrom( const PeopleInfo& from) {
PeopleInfo::MergeImpl(*this, from);
}
static ::PROTOBUF_NAMESPACE_ID::StringPiece FullMessageName() {
return "PeopleInfo";
}
// string name = 1;
void clear_name();
const std::string& name() const;
template <typename ArgT0 = const std::string&, typename... ArgT>
void set_name(ArgT0&& arg0, ArgT... args);
std::string* mutable_name();
PROTOBUF_NODISCARD std::string* release_name();
void set_allocated_name(std::string* name);
// int32 age = 2;
void clear_age();
int32_t age() const;
void set_age(int32_t value);
};在上述例子中：
- 每个字段都有设置和获取的⽅法， getter 的名称与⼩写字段完全相同，setter ⽅法以 set_ 开头。
- 每个字段都有⼀个 clear_ ⽅法，可以将字段重新设置回 empty 状态。 contacts.pb.cc代码就是对类声明方法的一些实现，这里就不再展示了。
序列化方法：
在消息类的⽗类MessageLite 中，提供了读写消息实例的⽅法，包括序列化⽅法和反序列化⽅法：
class MessageLite {
public:
//序列化：
bool SerializeToOstream(ostream* output) const; // 将序列化后数据写⼊⽂件流
bool SerializeToArray(void *data, int size) const;
bool SerializeToString(string* output) const;
//反序列化：
bool ParseFromIstream(istream* input); // 从流中读取数据，再进⾏反序列化动作
bool ParseFromArray(const void* data, int size);
bool ParseFromString(const string& data);
};注意：
- 序列化的 结果为⼆进制字节序列 ，⽽⾮⽂本格式。
- 以上三种序列化的方法没有本质上的区别，只是序列化后输出的格式不同，可以供不同的应⽤场景使用。
- 序列化的 API 函数均为const成员函数，因为序列化不会改变类对象的内容， 而是将序列化的结果保存到函数入参指定的地址中。
序列化与反序列化的使用
创建⼀个测试⽂件 main.cc，⽅法中我们实现：
- 对⼀个联系⼈的信息使⽤ PB 进⾏序列化，并将结果打印出来。
- 对序列化后的内容使⽤ PB 进⾏反序列，解析出联系⼈信息并打印出来。
#include <iostream>
#include <string>
#include "contacts.pb.h"
int main()
{
std::string msg;
// 对一个联系人的信息使用 PB 进行序列化，并将结果答应出来
contacts::PeopleInfo people;
people.set_name("张三");
people.set_age(20);
if(!people.SerializeToString(&msg))
{
std::cerr << "序列化联系人失败!" << std::endl;
return -1;
}
std::cout << "序列化成功，结果: " << msg << std::endl;
// 对序列化后的内容使用 PB 进行反序列化，解析出联系人信息并打印出来
contacts::PeopleInfo people_result;
if(!people_result.ParseFromString(msg))
{
std::cerr << "反序列化联系人失败!" << std::endl;
return -1;
}
std::cout << "反序列化成功! " << std::endl
<< "姓名: " << people_result.name() << std::endl
<< "年龄: " << people_result.age() << std::endl;
return 0;
}然后我们进行编译，因为使用了protobuf，而protobuf实际上使用了C++11的新特性:
-std=c++11: 必加，使用C++11语法。-lprotobuf：必加，链接protubuf库。
由于 ProtoBuf 是把联系⼈对象序列化成了⼆进制序列，这⾥⽤ string 来作为接收⼆进制序列的容器。所以在终端打印的时候会有换⾏等⼀些乱码显⽰。所以相对于 xml 和 JSON 来说，因为被编码成⼆进制，破解成本增⼤，ProtoBuf 编码是相对安全的。
小结
- 编写.proto 文件，目的是为了定义结构对象（message）及属性内容。
- 使用 protoc 编译器编译 .proto ⽂件，生成⼀系列接口代码，存放在新生成头文件和源⽂件中。
- 依赖生成的接口，将编译生成的头⽂件包含进我们的代码中，实现对 .proto 文件中定义的字段进行设置和获取，和对 message 对象进⾏序列化和反序列化。
总的来说：ProtoBuf 是需要依赖通过编译⽣成的头文件和源文件来使用的。
腾讯云开发者
