📚 课程目录第3章 Proto文件基础

3. Proto 文件基础：proto3 语法入门、message 定义、字段类型与字段编号规则

在 BFF 聚合服务中，gRPC 接口的协议定义全部由 Proto 文件（.proto）承载。Proto 文件既是服务端与客户端之间的契约，也是代码生成器的输入源。掌握 proto3 语法是进行协议适配的前提。

3.1 proto3 语法结构

一个标准的 proto3 文件由以下部分组成：

语法声明：文件首行必须指定 syntax = "proto3";，表示使用 proto3 版本。
包声明：使用 package 关键字定义命名空间，避免不同 proto 文件间的类型冲突。
导入语句：通过 import 引入其他 proto 文件中定义的类型。
选项设置：如 option go_package 指定生成的 Go 代码包路径。
服务定义：使用 service 关键字声明 RPC 接口。
消息定义：使用 message 关键字定义请求/响应数据结构。

  💡 工程建议：在 BFF 项目中，建议将 proto 文件按业务模块拆分，统一放在 api/proto/ 目录下，并通过 import 相互引用，避免单个文件过于臃肿。

3.2 message 定义与字段类型

message 是 proto3 中最核心的数据结构，相当于编程语言中的结构体或类。每个 message 由若干字段组成，每个字段包含：字段类型、字段名称、字段编号。

3.2.1 标量字段类型

Proto 类型	对应 Go 类型	对应 Java 类型	说明
`double`	`float64`	`double`	64 位浮点数
`float`	`float32`	`float`	32 位浮点数
`int32`	`int32`	`int`	可变长编码，负数效率低
`int64`	`int64`	`long`	可变长编码，负数效率低
`uint32`	`uint32`	`int`	无符号 32 位
`uint64`	`uint64`	`long`	无符号 64 位
`sint32`	`int32`	`int`	有符号，负数编码更高效
`fixed32`	`uint32`	`int`	固定 4 字节，大于 2^28 时编码更快
`fixed64`	`uint64`	`long`	固定 8 字节
`bool`	`bool`	`boolean`	布尔值
`string`	`string`	`String`	UTF-8 编码字符串，长度不超过 2^32
`bytes`	`[]byte`	`ByteString`	任意字节序列

3.2.2 复合类型

枚举（enum）：定义一组预定义的常量值，必须从 0 开始。
嵌套 message：一个 message 内部可以定义另一个 message，实现层级结构。
map 类型：map<key_type, value_type>，key 必须是标量类型。
repeated 字段：表示可变长度数组，相当于 Go 中的 slice。
oneof 字段：一组字段中同时只能设置其中一个，常用于联合体场景。

syntax = "proto3";

package bff.user;

option go_package = "github.com/example/bff/api/proto/user";

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

// 嵌套 message 示例
message Address {
  string country = 1;
  string city = 2;
  string detail = 3;
}

// 主 message
message UserProfile {
  int64 user_id = 1;
  string nickname = 2;
  Gender gender = 3;
  repeated string tags = 4;               // repeated 字段
  map<string, string> extra = 5;         // map 字段
  Address address = 6;                    // 引用其他 message
  oneof contact {                         // oneof 字段
    string email = 7;
    string phone = 8;
  }
}

3.3 字段编号规则

字段编号是 proto3 序列化与反序列化的核心标识，直接影响编码效率和兼容性。每个字段必须有一个唯一的正整数编号。

3.3.1 编号范围与用途

编号范围	占用字节	推荐用途
1 ~ 15	1 字节	频繁出现的字段，编码效率最高
16 ~ 2047	2 字节	普通字段
2048 ~ 536,870,911	5 字节	极少使用的字段或预留扩展
19000 ~ 19999	—	保留编号，Protocol Buffers 内部使用，禁止用户使用

⚠️ 避坑指南：

字段编号一旦被使用，不应修改，否则会导致旧数据反序列化错误。
删除字段时，应使用 reserved 关键字标记已删除的编号和名称，防止未来误用。
将高频字段放在 1~15 范围内，可显著降低序列化后的数据体积。

3.3.2 reserved 关键字

message UserProfile {
  reserved 2, 15, 20 to 25;       // 保留字段编号
  reserved "phone", "email";      // 保留字段名称

  int64 user_id = 1;
  string nickname = 3;            // 编号 2 已被保留，不可使用
}

3.4 字段编号与序列化效率的关系

下图展示了字段编号在 protobuf 二进制编码中的位置，以及编号大小对编码体积的影响：

3.5 字段默认值与零值

proto3 中，所有字段在未设置值时使用零值，序列化时会省略零值字段，从而减小数据体积。

字段类型	零值	序列化行为
数值类型	`0`	省略
`bool`	`false`	省略
`string`	`""`	省略
`bytes`	空字节	省略
枚举	第一个枚举值（编号 0）	省略
`repeated`	空列表	省略
`map`	空 map	省略
message 类型	`null`	省略

📌 BFF 适配要点：在 BFF 聚合服务中，当后端微服务返回的 proto 字段为零值时，gRPC 响应中不会包含该字段。BFF 层在转换为前端 JSON 时，需要根据业务需求决定是否填充默认值或直接省略，避免前端因字段缺失而报错。

3.6 服务定义与 RPC 方法

proto3 使用 service 关键字定义 gRPC 接口，每个方法必须指定请求 message 和响应 message。

service UserService {
  // 一元 RPC
  rpc GetUserProfile (GetUserProfileRequest) returns (UserProfile);

  // 服务端流式 RPC
  rpc ListUserTags (ListUserTagsRequest) returns (stream Tag);

  // 客户端流式 RPC
  rpc BatchUpdateProfile (stream UpdateProfileRequest) returns (BatchUpdateResponse);

  // 双向流式 RPC
  rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}

下图展示了 BFF 聚合服务中 proto 文件与代码生成、服务实现之间的关系：

3.7 本章小结

proto3 语法以 syntax = "proto3" 开头，通过 message 定义数据结构，service 定义 RPC 接口。
字段类型包括标量类型、枚举、嵌套 message、map、repeated 和 oneof，每种类型对应不同的序列化行为。
字段编号 1~15 占用 1 字节，应分配给高频字段；删除字段时必须使用 reserved 防止冲突。
零值字段在序列化时被省略，BFF 层需注意前端 JSON 字段缺失的处理策略。