Init
This commit is contained in:
@@ -0,0 +1,309 @@
|
||||
---
|
||||
tags: [gRPC, Protobuf, proto, message, enum, oneof, map, IDL]
|
||||
create time: 2026-05-11 16:40
|
||||
---
|
||||
|
||||
# Protobuf 语法与消息定义
|
||||
|
||||
## 概述
|
||||
|
||||
gRPC 使用 Protobuf（Protocol Buffers）作为接口定义语言（IDL）。所有 gRPC 服务契约都以 `.proto` 文件编写——这是你的 API「蓝图」，任何调用方、服务端都从这里生成代码。**学会写 `.proto` 文件，你就拿到了整个 gRPC 体系的入场券。**
|
||||
|
||||
> [!question] 为什么选 Protobuf 而不是 JSON Schema？
|
||||
> JSON Schema 描述的是数据格式，但不提供序列化协议和跨语言代码生成能力。Protobuf 则是一套完整的 IDL：它定义了数据结构、wire format、序列化规则，并且为多语言自动生成强类型 Stub。对于内部微服务通信，这意味着**契约即代码**，编译期就能发现类型不匹配。
|
||||
|
||||
## .proto 文件骨架
|
||||
|
||||
一个 `.proto` 文件由若干顶层声明组成。先看完整骨架：
|
||||
|
||||
```protobuf
|
||||
syntax = "proto3"; // ① 版本声明
|
||||
|
||||
package user.v1; // ② 包名（命名空间）
|
||||
option go_package = "github.com/example/svc/user/v1;v1"; // ③ Go 输出路径
|
||||
|
||||
import "google/protobuf/timestamp.proto"; // ④ 引用外部 Proto
|
||||
|
||||
message GetUserRequest { // ⑤ 消息
|
||||
string id = 1;
|
||||
}
|
||||
|
||||
message GetUserResponse { // ⑤ 消息
|
||||
User user = 1;
|
||||
}
|
||||
|
||||
message User { // ⑤ 消息
|
||||
string id = 1;
|
||||
string name = 2;
|
||||
google.protobuf.Timestamp created_at = 3;
|
||||
}
|
||||
|
||||
service UserService { // ⑥ RPC 服务
|
||||
rpc GetUser(GetUserRequest) returns (GetUserResponse);
|
||||
rpc ListUsers(ListUsersRequest) returns (stream User);
|
||||
}
|
||||
```
|
||||
|
||||
> [!note] proto2 vs proto3
|
||||
> - **proto3** 是当前默认版本，移除了 `required`/`optional` 字段修饰符、枚举必须从 0 开始等限制，语法更简洁。
|
||||
> - **proto2** 仍被部分遗留系统使用，支持更完整的特性如 `required`/`optional`、manually-implemented map field 等。
|
||||
> - **新项目一律使用 `syntax = "proto3"`**。除非你在维护十年前的遗留服务，否则没有理由用 proto2。
|
||||
|
||||
### 核心组成部分速查
|
||||
|
||||
| 声明 | 作用 | 是否必需 |
|
||||
|------|------|----------|
|
||||
| `syntax` | 指定 Protobuf 版本 | ✅ |
|
||||
| `package` | 命名空间隔离，避免名称冲突 | ⚠️ 推荐 |
|
||||
| `option go_package` | Go 生成的包路径和导出前缀 | ✅ Go 项目必需 |
|
||||
| `import` | 引用其他 `.proto` 文件 | ❌ |
|
||||
| `message` | 定义结构化数据类型 | ❌ |
|
||||
| `enum` | 定义枚举类型 | ❌ |
|
||||
| `service` / `rpc` | 定义远程调用接口 | ❌（纯数据 Proto 不需要） |
|
||||
|
||||
## Message 消息结构
|
||||
|
||||
Message 是 Protobuf 中最基本的结构化类型，对应 Go 的 `struct`：
|
||||
|
||||
```protobuf
|
||||
message LoginRequest {
|
||||
string username = 1; // 用户名
|
||||
string password = 2; // 密码（生产环境走 TLS 加密通道）
|
||||
bool remember_me = 3; // 记住登录状态
|
||||
}
|
||||
|
||||
message LoginResponse {
|
||||
string token = 1; // JWT Token
|
||||
int64 expire_at = 2; // 过期时间戳（Unix seconds）
|
||||
User profile = 3; // 嵌套消息
|
||||
}
|
||||
|
||||
message User {
|
||||
string id = 1; // UUID 格式
|
||||
string name = 2; // 显示名称
|
||||
string email = 3; // 邮箱地址
|
||||
int32 age = 4; // 年龄
|
||||
bool active = 5; // 是否活跃
|
||||
repeated string roles = 6; // 角色列表（repeated 详见 [02-数据类型详解](./02-数据类型详解.md)）
|
||||
}
|
||||
```
|
||||
|
||||
每个字段包含三部分：**类型 + 字段名 + tag number**。tag number 是字段在二进制 wire format 中的唯一标识——**一旦分配就不会再变**。后续讨论兼容性时会深入理解它的重要性。
|
||||
|
||||
> [!tip] tag number 分配原则
|
||||
> 1. 从 1 开始连续编号，不要跳号
|
||||
> 2. 预留编号区间给未来可能新增的字段（如保留 1-99 给常用字段，100+ 给扩展字段）
|
||||
> 3. 已使用的编号永远不要重用或删除 —— 这会导致序列化数据解析错乱
|
||||
> 4. 具体规则参见 [03-字段编号与前向兼容](./03-字段编号与前向兼容.md)
|
||||
|
||||
> [!question] 为什么不用 JSON 那样的"无编号"设计？
|
||||
> tag number 的核心价值在于**向后兼容**：当你新增字段时，老版本客户端遇到未知的 tag number 会直接跳过该字节块继续解析。如果没有编号，你只能换字段名 —— 但改了名就是 breaking change。Protobuf 的二进制设计让它在小体积、高性能之余，还能优雅地处理版本演进。
|
||||
|
||||
### 字段的默认值行为
|
||||
|
||||
proto3 中所有字段都有明确的默认值：
|
||||
|
||||
| 类型 | 默认值 |
|
||||
|------|--------|
|
||||
| string | `""`（空串） |
|
||||
| bytes | 空字节序列 |
|
||||
| bool | `false` |
|
||||
| numeric (int32, uint64, double…) | `0` 或 `0.0` |
|
||||
| enum | 值为 `0` 的那个枚举值 |
|
||||
| message | 返回"默认实例"（Go 中为零值 struct） |
|
||||
| repeated | 空列表（Go 中为 nil slice） |
|
||||
| map | nil map（Go 中为 nil） |
|
||||
|
||||
```go
|
||||
// Go 中读取默认值 — 无法区分"未设置"和"显式设为零值"
|
||||
var req LoginRequest
|
||||
fmt.Println(req.Username) // "" — 到底是没传还是传了 ""？
|
||||
```
|
||||
|
||||
**这就是 proto3 最著名的陷阱：客户端读不到"未设置"和"设为零值"的区别。** proto2 通过 `has_xxx` 字段解决这个问题，而 proto3 在 3.12+ 引入了 `optional` 关键字（生成时同样附带 `has_xxx`）。不过最通用的实践仍是用包装类型——详见 [02-数据类型详解](./02-数据类型详解.md)。
|
||||
|
||||
## Enum 枚举类型
|
||||
|
||||
枚举用于定义一组命名的整数值：
|
||||
|
||||
```protobuf
|
||||
enum Role {
|
||||
ROLE_UNSPECIFIED = 0; // 未指定（proto3 要求第一个值为 0）
|
||||
ROLE_ADMIN = 1; // 管理员
|
||||
ROLE_EDITOR = 2; // 编辑者
|
||||
ROLE_VIEWER = 3; // 只读者
|
||||
}
|
||||
|
||||
enum Status {
|
||||
STATUS_OFFLINE = 0; // 离线
|
||||
STATUS_ONLINE = 1; // 在线
|
||||
STATUS_BUSY = 2; // 忙碌
|
||||
STATUS_AWAY = 3; // 离开
|
||||
}
|
||||
|
||||
message User {
|
||||
string id = 1;
|
||||
string name = 2;
|
||||
Role role = 3; // 引用枚举类型
|
||||
Status status = 4; // 引用枚举类型
|
||||
}
|
||||
```
|
||||
|
||||
> [!warning] 枚举铁律
|
||||
> 1. **第一个枚举值必须是 0**（通常以 `_UNSPECIFIED` 或 `_UNKNOWN` 结尾），proto3 强制要求
|
||||
> 2. 新增枚举值是向后兼容的，但旧版本客户端收到未知枚举值时会回退到 0（即第一个值）
|
||||
> 3. **不要删除已有枚举值的编号**，否则可能引发不可预期的兼容问题
|
||||
> 4. 枚举值可以打同一个数值做 alias，但需要在 enum 选项里声明 `allow_alias = true`
|
||||
|
||||
## Oneof 排他选择
|
||||
|
||||
当多个字段互斥、每次请求只能填其中一个时，使用 `oneof`：
|
||||
|
||||
```protobuf
|
||||
message UpdateProfileRequest {
|
||||
string id = 1;
|
||||
|
||||
oneof update_field {
|
||||
string name = 2;
|
||||
string email = 3;
|
||||
Role role = 4;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这样保证了 `Name`、`Email`、`Role` 三个字段在序列化时只有一个会出现，节省带宽且语义清晰。在 Go 生成的代码中，oneof 会变成一个接口类型：
|
||||
|
||||
```go
|
||||
type UpdateProfileRequest struct {
|
||||
Id string
|
||||
// 只能设置其中之一
|
||||
UpdateField isUpdateProfileRequest_UpdateField
|
||||
}
|
||||
|
||||
switch req.UpdateField.(type) {
|
||||
case *UpdateProfileRequest_Name:
|
||||
fmt.Println("更新了 name:", req.Name)
|
||||
case *UpdateProfileRequest_Email:
|
||||
fmt.Println("更新了 email:", req.Email)
|
||||
}
|
||||
```
|
||||
|
||||
> [!question] oneof vs 单独字段？什么时候该用 oneof？
|
||||
> 如果你希望业务逻辑保证「每次请求只更新一个字段」，用 oneof 可以让编译器强制约束这个规则。但如果只是"几个可选字段可能同时出现"的场景，反而应该用单独的 field —— oneof 会增加代码复杂度（需要 switch/case 判断哪个被设置了）。**本质区别：oneof 表达的是"二选一或多选一"的互斥关系。**
|
||||
|
||||
## Map 键值映射
|
||||
|
||||
Protobuf 原生支持 key-value 映射，key 只能是整数或字符串类型：
|
||||
|
||||
```protobuf
|
||||
message UserProfile {
|
||||
string id = 1;
|
||||
|
||||
// 标签映射：string → string
|
||||
map<string, string> tags = 2;
|
||||
|
||||
// 统计映射：string → int32
|
||||
map<string, int32> login_count_by_day = 3;
|
||||
}
|
||||
```
|
||||
|
||||
在 Go 中生成的对应类型为 `map[string]string`，**注意默认为 nil**。如果需要确保非 nil，可以用 `repeated` + key-value message 替代。
|
||||
|
||||
## Reserved 保留字段
|
||||
|
||||
当你的 proto 文件 evolve 到新版本，可能需要移除某个字段。**但不能简单地删除——因为旧版本的客户端可能还在发送带有该字段编号的数据，新服务器解析时会把它塞进下一个字段里。** `reserved` 关键字就是为此而生：
|
||||
|
||||
```protobuf
|
||||
message User {
|
||||
reserved 7, 11; // 保留单个编号
|
||||
reserved 9 to 13; // 保留编号区间
|
||||
reserved "username", "telephone"; // 保留字段名
|
||||
|
||||
string id = 1;
|
||||
string name = 2;
|
||||
string nick = 8; // 7 不能用了，这里只能用 >= 14 的编号
|
||||
}
|
||||
```
|
||||
|
||||
> [!example] 典型场景：用户表迭代
|
||||
> v1: `message User { string username = 1; string email = 2; string phone = 3; }`
|
||||
>
|
||||
> v2: 业务发现 `username` 改名了，决定删除并保留编号：
|
||||
> ```protobuf
|
||||
> message User {
|
||||
> reserved 1; // 告诉 protoc：1 号编号作废
|
||||
> string id = 1; // 重新用编号 1 放 id
|
||||
> string email = 2;
|
||||
> string nickname = 3; // 新的昵称字段
|
||||
> }
|
||||
> ```
|
||||
>
|
||||
> 这样如果 v1 客户端发来 `username` 的数据（tag=1），protoc 会自动丢弃而不会错误地填入 `id` 字段。
|
||||
|
||||
> [!tip] reserved 最佳实践
|
||||
> 1. 删除字段时，同时记录被删字号的**原因注释**（可以在 git commit message 里说明，也可以加一行 `// reserved: replaced by xxx at YYYY-MM-DD`）
|
||||
> 2. 不要把正在使用的编号标记为 reserved——编译不过就是最大的提示
|
||||
> 3. 具体兼容策略参见 [03-字段编号与前向兼容](./03-字段编号与前向兼容.md)
|
||||
|
||||
## Package 与 Import
|
||||
|
||||
Protobuf 的 `package` 机制类似于 Go 的 import path，提供命名空间隔离：
|
||||
|
||||
```protobuf
|
||||
// file: user/v1/user.proto
|
||||
package user.v1;
|
||||
|
||||
import "google/protobuf/timestamp.proto"; // Well-Known Type
|
||||
|
||||
message User {
|
||||
string id = 1;
|
||||
string name = 2;
|
||||
google.protobuf.Timestamp created_at = 3;
|
||||
}
|
||||
|
||||
// file: order/v1/order.proto
|
||||
package order.v1;
|
||||
|
||||
import "user/v1/user.proto"; // 引用 user 包的 message
|
||||
|
||||
message Order {
|
||||
string id = 1;
|
||||
user.v1.User buyer = 2; // 跨包引用
|
||||
int64 amount_cents = 3;
|
||||
}
|
||||
```
|
||||
|
||||
> [!tip] import 路径约定
|
||||
> `import "user/v1/user.proto"` 中的路径应当与文件的实际磁盘路径一致（相对于 `protoc -I` 参数指定的目录）。保持一致性是关键。
|
||||
|
||||
## 构建流程总览
|
||||
|
||||
下图展示从 `.proto` 源文件到最终 Go Stub 的完整编译链：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[".proto 源文件"] --> B["protoc 编译器"]
|
||||
B --> C["protoc-gen-go 插件"]
|
||||
B --> D["protoc-gen-go-grpc 插件"]
|
||||
C --> E["pb.go — 消息结构体"]
|
||||
D --> F["_grpc.go — client/server stub"]
|
||||
E --> G["业务层调用 Client / Server"]
|
||||
F --> G
|
||||
|
||||
style A fill:#EAB308,color:#fff
|
||||
style B fill:#3B82F6,color:#fff
|
||||
style C fill:#4FC08D,color:#fff
|
||||
style D fill:#4FC08D,color:#fff
|
||||
style E fill:#A0AEC0,color:#fff
|
||||
style F fill:#A0AEC0,color:#fff
|
||||
```
|
||||
|
||||
> [!info] 工具链细节
|
||||
> `protoc` 负责解析 `.proto` 语法树，各类插件将其翻译成目标语言的代码。Go 生态需要两个插件协同工作：`protoc-gen-go` 生成消息结构体，`protoc-gen-go-grpc` 生成 gRPC 客户端和服务端 Stub。具体配置方法参见 [17-protoc 工具链与 Makefile](../6.%20工程实践篇/17-protoc%20工具链与%20Makefile.md)。
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[hhs/gRPC/README]] — gRPC 知识库全景索引
|
||||
- [[hhs/gRPC/1. Protobuf 基础篇/02-Protobuf 数据类型详解]] — Scalar、Wrapper、Well-Known、Repeated 详细对照
|
||||
- [[hhs/gRPC/1. Protobuf 基础篇/03-Protobuf 字段编号与前向兼容]] — Field Number 分配规则、Reserved、版本演进策略
|
||||
- [[hhs/gRPC/1. Protobuf 基础篇/04-Protobuf Oneof 与包装类型]] — Oneof 高级用法、Google.Protobuf.Value、Any 泛型封装
|
||||
Reference in New Issue
Block a user