3. Protobuf 语法与定义：message定义、字段类型与标签、枚举、嵌套消息、import与package管理

Protocol Buffers（Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。掌握 Protobuf 语法是定义高效、可扩展微服务契约的基础。本章将系统讲解 message 定义、字段类型与标签规则、枚举、嵌套消息以及 import/package 管理，帮助你在实际项目中编写规范、兼容的 .proto 文件。

3.1 message 定义与字段类型

一个 message 是 Protobuf 中最基本的数据结构，类似于编程语言中的结构体（struct）。每个字段由 类型、字段名 和 标签号 组成。

syntax = "proto3";

message User {
  string user_id = 1;      // 字符串类型，标签号 1
  int32 age = 2;           // 32位整数，标签号 2
  double score = 3;        // 双精度浮点，标签号 3
  bool is_active = 4;      // 布尔类型，标签号 4
  bytes avatar = 5;        // 二进制数据，标签号 5
}

3.1.1 标量字段类型对照表

3.2 字段标签（Field Number）规则

每个字段必须有一个唯一的标签号，范围是 1 ~ 536,870,911。标签号直接影响序列化后的字节大小，合理分配标签号可以优化传输效率。

• 1 ~ 15：使用 1 字节编码，应分配给最频繁使用的字段。
• 16 ~ 2047：使用 2 字节编码，分配给次频繁字段。
• 19000 ~ 19999：保留区间，Protobuf 内部使用，禁止手动分配。
• > 2^29：使用 5 字节编码，仅用于极少使用的字段。

message OptimizedOrder {
  string order_id = 1;      // 高频字段，1字节
  string user_id = 2;       // 高频字段，1字节
  double total_amount = 3;  // 高频字段，1字节
  int32 status = 4;         // 高频字段，1字节
  string remark = 16;       // 低频字段，2字节
  string ext_info = 17;     // 低频字段，2字节
}

message User {
  reserved 2, 15, 9 to 11;  // 保留标签号
  reserved "phone", "email"; // 保留字段名
  string user_id = 1;
  string nickname = 3;
}

3.3 枚举（Enum）定义

枚举用于定义一组预定义的常量值。在 proto3 中，枚举的第一个值必须为 0，且枚举值在同一个 package 内必须全局唯一。

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

message Order {
  string order_id = 1;
  OrderStatus status = 2;  // 枚举类型字段
}

3.4 嵌套消息（Nested Message）

Protobuf 支持在一个 message 内部定义另一个 message，用于组织复杂的数据结构。嵌套消息可以提升代码的内聚性和可读性。

message Order {
  string order_id = 1;

  // 嵌套消息：订单项
  message OrderItem {
    string product_id = 1;
    int32 quantity = 2;
    double unit_price = 3;
  }

  // 嵌套枚举：支付方式
  enum PaymentMethod {
    PAYMENT_METHOD_UNSPECIFIED = 0;
    PAYMENT_METHOD_CREDIT_CARD = 1;
    PAYMENT_METHOD_WECHAT = 2;
    PAYMENT_METHOD_ALIPAY = 3;
  }

  repeated OrderItem items = 2;  // 使用嵌套消息
  PaymentMethod payment = 3;     // 使用嵌套枚举
}

外部引用嵌套消息时，使用 父消息.子消息 语法：

message Invoice {
  Order.OrderItem item = 1;  // 引用 Order 内部的 OrderItem
}

3.5 import 与 package 管理

当项目规模增长时，需要将 .proto 文件拆分到不同模块。Protobuf 通过 package 和 import 实现命名空间隔离与跨文件引用。

3.5.1 package 声明

package 用于防止不同模块间的类型命名冲突。生成的代码中，package 会映射为对应语言的命名空间（如 Java 的 package、Go 的 package path）。

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

message Timestamp {
  int64 seconds = 1;
  int32 nanos = 2;
}

3.5.2 import 引用

使用 import 关键字引入其他 .proto 文件中定义的类型。引用时使用 相对路径，路径基于 protoc 编译器的 -I（或 --proto_path）参数指定的搜索目录。

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

import "common/base.proto";  // 引入 common 包

message Order {
  string order_id = 1;
  common.Timestamp create_time = 2;  // 使用全限定名
}

3.5.3 import 分类与最佳实践

protos/
├── common/          # 公共基础类型
│   ├── base.proto
│   └── types.proto
├── order/           # 订单服务
│   ├── order.proto
│   └── order_service.proto
├── user/            # 用户服务
│   └── user.proto
└── google/          # Google 标准类型（如 Timestamp）
    └── protobuf/
        └── timestamp.proto

3.5.4 使用 Google 标准类型

Protobuf 官方提供了一组标准类型（如 google.protobuf.Timestamp、google.protobuf.Duration），建议优先使用而非自定义，以提升跨语言兼容性。

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

message Event {
  string event_id = 1;
  google.protobuf.Timestamp event_time = 2;
  google.protobuf.Duration ttl = 3;
}

3.6 综合示例：微服务订单契约

以下是一个完整的 .proto 文件示例，综合运用了本章所有知识点：

syntax = "proto3";
package ecommerce.order;

import "google/protobuf/timestamp.proto";
import "common/types.proto";

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

// 订单主消息
message Order {
  string order_id = 1;
  string user_id = 2;
  OrderStatus status = 3;
  google.protobuf.Timestamp create_time = 4;
  double total_amount = 5;

  // 嵌套消息：订单项
  message OrderItem {
    string product_id = 1;
    string product_name = 2;
    int32 quantity = 3;
    double unit_price = 4;
    common.Currency currency = 5;  // 引用公共类型
  }

  repeated OrderItem items = 6;
  common.Address shipping_address = 7;  // 引用公共类型
}