4. Protocol Buffers 语法进阶：message 嵌套、枚举、map、oneof、包管理、import 与 option

在 gRPC 契约设计中，基础字段类型往往不足以表达复杂的业务模型。本章将深入 Protocol Buffers 的进阶语法特性，包括 message 嵌套、枚举、map、oneof、包管理、import 与 option。掌握这些特性，是编写可维护、可扩展的 gRPC 服务契约的关键。

4.1 message 嵌套：构建层次化数据结构

嵌套 message 允许在一个 message 内部定义另一个 message，用于表达“整体-部分”关系或作用域隔离。嵌套的 message 对外部可见，可通过 Parent.Child 方式引用。

syntax = "proto3";

package ecommerce;

message Order {
    string order_id = 1;
    int64 user_id = 2;
    // 嵌套 message：订单项
    message OrderItem {
        string product_id = 1;
        int32 quantity = 2;
        double unit_price = 3;
    }
    repeated OrderItem items = 3;
    double total_amount = 4;
}

// 外部引用嵌套 message
message Shipment {
    string shipment_id = 1;
    repeated Order.OrderItem shipped_items = 2; // 通过 Parent.Child 引用
}

4.2 枚举：定义有限取值集合

枚举用于定义一组预定义的常量值，增强代码可读性和类型安全。Proto3 要求枚举的第一个值必须为 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; // 使用枚举类型
}

4.3 map 类型：键值对映射

Proto3 支持 map<K, V> 类型，用于表示键值对集合。键类型必须是整数或字符串，值类型可以是任意 message 或标量类型。

message ProductInfo {
    string product_id = 1;
    map<string, string> attributes = 2; // 动态属性键值对
    map<string, double> price_tiers = 3; // 价格层级
}

// 使用示例
message InventoryResponse {
    map<string, int32> stock_by_warehouse = 1; // 仓库ID -> 库存数量
}

4.4 oneof：互斥字段集合

oneof 用于定义一组互斥的字段，同一时刻只能设置其中一个字段。常用于表达“多选一”的业务场景，如支付方式、通知渠道等。

message Payment {
    string payment_id = 1;
    oneof payment_method {
        CreditCard credit_card = 10;
        Alipay alipay = 11;
        WechatPay wechat_pay = 12;
        BankTransfer bank_transfer = 13;
    }
}

message CreditCard {
    string card_number = 1;
    string expiry = 2;
    string cvv = 3;
}

message Alipay {
    string alipay_id = 1;
}

message WechatPay {
    string open_id = 1;
}

message BankTransfer {
    string account_number = 1;
    string bank_code = 2;
}

// Go 中处理 oneof 的典型模式
switch pm := payment.GetPaymentMethod().(type) {
case *pb.Payment_CreditCard:
    fmt.Println("信用卡支付:", pm.CreditCard.CardNumber)
case *pb.Payment_Alipay:
    fmt.Println("支付宝支付:", pm.Alipay.AlipayId)
case *pb.Payment_WechatPay:
    fmt.Println("支付:", pm.WechatPay.OpenId)
case *pb.Payment_BankTransfer:
    fmt.Println("银行转账:", pm.BankTransfer.AccountNumber)
default:
    fmt.Println("未知支付方式")
}

4.5 包管理：命名空间与冲突避免

package 声明用于为 proto 文件定义命名空间，避免不同模块间的类型命名冲突。在 Go 中，package 名称会映射为 Go 的 package 路径。

syntax = "proto3";

package ecommerce.order.v1; // 推荐格式：domain.entity.version

// 生成的 Go package 路径由 go_package option 控制
option go_package = "github.com/company/ecommerce/proto/order/v1;orderv1";

4.6 import：模块化与复用

import 允许一个 proto 文件引用另一个 proto 文件中定义的类型，是实现契约模块化的基础。Proto3 支持相对路径和绝对路径两种导入方式。

// file: common/currency.proto
syntax = "proto3";
package common;
enum Currency {
    CURRENCY_UNSPECIFIED = 0;
    USD = 1;
    EUR = 2;
    CNY = 3;
    JPY = 4;
}

// file: order/order.proto
syntax = "proto3";
package order;
import "common/currency.proto"; // 相对路径导入

message Order {
    string order_id = 1;
    common.Currency currency = 2; // 使用导入的枚举
    double amount = 3;
}

4.7 option：编译时元数据控制

option 用于控制 proto 编译器的行为，影响代码生成、序列化优化、服务定义等。常用的 option 包括 go_package、java_package、optimize_for 等。

syntax = "proto3";

package ecommerce.order.v1;

// 控制生成的 Go package 路径和名称
option go_package = "github.com/company/ecommerce/proto/order/v1;orderv1";

// 控制 Java 包路径
option java_package = "com.company.ecommerce.order.v1";
option java_multiple_files = true; // 每个 message 生成独立 Java 文件

// 优化模式：SPEED（默认）、CODE_SIZE、LITE_RUNTIME
option optimize_for = SPEED;

// 自定义 option（需要提前定义扩展）
// option (my_custom_option) = "some_value";

4.8 综合实战：构建订单服务契约

将上述语法特性整合到一个完整的订单服务 proto 文件中，展示进阶语法的实际应用。

syntax = "proto3";

package ecommerce.order.v1;

option go_package = "github.com/company/ecommerce/proto/order/v1;orderv1";

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

// 订单状态枚举
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
message Order {
    string order_id = 1;
    int64 user_id = 2;
    OrderStatus status = 3;
    common.Currency currency = 4;
    google.protobuf.Timestamp created_at = 5;

    // 嵌套：订单项
    message OrderItem {
        string product_id = 1;
        string product_name = 2;
        int32 quantity = 3;
        double unit_price = 4;
        map<string, string> customizations = 5; // 定制选项
    }
    repeated OrderItem items = 6;

    // 支付信息（互斥）
    oneof payment {
        CreditCardPayment credit_card = 10;
        DigitalWalletPayment digital_wallet = 11;
    }

    // 配送地址
    ShippingAddress shipping_address = 7;
}

message CreditCardPayment {
    string last_four_digits = 1;
    string card_holder_name = 2;
}

message DigitalWalletPayment {
    string wallet_type = 1; // "alipay", "wechat", "paypal"
    string transaction_id = 2;
}

message ShippingAddress {
    string street = 1;
    string city = 2;
    string state = 3;
    string zip_code = 4;
    string country = 5;
}

// 服务定义
service OrderService {
    rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
    rpc GetOrder(GetOrderRequest) returns (Order);
    rpc ListOrders(ListOrdersRequest) returns (stream Order);
}

message CreateOrderRequest {
    int64 user_id = 1;
    repeated Order.OrderItem items = 2;
    oneof payment {
        CreditCardPayment credit_card = 10;
        DigitalWalletPayment digital_wallet = 11;
    }
    ShippingAddress shipping_address = 3;
}

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

message GetOrderRequest {
    string order_id = 1;
}

message ListOrdersRequest {
    int64 user_id = 1;
    OrderStatus status_filter = 2;
}