2. Protocol Buffers 入门：定义 .proto 文件、消息类型、字段规则与标量类型

Protocol Buffers（简称 Protobuf）是 gRPC 的接口定义语言（IDL）与序列化引擎。在编写任何 gRPC 服务之前，必须掌握如何编写 .proto 文件、定义消息结构、设置字段规则以及选择正确的标量类型。本章将系统性地拆解这些基础概念，为后续的服务定义与压测脚本编写打下坚实基础。

2.1 .proto 文件结构速览

一个标准的 .proto 文件由包声明、导入语句、选项配置以及若干消息（message）和服务（service）定义组成。以下是一个最小但完整的示例：

syntax = "proto3";                  // 指定语法版本，必须为第一行非注释内容

package order.v1;                   // 包名，用于避免命名冲突

option go_package = "order/v1;orderpb"; // 语言特定选项，此处为 Go 生成路径

// 定义订单消息
message Order {
  string order_id = 1;
  int32  quantity = 2;
  double unit_price = 3;
}

// 定义查询响应消息
message GetOrderResponse {
  Order order = 1;
  string error_message = 2;
}
版本选择：本课程统一使用 proto3 语法。proto3 移除了 required 字段、默认值语义更简洁，且支持更多语言。除非维护遗留系统，否则新项目应始终使用 proto3。

2.2 消息类型（Message Type）

消息是 Protobuf 中最基本的数据容器，类似于结构体（struct）或数据类（data class）。每个消息由一组字段组成，每个字段有唯一的编号（field number）和类型。消息可以嵌套，也可以引用其他消息作为字段类型。

概念 说明 示例
顶级消息 直接在文件级别定义 message Order { ... }
嵌套消息 在另一个消息内部定义 message Order { message Item { ... } }
引用外部消息 使用其他消息作为字段类型 Order order = 1;
Map 类型 键值对映射 map<string, string> attributes = 10;
Oneof 类型 一组字段中最多同时设置一个 oneof payment { string credit_card = 5; string crypto = 6; }

2.3 字段规则：required / optional / repeated

在 proto3 中，字段规则相比 proto2 做了大幅简化。理解这些规则对设计高效、兼容的 API 至关重要。

规则 proto3 支持 语义 典型使用场景
required ❌ 已移除 proto2 中表示字段必须设置；proto3 中所有标量字段默认有零值，不再区分“未设置”与“零值” 不应使用；改用服务端校验
optional ✅ 支持（显式语义） 字段可以存在或不存在；proto3 中通过 optional 关键字启用显式存在语义，可区分“未设置”与“零值” 需要区分空字符串与未传值时；需要向前兼容旧版 proto2 客户端时
repeated ✅ 支持 字段可以重复任意次数（包括 0 次），序列化为有序列表 列表、数组、集合；如订单中的商品列表
避坑提示：在 proto3 中，如果没有显式使用 optional，标量字段的默认值（如 0、空字符串、false）与“未设置”在序列化时无法区分。如果业务逻辑需要区分“用户未填写年龄”与“年龄为 0”，请使用 optional int32 age = 1; 或改用包装类型（google.protobuf.Int32Value）。

2.4 标量类型与默认值

Protobuf 提供了一套跨语言的标量类型映射。每个类型在 proto3 中都有明确的默认值（零值）。

.proto 类型 Go 类型 Java 类型 C++ 类型 默认值（proto3）
double float64 double double 0.0
float float32 float float 0.0
int32 int32 int int32 0
int64 int64 long int64 0
uint32 uint32 int uint32 0
uint64 uint64 long uint64 0
sint32 int32 int int32 0
sint64 int64 long int64 0
fixed32 uint32 int uint32 0
fixed64 uint64 long uint64 0
sfixed32 int32 int int32 0
sfixed64 int64 long int64 0
bool bool boolean bool false
string string String string ""（空字符串）
bytes []byte ByteString string 空字节序列
性能建议：对于可能为负数的整数，优先使用 sint32/sint64（ZigZag 编码），编码效率更高。对于固定大小的数值（如哈希值、时间戳高位），使用 fixed32/fixed64 可提升编解码速度。

2.5 字段编号（Field Number）与兼容性

