2. Protocol Buffers 基础：Protobuf 简介、.proto 文件结构、消息类型定义、字段编号与类型、默认值与可选字段

2.1 Protobuf 简介

Protocol Buffers（简称 Protobuf）是 Google 开发的一种语言中立、平台中立、可扩展的序列化结构化数据机制。与 JSON 或 XML 相比，Protobuf 具有以下核心优势：

• 序列化体积小：二进制编码，数据量约为 JSON 的 1/3 到 1/10。
• 解析速度快：无需字符串解析，直接按字节偏移读取字段。
• 强类型约束：在 .proto 文件中定义严格的数据结构，编译期即可发现类型错误。
• 向后兼容：通过字段编号机制，支持在不破坏现有代码的情况下扩展消息。
• 多语言支持：官方支持 C++、Java、Python、Go、C#、Ruby、PHP、JavaScript 等。

2.2 .proto 文件结构

一个标准的 .proto 文件由以下几个部分组成，以下是一个完整的示例：

syntax = "proto3";                          // 指定语法版本

package user.v1;                            // 包声明，用于避免命名冲突

import "common/timestamp.proto";            // 导入其他 .proto 文件

option go_package = "user/v1;userv1";       // 语言特定选项

// 枚举类型定义
enum Gender {
  GENDER_UNSPECIFIED = 0;                   // 默认值必须为 0
  MALE = 1;
  FEMALE = 2;
}

// 消息类型定义
message User {
  uint64 id = 1;                            // 字段编号 1
  string name = 2;                          // 字段编号 2
  Gender gender = 3;                        // 字段编号 3
  optional string email = 4;                // 可选字段（proto3）
  repeated string phone_numbers = 5;        // 重复字段（列表）
  Address address = 6;                      // 嵌套消息类型
}

message Address {
  string street = 1;
  string city = 2;
  string zip_code = 3;
}

2.3 消息类型定义

消息类型使用 message 关键字定义，可以包含多种字段类型。消息支持嵌套定义，也支持使用已定义的其他消息类型作为字段类型。

// 嵌套消息示例
message Order {
  string order_id = 1;
  uint64 user_id = 2;

  // 嵌套消息
  message LineItem {
    string product_id = 1;
    int32 quantity = 2;
    double price = 3;
  }

  repeated LineItem items = 3;

  // 使用外部消息类型
  common.Money total_amount = 4;
}

// 使用 map 类型
message Config {
  map<string, string> settings = 1;
}

// 使用 oneof 类型（互斥字段）
message Response {
  oneof result {
    string success_message = 1;
    string error_message = 2;
  }
}

2.4 字段编号与类型

每个消息字段必须有一个唯一的字段编号（Field Number），用于在二进制编码中标识该字段。字段编号的范围和规则如下：

Protobuf 支持的字段类型分为标量类型和复合类型：

// 使用 reserved 标记废弃字段
message User {
  reserved 2, 15, 9 to 11;       // 保留字段编号
  reserved "phone", "email";     // 保留字段名称

  uint64 id = 1;
  string name = 3;
  // 注意：编号 2 已被保留，不能使用
}

2.5 默认值与可选字段

在 proto3 中，所有字段在未设置值时都会使用其类型的默认值。这一机制简化了空值处理，但也带来了一个常见问题：无法区分“字段未被设置”和“字段被设置为默认值”。

为了解决默认值带来的歧义，proto3 引入了 optional 关键字，显式标记字段为可选字段。可选字段会生成一个包装类型，在序列化时明确记录字段是否存在。

// 可选字段示例
message UserProfile {
  string nickname = 1;
  optional string avatar_url = 2;    // 可选字段，可区分空字符串和未设置
  optional int32 age = 3;           // 可选字段，可区分 0 和未设置
}

// 在 Go 中，optional 字段会生成指针类型
// avatar_url 的类型为 *string
// age 的类型为 *int32

2.6 本章小结

• Protobuf 是 gRPC 的契约基础，提供高效的二进制序列化与强类型约束。
• .proto 文件 由 syntax、package、import、option、message、enum 等部分组成，结构清晰。
• 消息类型 支持嵌套、导入外部类型、map、oneof 等高级特性。
• 字段编号 1~15 占用 1 字节，应分配给高频字段；废弃编号需用 reserved 保护。
• 默认值 在 proto3 中自动生效，optional 关键字用于区分“未设置”与“默认值”。