gRPCGo gRPC契约接口设计与契约测试 - 第2节

2.1 Protocol Buffers 简介

Protocol Buffers（简称 Protobuf）是 Google 开发的一种语言中立、平台中立、可扩展的序列化结构化数据格式。在 gRPC 体系中，Protobuf 承担着接口定义语言（IDL）和数据交换格式的双重角色。与 JSON、XML 相比，Protobuf 具有更小的数据体积、更快的解析速度以及更强的类型约束。

2.1.1 为什么 gRPC 选择 Protobuf？

2.2 .proto 文件结构

一个标准的 .proto 文件由包声明、导入语句、选项设置以及消息/服务定义组成。以下是一个完整的示例：

syntax = "proto3";                  // 指定使用 proto3 语法

package userpb;                     // 包声明，防止命名冲突

option go_package = "example.com/userpb";  // Go 代码生成路径

import "google/protobuf/timestamp.proto";  // 导入标准时间类型

// 用户实体消息
message User {
  uint64 id       = 1;
  string name     = 2;
  string email    = 3;
  google.protobuf.Timestamp created_at = 4;
}

// 用户服务定义
service UserService {
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
}

2.2.1 文件结构要素

• syntax：必须位于文件第一行，指定 Protobuf 版本（proto3 或 proto2）。gRPC 推荐使用 proto3。
• package：为消息和服务定义命名空间，避免不同文件间的命名冲突。
• option go_package：指定 Go 代码生成的包路径，是 Go 语言使用 Protobuf 的必选项。
• import：引入其他 .proto 文件中的定义，支持跨文件复用。
• message：定义数据结构，包含多个字段。
• service：定义 gRPC 服务接口，包含 RPC 方法签名。

2.3 消息类型定义

消息（Message）是 Protobuf 中最基本的数据单元，类似于 Go 中的结构体。每个消息由若干个字段组成，每个字段包含类型、名称和编号。

2.3.1 标量类型与 Go 映射

2.3.2 复合类型

• 枚举（enum）：定义一组预定义的常量值。
• 嵌套消息：在一个消息内部定义另一个消息。
• map 类型：map<key_type, value_type> 映射表。
• repeated 字段：表示可变长度的数组（在 Go 中生成切片）。
• oneof 字段：一组字段中最多只能设置一个。

message Order {
  uint64 order_id = 1;
  repeated string items = 2;          // 字符串数组
  map<string, double> prices = 3;    // 商品名 -> 价格映射
  oneof payment {
    string credit_card = 4;
    string wechat_pay = 5;
    string alipay = 6;
  }
  Status status = 7;                  // 枚举类型
}

enum Status {
  STATUS_UNKNOWN = 0;
  STATUS_PENDING = 1;
  STATUS_SHIPPED = 2;
  STATUS_DELIVERED = 3;
}

2.4 字段编号与类型规则

字段编号是 Protobuf 向后兼容性的核心机制。每个字段在消息中必须有一个唯一的数字标识符，用于二进制编码时识别字段。

2.4.1 编号范围与规则

message Product {
  reserved 2, 15, 20 to 30;          // 保留编号
  reserved "old_name", "legacy_code"; // 保留字段名

  uint64 id = 1;
  string name = 3;                    // 注意：编号 2 已被保留
  double price = 4;
}

2.4.2 字段类型选择原则

• 整数类型：对于非负数值，优先使用 uint32/uint64；对于可能为负的数值，使用 sint32/sint64（采用 ZigZag 编码，负数更高效）。
• 字符串 vs bytes：文本数据用 string，二进制数据用 bytes。
• 枚举默认值：枚举的第一个值必须为 0，且语义上表示“未知”或“默认”。
• repeated 字段：proto3 中 repeated 字段默认使用 packed 编码，更节省空间。

2.5 实战：定义第一个 gRPC 消息

结合以上知识，我们定义一个完整的用户管理服务消息集合：

syntax = "proto3";

package usermgmt;

option go_package = "github.com/example/usermgmt/proto";

// 创建用户请求
message CreateUserRequest {
  string name     = 1;
  string email    = 2;
  uint32 age      = 3;
  repeated string tags = 4;           // 用户标签列表
}

// 创建用户响应
message CreateUserResponse {
  uint64 id       = 1;
  string name     = 2;
  string email    = 3;
  UserStatus status = 4;              // 枚举类型
}

// 用户状态枚举
enum UserStatus {
  USER_STATUS_UNSPECIFIED = 0;
  USER_STATUS_ACTIVE = 1;
  USER_STATUS_INACTIVE = 2;
  USER_STATUS_BANNED = 3;
}

通过本章学习，你已经掌握了 Protobuf 的核心概念：文件结构、消息定义、字段编号规则以及类型系统。这些知识是后续定义 gRPC 服务接口的基础，也是实现客户端与服务端契约一致性的关键保障。