每个字段必须有一个唯一的数字编号，用于二进制编码时的标识。编号范围与兼容性规则直接影响 API 演进能力。

  • 1 ~ 15：编码时占用 1 字节，应留给频繁出现的字段。
  • 16 ~ 2047：编码时占用 2 字节，适合不常出现的字段。
  • 19000 ~ 19999：保留编号，Protobuf 内部使用，不可手动分配。
  • 20000 ~ 2^29-1：可用于扩展，但建议保持有序。
兼容性黄金法则：永远不要更改已有字段的编号；永远不要复用已废弃的编号。添加新字段时使用新编号；移除字段时使用 reserved 关键字阻止未来误用。 
message Order {
  reserved 4, 8, 15;          // 保留编号，防止未来误用
  reserved "legacy_field";    // 保留字段名，防止 JSON 序列化冲突

  string order_id = 1;
  int32  quantity = 2;
  double unit_price = 3;
  // 编号 4 已被保留，不可使用
  string customer_note = 5;
}

2.6 消息定义流程：从需求到 .proto

下面通过一个完整的流程示例，展示如何将业务需求转化为结构清晰的 Protobuf 消息定义。

  1. 识别实体：确定核心业务对象，如 Order、Product、Customer。
  2. 列出属性：为每个实体列出所有属性及其数据类型。
  3. 分配编号：将频繁访问的属性放在 1~15 编号段。
  4. 选择规则：列表属性使用 repeated；需要区分未设置与零值的属性使用 optional。
  5. 添加元数据：定义请求/响应包装消息，包含业务状态码与错误信息。
  6. 预留兼容性：使用 reserved 标记已废弃的编号和字段名。
Protobuf 消息定义流程与字段规则决策树 Protobuf 消息定义流程与字段规则决策树 ① 识别业务实体 ② 列出属性与类型 ③ 分配字段编号 字段规则 决策 是列表？ repeated 需区分未设置？ optional 否则 默认（无规则） ④ 生成 .proto 文件

2.7 完整示例：订单服务消息定义

综合以上知识点，下面是一个面向实际压测场景的订单服务消息定义。该定义包含了嵌套消息、枚举、repeated 字段、optional 字段以及 map 类型。

syntax = "proto3";
package order.v1;

option go_package = "order/v1;orderpb";

// 订单状态枚举
enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_CONFIRMED = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_CANCELLED = 4;
}

// 订单商品项
message OrderItem {
  string product_id = 1;
  string product_name = 2;
  int32  quantity = 3;
  double unit_price = 4;
  optional string remark = 5;          // 可选备注，区分空字符串与未设置
}

// 订单主消息
message Order {
  string order_id = 1;
  string customer_id = 2;
  repeated OrderItem items = 3;        // 商品列表
  OrderStatus status = 4;
  double total_amount = 5;
  map<string, string> attributes = 6; // 扩展属性
  optional string coupon_code = 7;     // 优惠券码，可选
  int64 created_at = 8;                // Unix 时间戳
}

// 创建订单请求
message CreateOrderRequest {
  string customer_id = 1;
  repeated OrderItem items = 2;
  map<string, string> attributes = 3;
  optional string coupon_code = 4;
}

// 创建订单响应
message CreateOrderResponse {
  string order_id = 1;
  OrderStatus status = 2;
  string error_message = 3;            // 非空表示业务错误
}
压测视角：在后续的尾延迟压测中，Order 消息的大小和嵌套深度将直接影响序列化耗时与网络传输延迟。建议在压测脚本中构造不同大小的消息（如 1KB、10KB、100KB）来评估序列化开销对尾延迟的影响。

2.8 本章小结

  • .proto 文件是 gRPC 服务的唯一真相来源，必须严格遵循 proto3 语法。
  • 消息类型支持嵌套、引用、map 和 oneof，设计时应考虑 API 演进。
  • 字段规则：proto3 移除了 required；repeated 用于列表；optional 用于需要区分未设置的场景。
  • 标量类型有明确的跨语言映射和默认值，选择时需兼顾编码效率与业务语义。
  • 字段编号是兼容性的基石，1~15 留给高频字段，废弃编号必须使用 reserved。
← 上一章 📖 返回目录 下一章 →