当前位置：首页 > news >正文

protobuf实用教程

news 来源：原创 2025/5/24 0:05:32

引言

protobuf安装

protobuf数据类型

基本数据类型

复合类型

Map类型

protobuf使用教程

编写.proto文件

编译

使用

序列化与反序列化

结语

引言

protobuf 是 google 的一种数据交换的格式，它独立于平台语言。 google 提供了 protobuf 多种语言的实现：java、c#、c++、go 和 python。

每一种实现都包含了相应语言的编译器以及库文件。由于它是一种二进制的格式，比使用 xml（20倍）、json（10倍）进行数据交换快许多。可以把它用于分布式应用之间的数据通信或者异构环境下的数据交换。作为一种效率和兼容性都很优秀的二进制数据传输格式，可以用于诸如网络传输、配置文件、数据存储等诸多领域。

protobuf安装

先从github下载源代码https://github.com/google/protobuf，或者在分享的链接下载源码包。

通过网盘分享的文件：protobuf-master.zip
链接: https://pan.baidu.com/s/14GVIt2SwpgkobfpUOJQO5Q?pwd=1234 提取码: 1234
--来自百度网盘超级会员v3的分享

源码包中的src/README.md，有详细的安装说明，安装过程如下：

1、解压压缩包：unzip protobuf-master.zip

2、进入解压后的文件夹：cd protobuf-master

3、安装所需工具：sudo apt-get install autoconf automake libtool curl make g++ unzip

4、自动生成conﬁgure配置文件：./autogen.sh

5、配置环境：./conﬁgure

6、编译源代码(时间比较长)：make

7、安装：sudo make install

8、刷新动态库：sudo ldconﬁg

按步骤进行即可完成安装。安装完成后可以使用 protoc --version 验证，安装成功会输出版本信息。

protobuf数据类型

protobuf的数据类型主要有三种：基本数据类型，复合类，Map类型（proto3版本后支持）。

基本数据类型

double：双精度浮点数。
float：单精度浮点数。
int32：32位有符号整数。
int64：64位有符号整数。
uint32：32位无符号整数。
uint64：64位无符号整数。
sint32：32位有符号整数，使用zigzag编码以优化负数存储。
sint64：64位有符号整数，使用zigzag编码以优化负数存储。
fixed32：32位无符号整数（固定长度，不使用varint编码）。
fixed64：64位无符号整数（固定长度，不使用varint编码）。
sfixed32：32位有符号整数（固定长度）。
sfixed64：64位有符号整数（固定长度）。
bool：布尔值，true 或 false。
string：UTF-8 编码的字符串。
bytes：字节序列。

复合类型

复合类型有三种：消息，枚举，map。

消息

消息是 protobuf 中最核心的复合类型，用于定义结构化数据。我们可以在消息中定义字段，这些字段可以是基本数据类型，也可以是其他消息类型。使用起来和 cpp 的结构体类似。

示例：定义一个Person消息，包含三个字段：名称，id，电子邮件。

message Person 
{string name = 1;int32 id = 2;string email = 3;
}

定义中的 = 并不是赋值，而是字段编号，消息体中的每个字段都必须有一个字段编号，这个编号是用于在消息的二进制格式中唯一标识字段的。

每个字段编号在同一个消息定义中必须是唯一的。在二进制格式中，字段编号与字段类型和字段值一起被编码。字段编号用于标识消息中的特定字段。

字段可以使用 repeated 修饰，重复字段类似于数组或列表，允许一个字段有多个值。重复字段使用 repeated 关键字声明，可以包含基本数据类型或其他消息类型的元素。重复字段在序列化时会包含元素的数量，因此可以动态地表示不同数量的元素。

使用示例：

message Contact 
{repeated string phone_numbers = 1;
}

任意消息Any类型，Any类型可以存储任何消息类型的值，可以在消息中包含未知类型的消息。

使用示例：

message AnyMessage 
{google.protobuf.Any details = 1;
}

oneof允许在一个组内为字段提供一个单一的选择，组内字段互斥，只能设置一个字段的值。

