Protocol Buffers 数据序列化

它是什么

Protocol Buffers，简称 protobuf，是 Google 做的一种与语言和平台无关、可扩展的结构化数据序列化方式。你只需在一个 .proto 文件里描述一次数据。编译器 protoc 把这个文件变成你所用语言的代码，该语言的运行时库再负责写入和读取数据。这个条目提供 protoc 和主仓库里各语言运行时的安装说明，Go、Dart 和 JavaScript 则指向它们各自的仓库。

1. 你在 .proto 文件里描述数据
2. protoc 把它变成你所用语言的代码
3. 你的程序把消息序列化成字节
4. 另一种语言写的程序解析这些字节
5. 数据新增字段后，旧代码照常读取

适合谁

在服务之间传递结构化数据，或者把数据存进文件，又想要类型化的模式、紧凑的消息和自动生成的代码的开发者。混用多种语言的团队也合适，比如一个 Java 服务和一个 Python 任务共用同一个 .proto 文件。概览页说，protobuf 最常见的用途是和 gRPC 一起定义通信协议，以及存储数据。如果单条消息超过几兆字节，或者要让人不看 .proto 文件就读懂数据，就不要用它。

用在哪里

protoc 可以装在 Linux、macOS 和 Windows 上，运行时覆盖下面这些语言。安装说明涵盖这些，Go、Dart 和 JavaScript 则指向它们各自的仓库。

• protoc：适用于任何系统的发布版 zip，或者 apt、Homebrew、winget
• Python：pip install protobuf
• Java 和 Kotlin：Maven，安卓上用 Lite 运行时
• C#：Google.Protobuf 和 Google.Protobuf.Tools 两个 NuGet 包
• Ruby 和 PHP：google-protobuf gem、Composer 和 PECL
• C++：用 Bazel 或 CMake 构建，Windows 上也可以用 vcpkg
• Objective-C：把运行时源码加进你的项目
• Go、Dart 和 JavaScript：README 指向它们各自的仓库

如何设置

点“获取”会把一个装有 Mindket 安装说明的 zip 压缩包存进你的下载文件夹，主仓库文档里的每种运行时各有一页，内容来自制作者的 README 和文档。先装 protoc，再装你所用语言的运行时。

1. 安装 protoc，可以用 GitHub 上的发布版 zip，也可以用包管理器。
2. 运行 protoc --version，并和版本支持页上你所用语言的受支持版本比对，因为包管理器里的 protoc 可能比较旧。
3. 安装你所用语言的运行时。
4. 写一个 .proto 文件，再用 protoc 处理它，生成代码。

apt install -y protobuf-compiler
protoc --version
pip install protobuf

前两行是安装页给出的 Linux 路线，第三行安装 Python 运行时。在 Mac 上安装页给的是 brew install protobuf，在 Windows 上是 winget install protobuf，后面各跟一句 protoc --version。没有包管理器的话，从发布页下载适合你系统的 zip，解压到 $HOME/.local 下，再把放着 protoc 的文件夹加进 PATH。安装说明里写了每一条命令。

如何使用

把数据的结构写在一个 .proto 文件里，编译它，再使用生成的类。下面是概览页里的示例消息。

edition = "2023";

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

这里的数字是标签。每个字段在二进制编码里都带着自己的标签，Python 教程说 1 到 15 的标签比更大的编号少占一个字节。用教程里的那一行为 Python 编译，它写明了源目录、目标目录和 .proto 路径。

protoc --proto_path=$SRC_DIR --python_out=$DST_DIR $SRC_DIR/addressbook.proto

这会在目标文件夹里写出 addressbook_pb2.py。教程接着用 SerializeToString() 写出一条消息，用 ParseFromString(data) 读入一条消息。其他语言换一个选项就行：--java_out、--kotlin_out、--csharp_out、--ruby_out 和 --php_out 是各个 README 提到的几个。

示例

你想要一个能被两种语言读取的文件。examples README 为每种语言做了一个通讯录程序，并说可以用 add_person_java 创建通讯录，再用 list_people_python 读取。

export CLASSPATH=/path/to/protobuf-java-[version].jar
make java
make python

先用 add_person_java 加一个文件名来创建通讯录，再用 list_people_python 加同一个文件名来读取。README 给 C++ 的写法是 ./add_person_cpp addressbook.data，并说 Python 脚本的用法一样。最后得到一个数据文件，两种语言的程序共用。

新手与专家

新手：可以把 .proto 文件想成你数据的一张带类型的表格。protoc 读它，写出一些类，每个字段有一个取值方法和一个设置方法，还有把整条消息变成字节、再变回来的方法。概览页说 Protobuf 像 JSON，只是更小更快。教程假定你对它一无所知，只要求你会用自己的语言写代码和处理文件。教程页有 C++、C#、Dart、Go、Java、Kotlin 和 Python 的版本。

专家：概览页说，删掉的字段，它的编号绝不能再用，所以要把它保留下来。只要你遵守 protobuf.dev 上的更新做法，旧代码读新消息时会忽略新增的字段，新代码读旧消息时，缺少的字段取默认值。同样的数据可以序列化成许多不同的字节串，所以不先解析，就没法比较两条消息是否相等。

Python 有三个后端，API 相同。upb 后端是默认的，随 PyPI 包一起发布，cpp 已弃用，不再在 PyPI 发布，python 是纯 Python 后端。设置 PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION 来选一个，运行下面这段代码就能看到你用的是哪个。README 说它不是官方支持的稳定 API，但对临时诊断有用。

from google.protobuf.internal import api_implementation
print(api_implementation.Type())

从源码构建要小心。README 说，main 分支头部的构建时不时会坏，就连发布分支在两次发布提交之间也可能不稳定，所以要固定到某个发布提交。C++ README 警告说，C++ 运行时的两个版本不太可能 ABI 兼容，所以升级后要重新编译，或者静态链接。

注意事项

安装步骤都是普通的装包和构建步骤，其中有几步会连网。

• 许可证：BSD 风格的文本，有三个条件。LICENSE 文件写的是“Copyright 2008 Google Inc. All rights reserved.”，GitHub 把它列为 Other。结尾一段说，编译器生成的代码归输入文件的所有者所有，并且要链接一个支持库，该库适用同一个许可证
• 网络：protobuf.dev 上的发布版 zip 命令会访问 api.github.com，并从 GitHub 下载。CMake 构建在没装 Abseil、Google Test 和 jsoncpp 时，会从 GitHub 获取它们。用 git 克隆仓库会从 GitHub 下载，Bazel WORKSPACE 路线里的 http_archive 会从它的 url 下载，go install 会获取 Go 插件。包管理器会访问各自的注册表
• 版本：预编译的二进制文件只有已发布的版本才有。要用 main 的最新代码，就得自己构建 protoc，旧版本 README 指向 Maven 仓库
• 适用范围：概览页说 protobuf 不是任何组织的正式标准，所以在法律或其他要求必须基于标准的环境里不适合用。它不压缩消息，用在带大型浮点数组的科学计算上也不太合适
• 支持：Google 在 2008 年把它开源。概览页说它接受部分拉取请求，但不一定优先处理不符合它自身需求的请求
• 说明：这些安装说明是 Mindket 写的，Google 没有做过，也没有认可
• 移除：README 没有给出卸载步骤。用你安装每个部分时用的工具移除它，或者删掉解压出来的发布文件和 PATH 里的那一行