2. Protocol Buffers 入门：Protobuf 的作用、.proto 文件结构、消息类型定义、字段编号规则、标量类型与默认值

2.1 Protobuf 的核心作用

Protocol Buffers（简称 Protobuf）是 Google 开发的语言中立、平台中立、可扩展的序列化结构数据格式。在 gRPC 体系中，Protobuf 承担着 接口定义语言（IDL） 和 数据交换格式 的双重角色。

2.2 .proto 文件结构

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

1. 语法声明：指定 Protobuf 版本（proto2 / proto3）。
2. 包声明：防止命名冲突，类似 C++ namespace。
3. 导入声明：引用其他 .proto 文件中的类型。
4. 选项设置：如 go_package、java_package 等代码生成参数。
5. 消息定义：核心业务数据结构。
6. 枚举定义：预定义常量集合。
7. 服务定义：gRPC 接口方法声明。

syntax = "proto3";                          // 1. 语法声明

package user.v1;                            // 2. 包声明

import "common/timestamp.proto";            // 3. 导入声明

option go_package = "user/v1;userpb";       // 4. 选项设置

// 5. 消息定义
message User {
  string user_id = 1;
  string nickname = 2;
  int32 age = 3;
  Gender gender = 4;
}

// 6. 枚举定义
enum Gender {
  GENDER_UNSPECIFIED = 0;
  MALE = 1;
  FEMALE = 2;
}

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

2.3 消息类型定义与字段编号规则

消息（Message）是 Protobuf 中最核心的数据单元，每个字段由 字段编号、字段名、类型 三要素组成。

message Order {
  // 高频字段：使用 1~15
  string order_id = 1;
  string user_id = 2;
  double total_amount = 3;

  // 低频字段：使用 16+
  string remark = 16;
  int32 coupon_id = 17;

  // 已废弃字段：保留编号防止复用
  reserved 5, 10, 12;
  reserved "old_field", "deprecated_flag";
}

2.4 标量类型与默认值

Protobuf 3 提供了丰富的标量类型，每种类型在序列化时都有固定的 Wire Type 和默认值规则。

2.5 枚举与复合类型

除了标量类型，Protobuf 还支持枚举和复合消息类型：

• 枚举（enum）：第一个枚举值必须为 0，用于与默认值对齐。
• 嵌套消息：消息内部可以定义其他消息，实现层次化结构。
• map 类型：map<key_type, value_type> 用于键值对场景。
• repeated 字段：类似数组，可包含 0~N 个相同类型的元素。
• oneof 字段：一组字段中同时只能设置一个，节省内存。

message Order {
  string order_id = 1;
  repeated OrderItem items = 2;          // 订单项列表
  map<string, string> attributes = 3;   // 扩展属性
  oneof payment {
    string credit_card = 4;
    string alipay_id = 5;
    string wechat_id = 6;
  }
  OrderStatus status = 7;
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  PENDING = 1;
  PAID = 2;
  SHIPPED = 3;
  COMPLETED = 4;
  CANCELLED = 5;
}

message OrderItem {
  string product_id = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

2.6 版本兼容性要点