protocolbuffers / protobuf

71,30916,148+13 todayC++

View on GitHub

Protocol Buffers - Google's data interchange format

💡 Use Cases

最适合需要跨语言、高性能、版本兼容的结构化数据序列化和通信场景。

微服务间数据通信

Problem: 不同编程语言编写的微服务之间需要高效、类型安全地交换结构化数据，但JSON/XML序列化性能差且缺乏强类型约束。

Solution: 使用protobuf定义服务间通信的数据结构，通过protoc编译器生成各语言对应的强类型代码，实现高效二进制序列化和反序列化。

Example: Go编写的订单服务和Java编写的库存服务通过protobuf定义的Order消息进行通信，确保字段类型一致且传输效率高。

配置文件序列化

Problem: 应用需要将复杂的配置对象持久化到文件或数据库中，但传统格式如JSON缺乏版本兼容性支持，字段增减容易导致解析失败。

Solution: 使用protobuf的向后兼容特性定义配置结构，新增字段不会破坏旧版本程序的解析，支持平滑升级。

Example: 游戏客户端读取服务器下发的配置文件，即使服务器新增了配置字段，旧版本客户端也能正常解析已有字段。

高性能RPC框架

Problem: 需要实现跨语言的高性能远程过程调用，但手动实现序列化和网络通信复杂且容易出错。

Solution: 结合gRPC等RPC框架使用protobuf作为接口定义语言，自动生成客户端和服务端代码，统一序列化协议。

Example: 定义protobuf服务接口后，protoc自动生成C++服务器和Python客户端的stub代码，开发者只需实现业务逻辑。

大数据存储格式

Problem: 海量结构化数据需要高效存储和传输，但CSV/JSON等文本格式占用空间大，解析速度慢。

Solution: 使用protobuf二进制格式存储数据，相比文本格式可减少50%-80%的存储空间，并大幅提升解析性能。

Example: 日志分析系统将每天TB级的访问日志序列化为protobuf格式存储，节省存储成本并加速离线分析任务。

📊 Project Info

Language: C++
Stars: ⭐ 71,309
Forks: 16,148
Today: +13
Ranking: #2
Collection: Language
Trending Date: June 3, 2026
Last Push: 6/3/2026

🏷️ Topics

C++序列化数据交换跨平台高性能开发者

Difficulty

初级

Est. Time

3-5小时

Target Audience

对数据序列化、微服务通信或跨语言数据交换感兴趣的开发者，具备基本编程概念但可能没有protobuf使用经验。

🎯 What You'll Learn

能够理解Protocol Buffers的核心概念，安装protoc编译器，编写简单的.proto文件，并使用生成的代码在C++中进行基本的数据序列化与反序列化。

📋 Prerequisites

基本编程概念了解

理解变量、数据类型、函数等基础概念，以便理解数据结构的定义和序列化的目的。

C++基础了解

本项目指南以C++为例，需要能理解简单的C++代码（如类、头文件包含），用于编译和运行示例。

命令行操作熟悉

需要在终端中执行命令来安装软件、编译代码和运行程序。

📚 Resources

必看

Protocol Buffers 文档

官方全面的文档，包含语言指南（定义消息类型）、风格指南、API参考等。是学习核心概念的最佳起点。

🗺️ Learning Phases

环境准备与安装

⏱ 30-60分钟

安装Protocol Compiler (protoc)

根据你的操作系统，从GitHub Release页面下载预编译的protoc二进制文件（如protoc-xx.x-win64.zip）。解压后，将protoc可执行文件路径添加到系统的PATH环境变量中。在终端运行 `protoc --version` 验证安装。

💡对于新手，强烈建议下载预编译版本，而非从源码编译。选择与你的项目需求匹配的稳定版本（而非main分支）。

安装C++运行时库

如果你计划使用C++进行开发，需要安装protobuf的C++库。对于Linux/macOS用户，可以使用包管理器（如 `apt-get install libprotobuf-dev` 或 `brew install protobuf`）。Windows用户可参考源码中的CMakeLists.txt或使用vcpkg。

💡确保protoc编译器版本与C++运行时库版本兼容，最好使用相同版本。

核心概念与快速入门

⏱ 60-90分钟

理解.proto文件

创建一个名为 `person.proto` 的文件。学习其基本语法：定义 `package`，使用 `message` 关键字定义数据结构（如Person），并在其中声明字段（如 `string name = 1;`）。理解字段编号的唯一性和重要性。

💡字段编号1-15占用更少的字节，因此将频繁使用的字段分配在这个范围内。

编译.proto文件生成C++代码

在终端中，使用protoc编译器编译你的 `.proto` 文件：`protoc --cpp_out=. person.proto`。这将生成 `person.pb.h` 和 `person.pb.cc` 两个文件。

💡`--cpp_out=.` 指定了输出C++代码到当前目录。确保protoc能在命令行中找到。

编写第一个序列化/反序列化程序

创建一个简单的C++程序（如 `main.cpp`）。在程序中包含生成的头文件，使用生成的Person类设置数据（如set_name），调用 `SerializeToString` 方法将对象序列化为二进制字符串，再使用 `ParseFromString` 方法从字符串反序列化回对象，并打印验证。

💡编译你的C++程序时，记得链接protobuf库（如 `-lprotobuf`）。从官方示例或教程中复制一个最简单的程序开始。

编译并运行你的程序

使用C++编译器（如g++）编译你的程序：`g++ -std=c++11 main.cpp person.pb.cc -lprotobuf -o person_test`，然后运行生成的可执行文件 `./person_test`，观察输出。

💡如果遇到链接错误，请检查protobuf库是否正确安装以及链接器标志。

深入理解与练习

⏱ 60-90分钟

探索更多字段类型

在你的.proto文件中尝试添加不同类型的字段：数字类型（int32, double）、布尔型、枚举（enum）、嵌套消息（message）以及重复字段（repeated）。重新编译并测试。

💡阅读官方语言指南中关于“标量类型”的表格，了解所有可用的数据类型。

理解版本兼容性

学习protobuf的核心规则：不要更改现有字段的编号。你可以添加新字段（使用新的编号），旧字段可以标记为 `reserved` 以防止误用。修改.proto文件，体验向前/向后兼容。

💡这是protobuf在微服务中广泛使用的关键优势，务必理解。

⚠️ Common Mistakes

❌ protoc编译器版本与运行时库版本不匹配

✅ 始终确保使用相同的主要版本号。使用包管理器安装时，它们通常会保持同步。手动安装时需特别注意。

❌ 忘记将生成的.pb.cc文件加入编译，或忘记链接protobuf库（-lprotobuf）

✅ 编译命令需要包含所有源文件（.cpp和.pb.cc）并正确指定链接库。使用构建工具（如CMake）可以更好地管理依赖。

❌ 在.proto文件中修改或重用已存在的字段编号

✅ 字段编号一旦分配，在消息的整个生命周期内不应更改。删除字段时，应将其编号加入 `reserved` 列表，以防未来被意外重用。

❌ 直接使用GitHub主分支（main）的代码进行生产开发

✅ 如README所述，主分支可能不稳定。生产环境应使用官方发布的稳定版本（从Release页面获取）。

🚀 Next Steps

1. 学习如何将protobuf与gRPC结合使用，构建完整的RPC服务。2. 探索其他语言（如Go、Python）的protobuf支持，实现跨语言数据交换。3. 阅读高级主题，如Any、Oneof、Map字段类型，以及插件开发（扩展protoc）。4. 在实际项目（如微服务通信、配置文件存储）中应用protobuf。