Protocol Buffers

protobuf / pb

Protocol Buffers 是 Google 开源的跨语言数据序列化格式和接口定义语言（IDL）。通过 .proto 文件定义数据结构，编译生成多语言代码。

基础概念

基本语法

最小示例

syntax = "proto3";

package user.v1;

message User {
  string id = 1;
  string name = 2;
  string email = 3;
  int32 age = 4;
}

• syntax = "proto3"; 必须第一行（或仅次于注释）
• package 生成目标语言的命名空间
• 每个字段 类型 字段名 = 编号;

标量类型

嵌套与枚举

message Order {
  string id = 1;
  OrderStatus status = 2;
  repeated Item items = 3;
  Address shipping_address = 4;

  message Item {
    string sku = 1;
    int32 quantity = 2;
  }
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_PAID = 2;
  ORDER_STATUS_SHIPPED = 3;
}

message Address {
  string line1 = 1;
  string city = 2;
  string country = 3;
}

• repeated 表示数组
• 嵌套 message 作为内部类型
• enum 的 0 值必须是 UNSPECIFIED（proto3 规定）

字段编号规则

字段编号是 protobuf 的核心机制，决定了向前/向后兼容：

message User {
  reserved 4, 7 to 9;
  reserved "age", "old_email";

  string id = 1;
  string name = 2;
  string email = 3;
  // 5、6 可以用
  // 4、7、8、9 永远不能再用
}

默认值

proto3 没有 required，所有字段都是可选的；未设置的字段使用类型零值：

message Update {
  optional int32 count = 1;  // 可以区分 unset / 0
}

兼容性规则

protobuf 的关键卖点是向前/向后兼容。遵守规则：

安全的变更

• ✅ 新增字段（用新编号）
• ✅ 删除字段（改用 reserved）
• ✅ 重命名字段（编号不变即可，但会影响 JSON 字段名）
• ✅ singular ↔ repeated（接收端自动处理）

破坏性变更

• ❌ 修改字段编号（全局数据错乱）
• ❌ 修改字段类型（仅少数 wire 类型兼容组安全：int32/int64/uint32/uint64/bool/enum 之间可互转，但大数值从 int64 改回 int32 会截断溢出；sint32/sint64 自成一组不兼容前者）
• ❌ 重用已删除字段的编号

service 定义

对 gRPC 来说，service 声明了 RPC 服务接口：

service UserService {
  rpc GetUser(GetUserRequest) returns (User);
  rpc ListUsers(ListUsersRequest) returns (stream User);
  rpc UpdateUser(stream UpdateUserRequest) returns (User);
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

• stream 关键字标记流式（详见 gRPC 四种通信模式）
• 每个方法必须有输入和输出消息类型，不能直接返回标量

序列化格式（二进制布局）

每个字段在 wire 格式中是 (tag << 3) | wire_type + value。核心认识：

关键特性：

• 未设置的字段完全不出现在 wire 格式里，这就是为什么默认值没有开销
• 未知字段（新版本加的）会被旧版本保留并透传，保证转发类服务的兼容

工具链

与 JSON 的对比

使用建议：

• 服务间内部通信、高频数据传输 → protobuf
• 前后端通信（浏览器）、调试友好 → JSON
• 消息队列、持久化 → protobuf（如果上下游都能用）