3. Protobuf 语法入门：message 定义、字段类型与编号、enum 枚举、import 与 package、oneof 与 map

Protocol Buffers（Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。在编写任何 gRPC 服务之前，必须掌握 .proto 文件的核心语法。本章将围绕 message、字段规则、枚举、包管理、导入以及 oneof/map 等高级类型展开，为后续编写压测服务接口打下坚实基础。

3.1 message 定义与字段类型

message 是 Protobuf 中最基本的数据容器，类似于 Go 中的 struct。每个 message 由若干字段组成，每个字段包含：类型、字段名、字段编号。

syntax = "proto3";

message SearchRequest {
  string query = 1;
  int32  page_number = 2;
  int32  result_per_page = 3;
}

字段类型速查表：

3.2 字段编号：序列化的核心标识

每个字段必须分配一个唯一的数字编号，该编号在二进制编码中作为字段标识符，不是顺序索引。编号 1~15 使用 1 字节编码，16~2047 使用 2 字节编码。压测场景中，高频字段应分配小编号以降低序列化开销。

message Request {
  reserved 2, 15, 9 to 11;  // 保留编号，不可再使用
  reserved "old_field";      // 保留字段名

  string query = 1;
  int32  page  = 3;          // 编号 2 已被保留，跳过
}

3.3 enum 枚举：状态与类型定义

枚举用于定义一组预定义的常量值。在压测场景中，枚举常用于表示请求类型、状态码或错误分类。

enum RequestType {
  REQUEST_TYPE_UNSPECIFIED = 0;  // 必须存在零值
  REQUEST_TYPE_READ       = 1;
  REQUEST_TYPE_WRITE      = 2;
  REQUEST_TYPE_DELETE     = 3;
}

message EnumeratedRequest {
  string       request_id   = 1;
  RequestType  type         = 2;
}

枚举规则：

• 第一个枚举值必须为 0，用于默认值。
• 枚举值在 message 外部定义时，可在同一 package 内复用。
• 允许使用 enum_alias = true 选项为同一数值定义多个别名。

3.4 import 与 package：模块化管理

大型项目中，.proto 文件应按业务模块拆分，通过 import 相互引用。package 用于避免不同模块间的命名冲突。

// file: common/base.proto
syntax = "proto3";
package common;

message BaseResponse {
  int32  code    = 1;
  string message = 2;
}

// file: service/user.proto
syntax = "proto3";
package service;

import "common/base.proto";

message GetUserRequest {
  int32 user_id = 1;
}

message GetUserResponse {
  common.BaseResponse base = 1;   // 引用其他 package 的类型
  string             name = 2;
}

import 路径规则：

• 使用 import "path/to/file.proto"，路径相对于 --proto_path（或 -I）参数。
• Go 代码生成时，go_package 选项控制生成的 Go 包路径。
• 避免循环 import，Protobuf 编译器会直接报错。

3.5 oneof：互斥字段集合

oneof 用于表示一组字段中最多只有一个字段被设置。在压测场景中，常用于请求体多态、条件参数等场景。

message PaymentRequest {
  string order_id = 1;

  oneof payment_method {
    string credit_card_token = 2;
    string alipay_id        = 3;
    string wechat_openid    = 4;
  }
}

oneof 特性：

• 设置 oneof 中的任意字段会自动清除其他字段的值。
• Go 生成代码中，oneof 字段会生成一个接口类型和对应的结构体包装。
• oneof 字段编号不能与外部字段重复。

3.6 map：键值对映射

map 类型用于定义动态的键值对集合，语法为 map<key_type, value_type> field_name = N;。在压测中常用于传递标签、元数据或动态参数。

message BatchRequest {
  int32                  batch_id   = 1;
  map<string, string>    labels     = 2;   // 标签集合
  map<string, int32>     priorities = 3;   // 优先级映射
}

map 限制：

• key_type 必须是整型或 string。
• value_type 可以是任意类型，但不能是另一个 map。
• map 字段不能使用 repeated 修饰。
• 序列化时 map 是无序的，压测断言时不应依赖顺序。

3.7 综合结构图：Protobuf 核心语法关系

3.8 完整示例：压测服务接口定义

综合以上语法，定义一个用于压测的 Benchmark 服务接口：

syntax = "proto3";
package benchmark;

import "google/protobuf/timestamp.proto";

enum BenchmarkType {
  BENCHMARK_TYPE_UNSPECIFIED = 0;
  BENCHMARK_TYPE_READ        = 1;
  BENCHMARK_TYPE_WRITE       = 2;
  BENCHMARK_TYPE_MIXED       = 3;
}

message BenchmarkConfig {
  int32                     concurrency   = 1;  // 并发数
  int32                     total_requests = 2; // 总请求数
  map<string, string>       tags          = 3;  // 压测标签
  oneof payload_size {
    int32 fixed_size   = 4;  // 固定负载大小（字节）
    string dynamic_key = 5;  // 动态负载标识
  }
  BenchmarkType             type          = 6;
}

message BenchmarkResult {
  int32                          status_code   = 1;
  double                         latency_ms    = 2;
  google.protobuf.Timestamp      recorded_at   = 3;
  map<string, double>            percentiles   = 4; // p50/p90/p99
}

service BenchmarkService {
  rpc RunBenchmark(BenchmarkConfig) returns (BenchmarkResult);
}