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

Protocol Buffers（Protobuf）是 gRPC 的接口定义语言（IDL）与序列化协议。在领域驱动设计中，.proto 文件不仅是技术契约，更是限界上下文之间通信的“语言边界”。本章将系统讲解 Protobuf 的核心语法要素，帮助你构建清晰、可演进的服务契约。

3.1 message 定义：领域对象的序列化映射

message 是 Protobuf 中最基本的复合数据类型，对应 DDD 中的值对象或实体。每个 message 由一组字段组成，每个字段包含类型、名称和唯一编号。

syntax = "proto3";

package ecommerce.orders;

message Order {
  string order_id = 1;
  int64 user_id = 2;
  double total_amount = 3;
  int32 item_count = 4;
  string status = 5;
  int64 created_at = 6;
}

3.2 字段类型体系

Protobuf 提供了一套跨语言的标量类型，下表列出最常用的类型及其与 Go 类型的对应关系：

3.3 枚举：定义领域常量集合

枚举用于表示一组预定义的常量值，非常适合描述订单状态、用户角色、支付方式等领域概念。枚举值必须从 0 开始，0 值作为默认值。

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;
}

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

enum PaymentMethod {
  reserved 2;  // 废弃了 CREDIT_CARD
  PAYMENT_METHOD_UNSPECIFIED = 0;
  PAYMENT_METHOD_ALIPAY = 1;
  PAYMENT_METHOD_WECHAT = 3;
}

3.4 嵌套消息：构建领域层次结构

嵌套消息允许在一个 message 内部定义另一个 message，用于表达聚合根内部的组合关系。嵌套消息的作用域仅限于父消息，避免全局命名冲突。

message Order {
  string order_id = 1;

  message LineItem {
    string product_id = 1;
    int32 quantity = 2;
    int64 unit_price_cents = 3;
  }

  repeated LineItem items = 2;
  Address shipping_address = 3;
}

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

在 Go 代码中，嵌套消息会生成 Order_LineItem 类型，外部消息 Address 则保持独立。

3.5 import 与 package：组织跨文件契约

随着微服务数量增长，.proto 文件需要合理的模块化管理。package 用于声明消息的命名空间，import 用于引用其他 .proto 文件中定义的类型。

3.5.1 package 声明

package 在 Protobuf 中主要解决命名冲突，并影响生成代码的 Go 包路径（通过 go_package 选项）。

syntax = "proto3";

package ecommerce.orders.v1;

option go_package = "github.com/company/ecommerce/proto/orders/v1;ordersv1";

message Order {
  // ...
}

3.5.2 import 机制

使用 import 可以引用其他 .proto 文件中的消息、枚举和服务定义。Protobuf 编译器通过 -I 或 --proto_path 参数查找导入文件。

// file: proto/common/v1/types.proto
syntax = "proto3";
package common.v1;
option go_package = "github.com/company/ecommerce/proto/common/v1;commonv1";

message Money {
  int64 cents = 1;
  string currency_code = 2;
}

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

import "common/v1/types.proto";

option go_package = "github.com/company/ecommerce/proto/orders/v1;ordersv1";

message Order {
  string order_id = 1;
  common.v1.Money total = 2;
}

3.6 完整的契约示例

以下是一个综合示例，展示了本章所有语法要素的协同使用：

// proto/orders/v1/order.proto
syntax = "proto3";

package ecommerce.orders.v1;

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

option go_package = "github.com/company/ecommerce/proto/orders/v1;ordersv1";

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;
}

message Order {
  string order_id = 1;
  int64 user_id = 2;
  OrderStatus status = 3;

  message LineItem {
    string product_id = 1;
    int32 quantity = 2;
    common.v1.Money unit_price = 3;
  }

  repeated LineItem items = 4;
  common.v1.Money total_amount = 5;
  common.v1.Address shipping_address = 6;
  google.protobuf.Timestamp created_at = 7;
  google.protobuf.Timestamp updated_at = 8;
}

3.7 最佳实践与避坑指南

• 字段编号规划：将 1-15 留给业务上必填且频繁传输的字段，16+ 用于可选或扩展字段。
• 枚举默认值：枚举的第一个值必须为 0，且命名为 UNSPECIFIED 或 INVALID，避免与业务有效值混淆。
• 嵌套 vs 独立：如果嵌套消息只在父消息中使用，优先定义为嵌套；如果被多个消息引用，提取为独立消息。
• import 路径：统一使用相对路径，并在编译时通过 -I 指定根目录，避免绝对路径导致跨平台问题。
• 向后兼容：永远不要修改已有字段的编号和类型；废弃字段使用 reserved 标记。