3. Protobuf 数据类型：标量类型、枚举类型、复合类型、map 类型、oneof 类型

Protobuf 作为 gRPC 的接口定义语言（IDL），其数据类型系统是契约设计的基石。理解每种类型的特性、适用场景及序列化行为，是编写高效、兼容的 .proto 文件的前提。本章将系统梳理 Protobuf 的五大类型体系。

3.1 标量类型（Scalar Types）

标量类型是 Protobuf 中最基础的数据单元，对应编程语言中的基本类型。不同语言生成的代码会映射为对应的原生类型。

3.2 枚举类型（Enum）

枚举用于定义一组预定义的常量值，增强代码可读性与类型安全。枚举常量必须从 0 开始，且 0 值作为默认值。

syntax = "proto3";

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

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;  // 必须存在，作为默认值
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_CONFIRMED = 2;
  ORDER_STATUS_SHIPPED = 3;
  ORDER_STATUS_DELIVERED = 4;
  ORDER_STATUS_CANCELLED = 5;
}

3.3 复合类型（Message）

复合类型是 Protobuf 的核心，允许将多个字段组合成一个逻辑单元，支持嵌套定义。复合类型可以包含其他 message、枚举、标量类型，以及后续介绍的 map 和 oneof。

message Address {
  string street = 1;
  string city = 2;
  string zip_code = 3;
}

message User {
  int64 user_id = 1;
  string name = 2;
  Address home_address = 3;       // 引用其他 message
  repeated Address history = 4;   // 重复字段，类似列表
}

复合类型支持 嵌套 定义，适用于内部逻辑紧密的场景：

message Company {
  string name = 1;
  message Department {
    int32 dept_id = 1;
    string dept_name = 2;
  }
  repeated Department departments = 2;
}

3.4 map 类型

map 类型提供键值对映射，语法为 map<K, V> map_field = N;。键类型必须是标量类型（string、整型等），值类型可以是任意 Protobuf 类型。

message Product {
  int64 product_id = 1;
  string name = 2;
  map<string, string> attributes = 3;  // 动态属性
  map<string, double> prices = 4;      // 按地区定价
}

3.5 oneof 类型

oneof 用于表示一组互斥字段，同一时刻只能设置其中一个字段。它常用于联合体、状态机或可选配置场景。

message Payment {
  int64 payment_id = 1;
  oneof payment_method {
    string credit_card = 2;
    string alipay_account = 3;
    string wechat_openid = 4;
    int64 balance_pay = 5;
  }
}

oneof 的关键行为：

• 互斥性： 设置 oneof 中的任意字段会自动清除其他字段的值。
• 内存共享： 在生成的代码中，oneof 字段通常使用 union 或特殊包装类实现，节省内存。
• 字段编号： oneof 内的字段使用独立的编号空间，不与 message 其他字段冲突。
• 不可与 map 或 repeated 混用： oneof 内的字段不能是 repeated 或 map 类型。

3.6 类型体系总览

下图展示了 Protobuf 数据类型的完整分类体系，以及各类型在契约设计中的典型应用场景。

3.7 类型选择决策指南

在实际契约设计中，可参考以下决策流程快速确定字段类型：

1. 是否为固定集合？ → 是，使用 枚举；否，继续。
2. 是否为简单值？ → 是，使用 标量类型；否，继续。
3. 是否为键值对映射？ → 是，使用 map；否，继续。
4. 是否为互斥选项？ → 是，使用 oneof；否，使用 message 复合类型。