Go gRPC契约gRPC领域建模与架构设计 - 第2节

2.1 Protobuf 语法基础：从 IDL 到契约

Protocol Buffers（Protobuf）是 gRPC 的接口定义语言（IDL）与序列化引擎。在 gRPC 领域边界中，.proto 文件是服务提供方与消费方之间唯一的、不可绕过的契约载体。本节从语法结构入手，建立对 Protobuf 文件的基本认知。

2.1.1 文件结构与语法要素

一个标准的 .proto 文件包含以下要素：

• 语法声明：syntax = "proto3"; 或 syntax = "proto2";。gRPC 默认使用 proto3。
• 包声明：package my.package; 用于避免命名冲突，在生成代码中映射为命名空间。
• 导入语句：import "google/protobuf/timestamp.proto"; 复用已有类型。
• 选项：option go_package = "example.com/project/gen;pb"; 控制代码生成路径。
• 消息定义：message 关键字定义数据结构。
• 服务定义：service 关键字定义 RPC 接口。

syntax = "proto3";

package ecommerce.v1;

option go_package = "github.com/example/ecommerce/gen/v1;ecv1";

import "google/protobuf/timestamp.proto";

message Product {
  string id = 1;
  string name = 2;
  double price = 3;
  google.protobuf.Timestamp created_at = 4;
}

service ProductService {
  rpc GetProduct(GetProductRequest) returns (Product);
}

2.2 消息类型定义：契约的最小单元

消息（Message）是 Protobuf 中最核心的数据结构。每个消息由一组字段组成，每个字段有唯一的编号、名称、类型和规则。消息类型定义直接决定了序列化后的二进制格式，因此是契约设计的起点。

2.2.1 消息定义语法

message Order {
  string order_id = 1;
  int32 quantity = 2;
  float total_amount = 3;
  bool is_paid = 4;
  repeated string tags = 5;
  map<string, string> attributes = 6;
  Address shipping_address = 7;
}

关键点：

• 字段编号（Field Number）：1 到 2^29-1（19000-19999 保留），用于二进制编码标识，一旦发布不可修改。
• 字段名称：使用驼峰命名，生成代码时自动转换为目标语言的命名风格。
• 字段类型：标量类型、枚举、其他消息类型、复合类型（repeated、map、oneof）。

2.3 字段规则与类型系统

Protobuf 的字段规则定义了字段的基数（出现次数）和行为。理解这些规则是设计健壮契约的前提。

2.3.1 字段规则对比

2.3.2 标量类型速查

2.3.3 复合类型：枚举与嵌套消息

枚举用于定义一组预定义的常量值，嵌套消息用于构建层次化数据结构。

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_PENDING = 1;
  ORDER_STATUS_SHIPPED = 2;
  ORDER_STATUS_DELIVERED = 3;
  ORDER_STATUS_CANCELLED = 4;
}

message Order {
  string order_id = 1;
  OrderStatus status = 2;
  message LineItem {
    string product_id = 1;
    int32 quantity = 2;
    double unit_price = 3;
  }
  repeated LineItem items = 3;
}

2.4 契约设计中的字段编号策略

字段编号是 Protobuf 序列化性能与契约演化灵活性的关键。编号越小，编码开销越低。

• 1-15 号字段：使用 1 字节编码，留给高频、核心字段。
• 16-2047 号字段：使用 2 字节编码，留给普通字段。
• 2048 号以上：使用 3 字节或更多编码，留给低频、扩展字段。
• 19000-19999：Protobuf 保留，不可使用。

2.5 消息类型关系图

下图展示了 Protobuf 消息类型定义中字段规则、类型系统与编号策略之间的整体关系：

2.6 契约兼容性：向前与向后兼容

Protobuf 的设计哲学允许消息类型在不破坏现有系统的情况下演化。兼容性规则是契约设计的核心约束。

2.6.1 向后兼容（新服务端，旧客户端）

• 可以新增字段（使用未使用过的编号）。
• 可以删除字段（但必须保留编号，用 reserved 标记）。
• 可以修改字段名称（编号不变即可）。
• 可以将 optional 改为 repeated（反之不行）。

2.6.2 向前兼容（旧服务端，新客户端）

• 新客户端发送的未知字段会被服务端忽略并透传。
• 新客户端期望的字段如果不存在，会得到零值。
• 枚举值如果未知，会被解析为 0（UNSPECIFIED）。

message ProductV2 {
  // 保留已删除的字段编号，防止未来误用
  reserved 5, 10, 12 to 15;
  reserved "old_field", "deprecated_field";

  string id = 1;
  string name = 2;
  double price = 3;
  // 新增字段，编号 16 使用 2 字节编码
  string category = 16;
  // 新增 repeated 字段
  repeated string tags = 17;
}

2.7 消息定义与字段规则总结

下表汇总了消息定义中各个元素的设计要点：