2. Protocol Buffers 入门：Protobuf 简介、.proto 文件结构、消息类型定义、字段编号规则

2.1 Protobuf 简介：为什么需要接口契约语言？

在 gRPC 体系中，Protocol Buffers（简称 Protobuf） 是接口定义语言（IDL）与数据序列化协议的统一体。它解决了分布式系统中三个核心问题：

• 语言中立：服务端用 Java、客户端用 Go 或 Python，仍能通过同一份 .proto 文件生成完全兼容的代码。
• 高效序列化：二进制编码体积约为 JSON 的 1/3~1/10，解析速度提升 2~10 倍。
• 强类型约束：字段类型、编号、可选/必选在编译期即确定，避免运行时字段名拼写错误或类型不匹配。

2.2 .proto 文件结构：从零搭建一个契约文件

一个标准的 .proto 文件由以下部分组成，按出现顺序排列：

以下是一个完整的 .proto 文件示例：

syntax = "proto3";

package user.v1;

import "google/protobuf/timestamp.proto";

option go_package = "github.com/example/protos/user/v1;userv1";

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

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

message GetUserRequest {
  uint64 user_id = 1;
}

2.3 消息类型定义：字段类型与组合方式

Protobuf 消息由一组字段构成，每个字段包含：类型、名称、编号。支持的类型体系如下：

组合使用示例：

message Order {
  uint64 order_id = 1;
  repeated string item_ids = 2;          // 商品 ID 列表
  map<string, string> attributes = 3;   // 自定义属性
  optional string note = 4;              // 可选备注
  Status status = 5;                     // 枚举类型
}

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

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

字段编号是 Protobuf 序列化的核心标识，一旦发布，不可修改。编号规则如下：

1. 编号范围：1 ~ 2²⁹-1（536,870,911），其中 19000~19999 为 Protobuf 保留编号，不可使用。
2. 编码效率：编号 1~15 使用 1 字节编码；16~2047 使用 2 字节编码。高频字段应分配小编号。
3. 不可复用：删除字段后，其编号必须标记为 reserved，防止未来误用导致数据损坏。
4. 不可重编号：字段编号变更会破坏已有序列化数据的兼容性。

编号分配策略对比：

保留字段声明示例：

message User {
  reserved 2, 15, 20 to 30;   // 保留已删除的字段编号
  reserved "phone", "fax";    // 保留已删除的字段名称（防止 JSON 序列化冲突）
  
  uint64 id = 1;
  string name = 3;            // 注意：编号 2 已被保留，不可使用
}

2.5 Protobuf 消息结构总览

下图展示了 .proto 文件中消息定义、字段类型、编号规则与序列化结果之间的整体关系：

2.6 常见陷阱与避坑指南