配图清新的Protobuf 编码&避坑指南

我们现在所有的协议、配置、数据库的表达都是以 protobuf 来进行承载的，所以我想深入总结一下 protobuf 这个协议，以免踩坑。

先简单介绍一下 Protocol Buffers（protobuf），它是Google开发的一种数据序列化协议（与XML、JSON类似）。它具有很多优点，但也有一些需要注意的缺点：

优点：

1. 效率高：Protobuf以二进制格式存储数据，比如XML和JSON等文本格式更紧凑，也更快。序列化和反序列化的速度也很快。
2. 跨语言支持：Protobuf支持多种编程语言，包括C++、Java、Python等。
3. 清晰的结构定义：使用protobuf，可以清晰地定义数据的结构，这有助于维护和理解。
4. 向后兼容性：你可以添加或者删除字段，而不会破坏老的应用程序。这对于长期的项目来说是非常有价值的。

缺点：

1. 不直观：由于protobuf是二进制格式，人不能直接阅读和修改它。这对于调试和测试来说可能会有些困难。
2. 缺乏一些数据类型：例如没有内建的日期、时间类型，对于这些类型的数据，需要手动转换成可以支持的类型，如string或int。
3. 需要额外的编译步骤：你需要先定义数据结构，然后使用protobuf的编译器将其编译成目标语言的代码，这是一个额外的步骤，可能会影响开发流程。

总的来说，Protobuf是一个强大而高效的数据序列化工具，我们一方面看重它的性能以及兼容性，除此之外就是它强制要求清晰的定义出来，以文件的形式呈现出来方便我们维护管理。下面我们主要看它的编码原理，以及在使用上有什么需要注意的地方。

编码原理

概述

对于 protobuf 它的编码是很紧凑的，我们先看一下 message 的结构，举一个简单的例子：

message Student {
  string name = 1;
  int32 age = 2; 
}

message 是一系列键值对，编码过之后实际上只有 tag 序列号和对应的值，这一点相比我们熟悉的 json 很不一样，所以对于 protobuf 来说没有 .proto 文件是无法解出来的：

对于 tag 来说，它保存了message 字段的编号以及类型信息，我们可以做个实验，把 name 这个tag编码后的二进制打印出来：

func main() {
 student := student.Student{}
 student.Name = "t" 
 marshal, _ := proto.Marshal(&student)
 fmt.Println(fmt.Sprintf("%08b", marshal)) // 00001010 00000001 01110100
}

打印出来的结果是这样：

上图中，由于 name 是 string 类型，所以第一个 byte 是tag，第二 byte 是 string 的长度，第三个 byte 是值，也就是我们上面设置的 “t”。我们下面先看看 tag：

tag 里面会包含两部分信息：字段序号，字段类型，计算方式就是上图的公式。上图中将 name 这个字段序列化成二进制我们可以看到，第一个 bit 是标记位，表示是否字段结尾，这里是0表示tag 已结尾，tag 占用1byte；接下来 4 个 bit 表示的是字段序号，所以范围 1 到 15 中的字段编号只需要 1 bit进行编码，我们可以做个实验看看，将tag 改成16：

由上图所示，每个byte 第一个bit表示是否结束，0表示结束，所以上面 tag 用两个 byte 表示，并且protobuf 是小端编码的，需要转成大端方便阅读，所以我们可以知道 tag 去掉每个 byte 第一个 bit 之后，后三位表示类型，是3，其余位是编号表示 16。

所以从上面编码规则我们也可以知道，字段尽可能精简一些，字段尽量不要超过 16 个，这样就可以用一个byte表示了。

同时我们也可以知道，protobuf 序列化是不带字段名的，所以如果客户端的 proto 文件只修改了字段名，请求服务端是安全的，服务端继续用根据序列编号还是解出来原来的字段。但是需要注意的是不要修改字段类型。

接下来我们看看类型，protobuf 共定义了 6 种类型，其中两种是废弃的：

上面的例子中，Name 是 string 类型所以上面 tag 类型解出来是 010 ，也就是 2。

Varints 编码

对于 protobuf 来说对数字类型做了压缩的，普通情况下一个 int32 类型需要 4 byte，而 protobuf 表示127以内的数字只需要 2 byte。因为对于一个普通 int32 类型数字，如果数字很小，那么实际上有效位很少，比如要表示 1 这个数字，二进制可能是这样：

00000000 00000000 00000000 00000001

前 3 个字节都是 0 没有表示任何信息，protobuf 就是将这些 0 都去除了，用 1 byte 表示 1 这个数字，再用 1 byte 表示 tag 的编号和类型，所以占用了 2byte。

比如我们对上面 student 设置 age 等于 150：

func main() {
 student := student.Student{}
 student.Age = 150
 marshal, _ := proto.Marshal(&student)
 fmt.Println(fmt.Sprintf("%08b", marshal)) //00010000 10010110 00000001
 fmt.Println(fmt.Sprintf("%08b", "a"))
}

