Proto3 语法入门：从 message 到包管理

Proto3 是 gRPC 契约的基石。本章将系统讲解 .proto 文件的核心语法，包括 message 定义、字段类型与编号规则、枚举类型以及 import/package 管理。掌握这些规则，你才能编写出可跨语言、跨版本兼容的 gRPC 契约。

1. message 定义：契约的最小单元

在 Proto3 中，message 是数据结构的核心容器。每个 message 对应一个逻辑实体，例如订单、用户或支付请求。

syntax = "proto3";

message Order {
  string order_id = 1;
  int32 user_id = 2;
  double total_amount = 3;
  bool paid = 4;
}

• syntax 声明：文件首行必须指定 syntax = "proto3";，否则编译器默认使用 proto2。
• 字段排列：每个字段由 类型 名称 = 编号; 组成，顺序不影响序列化。
• 嵌套 message：message 内部可以定义另一个 message，用于表达复杂层级。

2. 字段类型：标量、复合与特殊类型

3. 字段编号规则：不可逆的契约锚点

字段编号是 Proto3 序列化的核心标识，一旦发布就不可修改。编号决定了 wire format 中的 tag 值，直接影响兼容性和性能。

message Product {
  string name = 1;       // 小编号，高频字段
  string description = 2;
  double price = 3;
  int32 stock = 4;
  // 预留编号，防止未来冲突
  reserved 5, 6, 10 to 15;
  reserved "old_field", "deprecated_field";
}

• 编号范围：1 ~ 536,870,911。其中 1 ~ 15 仅占 1 字节 tag，16 ~ 2047 占 2 字节，更大编号占用更多空间。
• 高频字段用小编号：频繁出现的字段（如 ID、名称）应分配 1 ~ 15，以节省带宽。
• reserved 关键字：删除字段后，必须用 reserved 锁定编号和名称，防止未来误用导致兼容性灾难。
• 不可变规则：字段编号一旦在线上使用，永远不能修改或复用。这是 gRPC 契约演进的铁律。

4. 枚举类型：有限状态的定义

枚举用于表示一组预定义的常量值，例如订单状态、支付方式等。Proto3 的枚举必须从 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;
}

• 0 值语义：第一个枚举值必须为 0，且通常命名为 XXX_UNSPECIFIED，表示未设置或未知状态。
• 枚举作用域：枚举可以定义在 message 内部或文件顶层。跨文件引用时需通过 package 限定。
• 允许别名：通过 option allow_alias = true; 可以让多个枚举名映射到同一个数值，用于兼容旧版本。
• 枚举编号范围：枚举值编号必须在 int32 范围内（-2^31 ~ 2^31-1），但推荐使用非负整数。

5. import 与 package：模块化与命名空间

当项目规模增长时，你需要将 .proto 文件拆分为多个模块，并通过 import 和 package 管理依赖与命名冲突。

// file: common/currency.proto
package common;

enum Currency {
  CURRENCY_UNSPECIFIED = 0;
  CURRENCY_USD = 1;
  CURRENCY_EUR = 2;
  CURRENCY_CNY = 3;
}

// file: order/order.proto
package order;

import "common/currency.proto";

message Order {
  string order_id = 1;
  common.Currency currency = 2;  // 通过 package 引用
  double total = 3;
}

6. 完整契约示例：综合运用

下面是一个综合了 message、枚举、import 和 package 的完整示例，展示实际项目中的 .proto 文件组织方式。

// file: payment/payment.proto
package payment;

import "common/currency.proto";

enum PaymentMethod {
  PAYMENT_METHOD_UNSPECIFIED = 0;
  PAYMENT_METHOD_CREDIT_CARD = 1;
  PAYMENT_METHOD_ALIPAY = 2;
  PAYMENT_METHOD_WECHAT = 3;
}

message PaymentRequest {
  string payment_id = 1;
  string order_id = 2;
  common.Currency currency = 3;
  double amount = 4;
  PaymentMethod method = 5;
  map<string, string> metadata = 6;  // 扩展元数据
}

message PaymentResponse {
  string transaction_id = 1;
  bool success = 2;
  string error_message = 3;
}

7. 常见陷阱与避坑指南

• 字段编号复用：永远不要修改或复用已发布的字段编号。使用 reserved 锁定已删除的编号和名称。
• 枚举值 0 的语义：0 值在 proto3 中作为默认值，如果业务上 0 有实际含义（如状态为“已创建”），会导致新老客户端行为不一致。始终将 0 定义为 UNSPECIFIED。
• import 循环依赖：Proto3 不允许循环 import。如果 A.proto 引用 B.proto，B.proto 不能反向引用 A.proto。解决方案：将公共类型抽离到第三个文件。
• package 与 go_package 混淆：package 是 proto 的命名空间，go_package 指定生成的 Go 代码的包路径。两者可以不同，但建议保持一致。
• 字段默认值不参与序列化：如果字段被设为默认值（如 int32 的 0，string 的 ""），序列化时会跳过该字段。反序列化时，未设置的字段也会被赋为默认值。这导致无法区分“未设置”和“被设为默认值”。