2、Protocol Buffers入门：proto3语法基础、定义消息类型、标量类型与枚举、字段编号规则

好，咱们正式开始聊 Protocol Buffers。说实话，我当年刚接触 gRPC 时，第一反应是：这不就是个序列化工具吗？后来踩了几个坑才明白，ProtoBuf 是整个 gRPC 通信的基石。你定义的数据结构好不好，直接决定了后续的服务能不能优雅地演进。

2.1 proto3 语法基础

先说说版本。现在主流用的是 proto3，相比 proto2 它砍掉了一些复杂特性（比如 required/optional 的严格区分），换来的是更简洁的语法和更好的跨语言兼容性。我个人习惯，新项目一律用 proto3。

一个最基本的 .proto 文件长这样：

syntax = "proto3";

package user;

option go_package = ".;userpb";

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

注意第一行 syntax = "proto3";，这行必须写，而且必须放在文件第一行。不写的话，编译器默认按 proto2 解析——嗯，这个坑我见过不少新手踩过。

package 关键字用来避免命名冲突，类似 Go 里的包名。而 option go_package 是给 Go 编译器看的，指定生成的 .pb.go 文件属于哪个包。我建议你养成习惯，每次写 proto 文件都显式声明 go_package，否则默认行为会让你很头疼。

小技巧：go_package 的写法有两种：一种是完整路径（如 "github.com/xxx/proto/userpb"），另一种是只写包名（如 ".;userpb"）。我更喜欢后者，简单直接，适合单体项目。

2.2 定义消息类型

消息类型（Message）是 ProtoBuf 的核心概念。说白了，它就是你要传输的数据结构。每个消息由若干个字段组成，每个字段有名字、类型和编号。

看个复杂点的例子：

message Order {
  string order_id = 1;
  int64 user_id = 2;
  repeated string items = 3;
  float total_price = 4;
  Status status = 5;
  map<string, string> extra = 6;
}

enum Status {
  STATUS_UNKNOWN = 0;
  STATUS_PENDING = 1;
  STATUS_SHIPPED = 2;
  STATUS_DONE = 3;
}

这里有几个要点：

  • repeated 关键字表示数组/列表。在 Go 里会生成 slice。
  • map 关键字表示键值对。注意 key 的类型只能是标量类型。
  • 枚举 可以嵌套在消息内部，也可以单独定义。
  • 字段顺序不重要，但编号很重要——这个我们马上讲。

我在项目中遇到过一个问题：有个同事把 repeated 字段写成了普通字段，结果客户端收到的数据永远只有最后一条。排查了半天才发现是类型定义错了。所以，集合类型一定要用 repeated，别偷懒。

2.3 标量类型与枚举

ProtoBuf 的标量类型和 Go 类型有个对应关系，我整理了一张表，你直接收藏就行：

ProtoBuf 类型 Go 类型 说明
double float64 64位浮点
float float32 32位浮点
int32 int32 变长编码，负数效率低
int64 int64 变长编码
uint32 uint32 无符号变长编码
uint64 uint64 无符号变长编码
sint32 int32 负数效率高，适合有符号数
sint64 int64 负数效率高
fixed32 uint32 固定4字节，编码快
fixed64 uint64 固定8字节
sfixed32 int32 固定4字节，有符号
sfixed64 int64 固定8字节，有符号
bool bool 布尔值
string string UTF-8 字符串
bytes []byte 任意字节序列

这里有个容易忽略的点：int32 和 sint32 的区别。如果你要传输负数，用 sint32 更省空间。为什么？因为 int32 用变长编码时，负数会被当成很大的无符号数，占用 10 个字节。而 sint32 用了 ZigZag 编码，负数也能压缩到很小的空间。我当年做支付系统时，传输金额差值（可能为负），一开始用了 int32，结果发现序列化后的数据比预期大了一倍。换成 sint32 后，体积直接减半。

枚举的定义也很简单：

enum Color {
  COLOR_UNSPECIFIED = 0;
  COLOR_RED = 1;
  COLOR_GREEN = 2;
  COLOR_BLUE = 3;
}

注意：枚举的第一个值必须为 0。这是 proto3 的硬性要求，用来作为默认值。我建议你给第一个值起名叫 XXX_UNSPECIFIED 或 XXX_UNKNOWN，语义更清晰。

警告：枚举值不能重复，且不能使用负数。如果你删除了某个枚举值，记得用 reserved 关键字标记，防止别人误用。比如：reserved 2, 3;。

2.4 字段编号规则

这是 ProtoBuf 里最容易被忽视、但坑最多的地方。每个字段都有一个唯一的数字编号，这个编号一旦确定，尽量不要修改。

编号的范围是 1 到 2^29-1（约 5.3 亿），但实际使用时有讲究：

  • 1 ~ 15：占用 1 个字节的编码空间。高频字段放这里。
  • 16 ~ 2047：占用 2 个字节。次高频字段。
  • 2048 以上：占用更多字节。低频字段或未来扩展用。

为什么会这样？因为 ProtoBuf 的编码机制里，字段编号和类型会一起编码成 tag。编号越小，tag 占用的字节越少。你想想看，如果一个消息里频繁传输的字段编号是 1，那每次序列化都能省下几个字节。微服务调用量大的时候，积少成多，效果很明显。

我曾经维护过一个老项目，里面有个消息定义了 30 多个字段，编号从 1 到 30 随便排的。后来做性能优化时，我把最常用的 5 个字段挪到了 1~5，序列化体积直接降了 12%。虽然改动不大，但效果立竿见影。

关于编号，还有几个铁律：

  • 编号不能重复。同一个消息里，每个字段的编号必须唯一。
  • 编号不能修改。如果你要废弃一个字段，用 reserved 保留编号，防止未来复用。
  • 19000 ~ 19999 是保留编号，Protocol Buffers 内部使用，你不能用。
  • 不要用 0。编号从 1 开始。

看个正确示范：

message Product {
  reserved 2, 5, 10 to 15;  // 这些编号已被废弃，不可再用

  string product_id = 1;     // 高频字段
  string name = 3;           // 高频字段
  double price = 4;          // 中频字段
  int64 stock = 6;           // 低频字段
  // ... 其他字段
}
核心原则：字段编号是 ProtoBuf 的「契约」的一部分。一旦上线，就不能随便改。如果你要新增字段，用新的编号；如果要删除字段，用 reserved 占住编号。这样才能保证前后兼容。

2.5 小结

嗯，这一章的内容其实不难，但都是基本功。我见过太多人因为 proto 文件定义得乱七八糟，导致后续服务升级时叫苦连天。记住三点：

  1. 语法要规范：syntax、package、go_package 一个都不能少。
  2. 类型要选对：负数用 sint32，高频字段用 1~15 编号。
  3. 编号要珍惜：一旦定下来，就别乱动。用 reserved 保护已废弃的编号。

下一章我们开始写真正的 .proto 文件，然后生成 Go 代码。到时候你会看到，这些基础概念是怎么落地的。

← 上一章 📖 返回目录 下一章 →