上面打印出来的二进制如下，因为 150 超过 127，所以需要用两个 byte 表示：

第一个 byte 是 tag 这里就不再重复介绍了。后面两个 byte 是真实的值，每个 byte 的最高位 bit 是标记位，表示是否结束。然后我们转换成大端表示，串联起来就可以得到它的值是 150。

ZigZag 编码

Varints 编码之所以可缩短数字所占的存储字节数是因为去掉了 0 ，但是对于负数来说就不行了，因为负数的符号位为 1，并且对于32 位的有符号数都会转换成 64 位无符号来处理，例如 -1，用 Varints 编码之后的二进制：

所以 Varints 编码负数总共会恒定占用 11 byte，tag 一个byte，值占用 10 byte。

为此 Google Protocol Buffer 定义了 sint32 这种类型，采用 zigzag 编码。将所有整数映射成无符号整数，然后再采用 varint 编码方式编码。例如：

参照上面的表，也就是将 -1 编码成 1，将 1 编码成 2，全部都做映射，实际的 Zigzag 映射函数为：

(n << 1) ^ (n >> 31)  //for 32 bit 
(n << 1) ^ (n >> 63)  //for 64 bit

对于使用来说，只是编码方式变了，使用是不受影响，所以对于如果有很高比例负数的数据，可以尝试使用 sint 类型，节省一些空间。

embedded messages & repeated

比如现在定义这样的 proto：

message Lecture {
  int32 price =1 ; 
}

message Student {
  repeated int32 scores = 1;
  Lecture lecture = 2;
}

给 scores 取值为 [1,2,3]，编码之后发现其实和上面讲的 string 类型很像。第一个 byte 是 tag；第二 byte 是 len，长度为 3；后面三个byte 都是值，我们设定的 1，2，3。

再来看看 embedded messages 类型，让 Lecture 的 price 设置为150 好了，编码之后是这样：

其实结构也很简单，左边的是 Student 类型，右边是 Lecture 类型。有点不同的是对于 embedded messages 会将大小计算出来。

最佳实践

字段编号

需要注意的是范围 1 到 15 中的字段编号需要一个字节进行编码，包括字段编号和字段类型；范围 16 至 2047 中的字段编号需要两个字节。所以你应该保留数字 1 到 15 作为非常频繁出现的消息元素。

因为使用了 VarInts，所以单字节的最高位是零，而最低三位表示类型，所以只剩下 4 位可用了。也就是说，当你的字段数量超过 16 时，就需要用两个以上的字节表示了。

保留字段

一般的情况下，我们是不会轻易的删除字段的，防止客户端和服务端出现协议不一致的情况，如果您通过完全删除某个字段或将其注释掉来更新消息类型，那么未来的其他人不知道这个 tag 或字段被删除过了，我们可以使用 reserved 来标记被删除的字段，如：

message Foo {
  reserved 2, 15, 9 to 11;
  reserved "foo", "bar";
}

当然除了 message ，reserved也可以在枚举类型中使用。

不要修改字段 tag 编号以及字段类型

protobuf 序列化是不带字段名的，所以如果客户端的 proto 文件只修改了字段名，请求服务端是安全的，服务端继续用根据序列编号还是解出来原来的字段，但是需要注意的是不要修改字段类型，以及序列编号，修改了之后就可能按照编号找错类型。

不要使用 required 关键字

required 意味着消息中必须包含这个字段，并且字段的值必须被设置。如果在序列化或者反序列化的过程中，该字段没有被设置，那么protobuf库就会抛出一个错误。

如果你在初期定义了一个 required 字段，但是在后来的版本中你想要删除它，那么这就会造成问题，因为旧的代码会期待该字段始终存在。为了确保兼容性，Google在最新版本的 protobuf（protobuf 3）中已经不再支持 required 修饰符。

尽量使用小整数

Varints 编码表示127以内的数字只需要 2 byte，1 byte 是 tag，1 byte 是值，压缩效果很好。但是如果表示一个很大的数如 ：1<<31 - 1，除去 tag 外需要占用 5 byte，比普通的 int 32 多1 byte，因为 protobuf 每个byte最高位有一个标识符占用 1 bit。

如果需要传输负数，可以试试 sint32 或 sint64

因为负数的符号位为 1，并且Varints 编码对于负数如果是32 位的有符号数都会转换成 64 位无符号来处理，所以 Varints 编码负数总共会恒定占用 11 byte，tag 一个byte，值占用 10 byte。

而 sint32  和 sint64 将所有整数映射成无符号整数，然后再采用 varint 编码方式编码，如果数字比较还是可以节省一定的空间的。

Reference

https://sunyunqiang.com/blog/protobuf_encode/

https://halfrost.com/protobuf_encode/

https://protobuf.dev/programming-guides/encoding/

https://protobuf.dev/programming-guides/dos-donts/