2. Protobuf 语法入门：message 定义、字段类型与编号、repeated 与 map、enum 枚举、import 与 package、option 选项

Protocol Buffers（Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。掌握 Protobuf 语法是编写 gRPC 服务的第一步。本章从最核心的 message 定义出发，系统讲解字段类型、编号规则、集合类型、枚举、模块组织与编译选项，为后续的 Go 代码生成与压测脚本编写打下坚实基础。

2.1 message 定义与字段编号

Protobuf 的核心数据单元是 message。每个 message 定义了一组字段，每个字段由 类型、字段名 和 唯一的字段编号 组成。

syntax = "proto3";

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

字段编号（Field Number） 是 Protobuf 二进制序列化的关键标识，而非字段名。编号范围与使用建议如下：

message User {
  reserved 4, 5, 10 to 15;  // 保留编号
  reserved "phone", "address";  // 保留字段名（可选）
  string name = 1;
  int32 age = 2;
  string email = 3;
}

2.2 字段类型体系

Protobuf 提供了一套跨语言的标量类型，每种类型映射到 Go 语言的具体类型。下表列出最常用的类型对应关系：

2.3 repeated 与 map：集合类型

Protobuf 提供两种内置集合类型：repeated（列表）和 map（字典）。

2.3.1 repeated 字段

repeated 表示一个字段可以包含零个或多个相同类型的元素，在 Go 中生成 []T 切片。

message Order {
  string order_id = 1;
  repeated string item_names = 2;   // 字符串列表
  repeated double prices = 3;       // 浮点数列表
}

在 proto3 中，repeated 字段默认使用 packed 编码，即所有元素连续排列，减少编码开销。对于标量类型（int32、uint64、float 等），packed 编码是自动启用的。

2.3.2 map 字段

map<K, V> 定义键值对映射，在 Go 中生成 map[K]V。键类型必须是标量或 string，值类型可以是任意 message 或标量。

message Product {
  string product_id = 1;
  map<string, double> price_by_region = 2;  // 区域 -> 价格
  map<string, string> attributes = 3;       // 属性键值对
}

// 替代方案：有序键值对列表
message KeyValue {
  string key = 1;
  string value = 2;
}
message Config {
  repeated KeyValue entries = 1;
}

2.4 enum 枚举

枚举用于定义一组预定义的常量值，在 Go 中生成对应的常量类型。

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;  // 必须存在，proto3 要求
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_CONFIRMED = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_DELIVERED = 4;
  ORDER_STATUS_CANCELLED = 5;
}

message Order {
  string order_id = 1;
  OrderStatus status = 2;
}

枚举规则：

• proto3 中枚举的第一个值必须为 0，作为默认值。
• 枚举值编号必须在 0 到 2^31-1 之间。
• 建议使用 ENUM_NAME_UNSPECIFIED = 0 的命名风格，明确表示未指定状态。
• 枚举可以定义在 message 内部或文件顶层。

2.5 import 与 package：模块化组织

随着项目规模增长，需要将 .proto 文件拆分到不同包和目录中。package 和 import 提供了模块化能力。

2.5.1 package 声明

package 用于避免不同 .proto 文件中的类型命名冲突。在 Go 中，package 会映射为 Go 包路径的一部分。

// file: proto/order/v1/order.proto
syntax = "proto3";
package order.v1;

message Order {
  string order_id = 1;
}

2.5.2 import 引用

使用 import 引入其他 .proto 文件中定义的类型。路径相对于 protoc 的 -I 或 --proto_path 参数。

// file: proto/payment/v1/payment.proto
syntax = "proto3";
package payment.v1;

import "order/v1/order.proto";  // 相对路径

message Payment {
  string payment_id = 1;
  order.v1.Order order = 2;     // 使用包名限定
  double amount = 3;
}

2.6 option 选项：控制代码生成行为

option 用于向 protoc 编译器传递元信息，影响代码生成、序列化行为或 gRPC 服务定义。最常用的选项如下：

一个完整的 .proto 文件示例，整合了本章所有语法元素：

syntax = "proto3";
package order.v1;

option go_package = "github.com/myproject/gen/order/v1;orderv1";

import "common/v1/types.proto";

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_CONFIRMED = 2;
}

message LineItem {
  string sku = 1;
  int32 quantity = 2;
  double unit_price = 3;
  map<string, string> custom_attrs = 4;
}

message Order {
  string order_id = 1;
  OrderStatus status = 2;
  repeated LineItem items = 3;
  common.v1.Address shipping_address = 4;
  double total_amount = 5;
}

2.7 本章小结

本章覆盖了 Protobuf 语法的核心要素，这些知识将直接应用于后续的 gRPC 服务定义与压测数据构造：

• message 与字段编号：编号是序列化的唯一标识，1-15 号字段应留给高频数据。
• 字段类型：标量类型映射到 Go 原生类型，选择合适类型可优化序列化效率。
• repeated 与 map：分别对应切片和字典，注意 map 的无序性限制。
• enum 枚举：首值必须为 0，用于状态机或分类字段。
• import 与 package：模块化组织 .proto 文件，避免命名冲突。
• option 选项：控制代码生成路径与优化策略，Go 项目必须设置 go_package。