message SampleMessage 
{oneof test_oneof {string name = 1;int32 id = 2;}
}

枚举

枚举类型用于定义一组命名的整数常量。用于定义一组命名的整数常量。枚举提供了一种类型安全的方式来表示一组有限的、固定的值。用法和 cpp 中的枚举基本类似。

使用示例：枚举 Color 定义三种颜色。

enum Color 
{RED = 0;GREEN = 1;BLUE = 2;
}

枚举类型可以作为消息中的字段类型，提供了对特定值集合的限制。

Map类型

map 用于存储键值对集合。从 protobuf 3.0 开始，map 类型被引入作为语言中原生支持的类型，允许定义一个字段为一个映射，其中键和值可以是任何有效的 protobuf 数据类型。用法和cpp中基本相同。

定义map类型时，需要指定键（key）和值（value）的数据类型。

键只能是以下类型之一：int32、sint32、uint32、int64、sint64、uint64、bool 或 string。
值可以是任何消息中有效的类型，包括基本数据类型、枚举、消息类型，甚至是另一个 map 类型。

使用示例：

message MapMessage 
{map<int32, string> int_to_string = 1;map<string, MapMessage> string_to_message = 2;
}

protobuf使用教程

编写.proto文件

使用protobuf，我们需要创建一个.proto文件来定义数据结构。

syntax = "proto3";package test;message Person 
{string name = 1;int32 id = 2;string email = 3;
}

这里定义了一个Person消息，包含三个字段：name、id和email。

syntax

syntax 关键词用于指定 .proto 文件使用的语法版本。syntax 声明必须位于文件的最开始部分，它告诉 protoc 编译器使用哪个版本的 protobuf 语法规则来解析 .proto 文件。

syntax 声明的基本用法：

使用Proto2 语法

proto syntax = "proto2";

使用Proto3 语法

 proto syntax = "proto3";

proto2 是 Protocol Buffers 的原始语法版本。 在 proto2 语法中，字段可以被标记为 required、optional 或 repeated。 proto2 支持 default 值和 extensions 等特性。

proto3 是 Protocol Buffers 的更新版本，引入了一些新特性和简化。 在 proto3 语法中，所有字段都是可选的。没有 required 或 optional 关键字，只有 repeated。 proto3 不支持 default 值和 extensions，但引入了 map 类型和字段编号的更多限制。 proto3 语法更简洁，推荐使用。

package

package 声明用于定义一个 .proto 文件中所有消息、枚举和 RPC 服务的命名空间。与 cpp 中的命名空间相同。

语法：

package package_name;

import

要引用其他包中的类型，需要在 .proto文件的顶部使用 import 关键字。

import "path/other.proto";

导入的类型必须使用其完全限定名（包括包名）来引用。使用示例：

syntax = "proto3";package com.example;import "addressbook.proto";message Greeting 
{string greeting = 1;com.example.person.Person person = 2; // 引用其他包中的 Person 消息
}

编译

我们需要使用 protoc 命令行工具编译 .proto 文件。语法：

protoc -I=<source_files_directory> --<language>_out=<output_directory> <proto_file.proto>

-I=<source_files_directory>: 指定 .proto 文件所在的目录。
-- <language>_out=<output_directory>: 指定生成代码的语言和输出目录。
<proto_file.proto>: 指定要编译的 .proto 文件。

这里我们准备了一个测试文件person.proto:

syntax = "proto3";package test;message Person 
{string name = 1;int32 id = 2;string email = 3;
}

我们执行 protoc 命令编译

protoc --cpp_out=. person.proto

可以看到当前目录下生成了两个文件：person.pb.h 与 person.cc。

person.pb.h 头文件包含了 Person 消息的 C++ 类声明。它定义了消息的结构和所有字段的访问器（getter/setter）函数。

person.pb.cc 文件这个源文件包含了 Person 消息类的实现，包括字段的访问器函数和序列化/反序列化方法的实现。

我们只关注生成的person类：

