113 lines
5.4 KiB
Markdown
113 lines
5.4 KiB
Markdown
---
|
||
tags: [gRPC, Protobuf, Go, RPC, Microservice]
|
||
create time: 2026-05-11 15:30
|
||
---
|
||
|
||
# gRPC & Protobuf 知识库
|
||
|
||
## 概述
|
||
|
||
gRPC 是 Google 开源的高性能 RPC 框架，基于 HTTP/2 和 Protobuf 序列化，是现代微服务通信的事实标准。本知识库从 Protobuf 消息定义入手，贯穿服务端、客户端、流式通信、中间件链到生产级工程实践。
|
||
|
||
> [!question] gRPC vs REST？什么时候选 gRPC？
|
||
> gRPC 适合内部服务间通信：强类型契约（Protobuf）、低延迟、双向流；REST 更适合对外 API：人类可读、浏览器原生支持、缓存友好。二者并非互斥——常见的做法是用 API Gateway 将 REST 转为 gRPC。
|
||
|
||
## 目录索引
|
||
|
||
### 1. Protobuf 基础篇
|
||
|
||
- **[01-Protobuf 语法与消息定义](./1. Protobuf 基础篇/01-Protobuf 语法与消息定义.md)** — `.proto` 文件结构、message / enum / oneof / map 字段、package 与 import
|
||
- **[02-数据类型详解](./1. Protobuf 基础篇/02-数据类型详解.md)** — Scalar Types、Wrapper Types、Well-Known Types、Repeated 与 Packaged 语义
|
||
- **[03-字段编号与前向兼容](./1. Protobuf 基础篇/03-字段编号与前向兼容.md)** — Field Number 分配规则、Reserved、版本演进策略、向后/向前兼容原理
|
||
- **[04-Oneof 与包装类型](./1. Protobuf 基础篇/04-Oneof 与包装类型.md)** — Oneof 排他选择、GoogleProtobuf.Value 万能类型、Any 泛型封装
|
||
|
||
### 2. gRPC 核心篇
|
||
|
||
- **[05-RPC 调用模式总览](./2. gRPC 核心篇/05-RPC 调用模式总览.md)** — Unary、Server Streaming、Client Streaming、Bidirectional Streaming 四种模式对比
|
||
- **[06-Service 定义与代码生成](./2. gRPC 核心篇/06-Service 定义与代码生成.md)** — `.proto` Service/Dialect 语法、protoc 插件体系、Go Stub 生成机制
|
||
- **[07-HTTP2 传输原理](./2. gRPC 核心篇/07-HTTP2 传输原理.md)** — HTTP/2 Frame、Stream Multiplexing、Header Compression（HPACK）、Flow Control
|
||
- **↳ [07-RPC 设计与 RESTful 对应](./2. gRPC 核心篇/07-HTTP2 传输原理/07-RPC 设计与 RESTful 对应.md)** — PUT/PATCH/POST 语义映射、Partial Update 的 PATCH + FieldMask 方案
|
||
|
||
### 3. 服务端实现
|
||
|
||
- **[08-Server 搭建与注册](./3. 服务端实现/08-Server 搭建与注册.md)** — grpc.NewServer、服务注册、多端口监听、Reflection
|
||
- **[09-Streaming Handler](./3. 服务端实现/09-Streaming Handler.md)** — Send / Recv 循环模式、Context 超时处理、优雅关闭流程
|
||
- **[10-健康检查与反射](./3. 服务端实现/10-健康检查与反射.md)** — Health Check v1 API、ServerReflection、调试接入
|
||
|
||
### 4. 客户端开发
|
||
|
||
- **[11-Client 连接与 Dial](./4. 客户端开发/11-Client 连接与 Dial.md)** — grpc.Dial / WithInsecure / TransportCredentials、Dial Options 精选
|
||
- **[12-Call Options 与 Context](./4. 客户端开发/12-Call Options 与 Context.md)** — WithTimeout / WithMeta / Retry Policy、Context 取消传播
|
||
- **[13-Streaming Client](./4. 客户端开发/13-Streaming Client.md)** — 三种 Stream 的 Client 端遍历模式、recv 错误分类
|
||
|
||
### 5. 中间件与拦截器
|
||
|
||
- **[14-Unary 与 Stream 拦截器](./5. 中间件与拦截器/14-Unary 与 Stream 拦截器.md)** — Chain 链构建、interceptor.Handler 签名、上下文传递
|
||
- **[15-元数据与鉴权](./5. 中间件与拦截器/15-元数据与鉴权.md)** — MD 读取/注入、Token 校验、TLS mTLS、per-RPC Credentials
|
||
- **[16-日志与链路追踪](./5. 中间件与拦截器/16-日志与链路追踪.md)** — 请求耗时统计、Trace ID 透传、OpenTelemetry 集成
|
||
|
||
### 6. 工程实践篇
|
||
|
||
- **[17-protoc 工具链与 Makefile](./6. 工程实践篇/17-protoc 工具链与 Makefile.md)** — protoc-gen-go / protoc-gen-go-grpc 版本匹配、go generate、多语言生成
|
||
- **[18-模块拆分与 proto 规范](./6. 工程实践篇/18-模块拆分与 proto 规范.md)** — proto 目录结构、命名约定、import 路径规范、linter 集成
|
||
- **[19-跨语言兼容测试](./6. 工程实践篇/19-跨语言兼容测试.md)** — Go ↔ Java ↔ Node 互通、默认值差异、枚举一致性
|
||
- **[20-性能优化与压测](./6. 工程实践篇/20-性能优化与压测.md)** — 序列化大小调优、连接池复用、Compression、gRPC-Bench 压测手法
|
||
|
||
## 核心架构
|
||
|
||
```mermaid
|
||
graph TB
|
||
subgraph "应用层"
|
||
A["Handler 业务逻辑"]
|
||
B["Interceptor Chain"]
|
||
C["Metadata / Auth / Trace"]
|
||
end
|
||
|
||
subgraph "gRPC 层"
|
||
D["Server / Client"]
|
||
E["Stream Controller"]
|
||
F["Call Options"]
|
||
end
|
||
|
||
subgraph "传输层"
|
||
G["HTTP/2 Framing"]
|
||
H["HPACK Header"]
|
||
I["Flow Control"]
|
||
end
|
||
|
||
subgraph "数据层"
|
||
J["Protobuf Serialize"]
|
||
K["Message Definition"]
|
||
L["Enum / Oneof / Map"]
|
||
end
|
||
|
||
A --> B --> D --> G --> J
|
||
B --> C
|
||
D --> E --> F
|
||
J --> K --> L
|
||
|
||
style A fill:#00B6BC,color:#fff
|
||
style D fill:#4FC08D,color:#fff
|
||
style G fill:#FF6B35,color:#fff
|
||
style J fill:#A0AEC0,color:#fff
|
||
```
|
||
|
||
## 学习路径建议
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
P1["Protobuf 语法"] --> P2["gRPC 核心概念"]
|
||
P2 --> P3["服务端开发"]
|
||
P2 --> P4["客户端开发"]
|
||
P3 --> P5["中间件与拦截器"]
|
||
P4 --> P5
|
||
P5 --> P6["工程实践"]
|
||
P5 --> P7["性能优化"]
|
||
|
||
style P1 fill:#00D866,color:#fff
|
||
style P6 fill:#FF9F43,color:#000
|
||
style P7 fill:#EE5A24,color:#fff
|
||
```
|
||
|
||
## 关联笔记
|