4. Protobuf 高级特性：默认值、字段规则、包与导入、选项

在掌握了 Protobuf 的基本消息定义后，本章深入探讨四个关键的高级特性。这些特性直接影响接口的兼容性、代码组织方式以及运行时行为，是设计生产级 gRPC 契约的必备知识。

4.1 字段默认值

Protobuf 3 中，当消息被解析时，如果某个字段未被显式赋值，该字段会被设置为该类型的“零值”（默认值）。这一特性与 Protobuf 2 有显著区别，也是导致兼容性问题的主要来源之一。

4.2 字段规则：singular 与 repeated

Protobuf 3 简化了字段规则，仅保留两种核心规则：

• singular（默认规则）：消息中该字段最多出现一次。在 Protobuf 3 中，所有未显式标注规则的字段默认即为 singular。
• repeated：消息中该字段可以出现任意次数（包括 0 次），在生成的代码中通常映射为列表或数组。

syntax = "proto3";

message Order {
  string order_id = 1;                    // singular (默认)
  repeated string item_codes = 2;         // repeated，可包含 0 或多个元素
  repeated LineItem items = 3;            // repeated 消息类型
  map<string, double> discounts = 4;     // map 是 repeated 的语法糖
}

message LineItem {
  string sku = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

4.3 包（package）与导入（import）

包用于避免不同 .proto 文件之间的命名冲突，导入则允许一个文件引用另一个文件中定义的消息类型。两者共同构成了 Protobuf 的模块化体系。

4.3.1 包的定义与作用

// file: ecommerce/common/v1/types.proto
syntax = "proto3";

package ecommerce.common.v1;

message Money {
  string currency_code = 1;
  int64 units = 2;
  int32 nanos = 3;
}

• 命名空间隔离：不同包中可以定义同名的消息类型。
• 生成代码的包路径：在 Java 中映射为 Java 包，在 C# 中映射为命名空间，在 Go 中映射为 Go 包路径。
• 包路径约定：推荐使用 组织.产品.版本 的层级结构，如 acme.payment.v1。

4.3.2 导入其他 .proto 文件

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

package ecommerce.order.v1;

import "ecommerce/common/v1/types.proto";  // 导入公共类型
import "google/protobuf/timestamp.proto";  // 导入标准 Well-Known 类型

message Order {
  string order_id = 1;
  ecommerce.common.v1.Money total_amount = 2;  // 使用全限定名
  google.protobuf.Timestamp created_at = 3;
}

4.4 选项（Options）

选项是 Protobuf 的元数据机制，用于控制代码生成、序列化行为以及运行时处理逻辑。选项可以作用于文件、消息、字段、枚举等多个层级。

4.4.1 文件级选项

syntax = "proto3";

package acme.payment.v1;

option java_package = "com.acme.payment.v1";       // 指定 Java 包名
option java_multiple_files = true;                  // 每个消息生成独立 Java 文件
option go_package = "github.com/acme/payment/v1";   // 指定 Go 包路径
option csharp_namespace = "Acme.Payment.V1";        // 指定 C# 命名空间
option optimize_for = SPEED;                        // 代码生成优化模式

4.4.2 字段级选项

message User {
  string email = 1 [(validate.rules) = { email: true }];  // 自定义验证选项
  string password = 2 [(buf.validate.field).string.min_len = 8]; // Buf 验证选项
  int32 age = 3 [deprecated = true];                        // 标记为废弃
}

4.4.3 常用选项速查表

4.5 特性关系总览

下图展示了本章四个高级特性在 Protobuf 契约定义中的协作关系：

4.6 实战：综合运用高级特性

以下示例展示了如何在一个真实的订单服务 .proto 文件中综合运用本章所有特性：

syntax = "proto3";

package ecommerce.order.v1;

option java_package = "com.ecommerce.order.v1";
option java_multiple_files = true;
option go_package = "github.com/ecommerce/order/v1";

import "ecommerce/common/v1/money.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

// 订单状态枚举，0 值必须为 UNSPECIFIED
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;
  string user_id = 2;
  repeated LineItem items = 3;                    // repeated 消息
  ecommerce.common.v1.Money total = 4;            // 跨包引用
  OrderStatus status = 5;
  google.protobuf.Timestamp created_at = 6;       // Well-Known 类型
  google.protobuf.StringValue note = 7;           // 包装类型，可区分空字符串与未设置
  string shipping_address = 8 [deprecated = true]; // 标记废弃
  string delivery_address = 9;                     // 替代字段
}

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