Protobuf

自动关联目录:Protobuf

Protobuf 的核心设计是用字段编号代替字段名。字节流里只有编号,没有键名——这一条同时解决了体积、解析速度和版本兼容三个问题。

message PlayerState {
    int32  level   = 1;
    int64  exp     = 2;
    string name    = 3;
    repeated int32 buffs = 4;
}

编码要点

机制说明
varint小数字用更少字节(每个字节最高位是"还有后续"标志)
ZigZagsint32/sint64 用,让负数也变短
Tag-Length-Value / Tag-Value头部是 `(字段号 << 3)
字段可缺省没写的字段不出现在字节流里

推论:

  • 字段号 1–15 的 tag 只占 1 字节,常用字段应该用这些号
  • repeated 的标量用 packed=true 能显著减小体积
  • 负数用 int32 会被编码成 10 字节,负数多的字段用 sint32

版本兼容规则

操作是否安全
新增字段(用新编号)安全
删除字段(保留编号不用)安全,但要用 reserved 占位
改字段名安全(字节流里本来就没有名字)
改字段类型(兼容类型内)部分安全,见下
复用已删除的编号危险,旧数据会被错误解析
改字段编号破坏兼容
message PlayerState {
    reserved 5, 8 to 10;   // 曾经用过,永远别再分配
    reserved "old_hp";
}

兼容的类型替换:int32 ↔ int64 ↔ uint32(varint 家族内部)、string ↔ bytes。int32 与 enum 也互通,但语义上不建议。

默认值与"是否设置"

proto3 里标量没有 hasXXX():默认值(0 / "" / false)不会被序列化,所以"设为 0"和"没设置"在字节流里无法区分。

需求做法
区分"没设置"和"设了默认值"用 optional(proto3 支持)或包装类型 google.protobuf.Int32Value
强制写出默认值一般用不到,靠接收端默认值即可
需要真正的"空"语义用 oneof 或单独的 bool 标志

常见坑

坑说明
复用字段编号最危险的一类错误,旧存档/旧客户端会读出脏数据
用 float/double 做精确值跨端一致性与精度问题,用整数
把 map 当有序结构Protobuf 的 map 顺序不保证
超大 message单个 message 建议控制在 MB 级以内,超了要分包
忽视 unknown fields旧版本收到新字段时应保留并回传,否则会丢数据
用 Json 序列化 Protobuf 做协议失去了体积与速度优势,只在调试时用

与 Json 的配合

Protobuf 自带 Json 映射(MessageToJsonString),适合:

  • 日志与调试:把二进制协议打成文本看
  • 对外接口:一份 schema,两种编码

注意数字在 Json 里会变成 int64 → string(避免精度丢失),跨端约定时要留意。

选型小结

场景选谁
配置、人读人改Json
网络协议、存档、大数据Protobuf
引擎内、跟随 USTRUCTUE 自带序列化
极高吞吐、零拷贝FlatBuffers / Cap'n Proto