class Person : public google::protobuf::Message 
{public:// 构造函数和析构函数Person();virtual ~Person();// 字段访问器const std::string& name() const;void set_name(const std::string& value);// ...// 序列化和反序列化bool SerializeToString(std::string* output) const;bool ParseFromString(const std::string& data);// ...
};

对于每个字段都生成了访问器，提供了对定义的数据结构的操作接口：

set_字段名(值)：用于设置消息中的字段值。

例如：user->set_name("John Doe");

字段名()：用于获取消息中的字段值（只读）。

例如：const string& name = user->name();

mutable_字段名()：返回指向字段的指针，允许修改字段值。

例如：string* mutable_name = user->mutable_name();

add_字段名()：对于repeated字段，用于添加新的元素。

例如：User* user = userList.add_users();

字段名_size()：返回repeated字段中的元素个数。

例如：int size = contacts.contacts_size();

字段名(int index)：获取repeated字段中指定索引的元素。

例如：const PeopleInfo& first_contact = contacts.contacts(0);

mutable_字段名(int index)：返回指向repeated字段中指定索引元素的指针，允许修改。

例如：PeopleInfo* contact = contacts.mutable_contacts(0);

clear_字段名()：清空repeated字段中的所有元素。

例如：contacts.clear_contacts();

对于我们的类生成了以下几个访问接口：

//name
const std::string& name() const;
void set_name(const std::string& value);
void set_name(std::string&& value);
void set_name(const char* value);
void set_name(const char* value, size_t size);
std::string* mutable_name();//email
const std::string& email() const;
void set_email(const std::string& value);
void set_email(std::string&& value);
void set_email(const char* value);
void set_email(const char* value, size_t size);
std::string* mutable_email();//id
::PROTOBUF_NAMESPACE_ID::int32 id() const;
void set_id(::PROTOBUF_NAMESPACE_ID::int32 value);

使用

我们简单测试一下：

#include<iostream>
#include<string>
#include"person.pb.h"using namespace std;
using namespace test;int main()
{Person p;p.set_name("张三");p.set_email("123456789@qq.com");p.set_id(234560);string name=p.name();string email=p.email();int id=p.id();cout << "name: " <<  name << endl;cout << "email: " << email << endl;cout << "id: " << id << endl;return 0;
}

我们编译一下：

g++ -o test person.pb.cc test.cpp -lprotobuf -lpthread -std=c++11

注意：protobuf中使用了线程库，所以我们需要链接线程库。

程序运行结果如下:

序列化与反序列化

序列化和反序列化在类中也生成了接口：

SerializeToString：将Protobuf消息序列化为字符串。
SerializeToArray：将Protobuf消息序列化为字节数组。
SerializeToOstream：将Protobuf消息序列化为输出流。
ParseFromString：从字符串中解析Protobuf消息。
ParseFromArray：从字节数组中解析Protobuf消息。
ParseFromIstream：从输入流中解析Protobuf消息。

我们这里只介绍最常用的接口，即序列化与反序列化为字符串，其他方法也大同小异：

序列化为字符串

bool SerializeToString(std::string* output) const;

反序列为对象

 bool ParseFromString(const std::string& data)

我们简单使用一下：

#include "person.pb.h"
#include <iostream>
#include <string>using namespace test;
using namespace std;int main()
{Person p;p.set_name("张三");p.set_email("123456789@qq.com");p.set_id(234560);string out;//序列化p.SerializeToString(&out);cout << "序列化：" << out << endl;Person s;s.ParseFromString(out);string name=s.name();string email=s.email();int id=s.id();cout << "反序列化：" << endl;cout << "name: " <<  name << endl;cout << "email: " << email << endl;cout << "id: " << id << endl;return 0;
}

运行结果如下：

结语

到这里我们已经完成了prptobuf的基础学习。笔者能力有限，如有错漏之处，欢迎指正。同时很多命令语法只是讲了基础用法，并不全面，如果有读者有兴趣可以深入研究。感谢观看！

引言

protobuf安装

protobuf数据类型

基本数据类型

复合类型

Map类型

protobuf使用教程

编写.proto文件

编译

使用

序列化与反序列化

结语

相关文章：