134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
|
---
|
|||
|
|
tags: [grpc]
|
|||
|
|
create time: 2026-05-07 16:30
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# gRPC 知识索引
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
本目录系统整理 **gRPC** 的核心知识点，从底层协议到生产实践，由浅入深覆盖 gRPC 的每一个关键领域。与 [[02-服务治理/05-服务间通信]] 中的入门对比不同，这里聚焦于「用了 gRPC 之后」—— 如何设计 Proto、如何编写拦截器、如何处理流式调用、连接怎么管、出错怎么查。
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph LR
|
|||
|
|
A["01 协议与架构"] --> B["02 Proto设计"]
|
|||
|
|
B --> C["03 RPC模式"]
|
|||
|
|
C --> D["04 拦截器"]
|
|||
|
|
D --> E["05 错误处理"]
|
|||
|
|
E --> F["06 连接管理"]
|
|||
|
|
F --> G["07 最佳实践"]
|
|||
|
|
|
|||
|
|
style A fill:#e3f2fd
|
|||
|
|
style B fill:#fff3e0
|
|||
|
|
style C fill:#c8e6c9
|
|||
|
|
style D fill:#fce4ec
|
|||
|
|
style E fill:#e8f5e9
|
|||
|
|
style F fill:#f3e5f5
|
|||
|
|
style G fill:#ffe0b2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 知识体系
|
|||
|
|
|
|||
|
|
### 1. [[01-协议与架构]] — gRPC 的内部架构
|
|||
|
|
|
|||
|
|
从协议栈层次到 HTTP/2 多路复用原理，回答「为什么 gRPC 更快」。
|
|||
|
|
|
|||
|
|
| 核心内容 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| 协议栈分层 | Application → Generated Stub → gRPC Framework → HTTP/2 → TCP/IP |
|
|||
|
|
| HTTP/2 三特性 | 多路复用、HPACK 头部压缩、二进制分帧 |
|
|||
|
|
| 组件职责 | Channel、Stub、Transport、Picker 的作用域划分 |
|
|||
|
|
|
|||
|
|
> [!tip] 理论基础篇
|
|||
|
|
> 建议先读此篇，建立正确认知后再深入配置细节。
|
|||
|
|
|
|||
|
|
### 2. [[02-Proto设计]] — Proto 文件设计规范
|
|||
|
|
|
|||
|
|
如何写出经得起演进的 `.proto` 文件——这是最容易踩坑也最容易被忽视的部分。
|
|||
|
|
|
|||
|
|
| 核心内容 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| Oneof / Map / Well-Known Types | Proto3 进阶类型用法 |
|
|||
|
|
| 版本管理 | 向前兼容三大铁律与决策速查表 |
|
|||
|
|
| reserved 机制 | 锁定已删除字段编号的安全声明 |
|
|||
|
|
| 命名约定 | package / service / message / field 统一规范 |
|
|||
|
|
|
|||
|
|
### 3. [[03-RPC模式]] — 四种 RPC 调用模式详解
|
|||
|
|
|
|||
|
|
| 模式 | 客户端消息数 | 服务端消息数 | 典型场景 |
|
|||
|
|
|------|------------|------------|---------|
|
|||
|
|
| Unary（普通） | 1 | 1 | CRUD 常规操作 |
|
|||
|
|
| Server Streaming | 1 | N | 列表查询、日志流拉取 |
|
|||
|
|
| Client Streaming | N | 1 | 批量写入、大文件分块上传 |
|
|||
|
|
| Bidi Streaming | N | M | 聊天室、实时协作、行情推送 |
|
|||
|
|
|
|||
|
|
> [!question] 选型思考
|
|||
|
|
>
|
|||
|
|
> 实时订单状态推送：用双向流还是 WebSocket？gRPC 强类型契约 vs 浏览器原生支持的权衡在哪里？
|
|||
|
|
|
|||
|
|
### 4. [[04-拦截器]] — Interceptor 与上下文传播
|
|||
|
|
|
|||
|
|
gRPC 的切面编程能力：鉴权、日志、指标采集、重试决策都通过 interceptor 实现。
|
|||
|
|
|
|||
|
|
| 核心内容 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| 拦截器链架构 | 客户端链 vs 服务端链的执行顺序 |
|
|||
|
|
| Go 链式封装 | `chainUnaryInterceptors` 解决多拦截器叠加问题 |
|
|||
|
|
| Context Propagation | metadata 传递 trace ID、user ID 等上下文信息 |
|
|||
|
|
| OpenTelemetry 集成 | W3C Trace Context 自动注入 |
|
|||
|
|
|
|||
|
|
### 5. [[05-错误处理]] — 状态码规范与客户端降级
|
|||
|
|
|
|||
|
|
| 核心内容 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| 16 个标准状态码 | 按 4xx / 5xx / 未实现分类的决策图 |
|
|||
|
|
| status.Error vs fmt.Errorf | 为什么必须用 `codes.*` 做返回值 |
|
|||
|
|
| Status Details | 带结构化详情的错误响应（BadRequest / RetryInfo） |
|
|||
|
|
| 优雅降级 | 根据状态码选择重试、降级或直接报错 |
|
|||
|
|
|
|||
|
|
### 6. [[06-连接管理]] — Keepalive、负载均衡与服务发现
|
|||
|
|
|
|||
|
|
| 核心内容 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| Keepalive 策略 | ping 间隔、超时检测、MaxConnectionAge 平滑退役 |
|
|||
|
|
| 负载均衡 Picker | pick_first / round_robin / weighted_round_robin 选型 |
|
|||
|
|
| Name Resolver | DNS / K8s / Eureka 等服务发现后端接入 |
|
|||
|
|
|
|||
|
|
### 7. [[07-最佳实践]] — 生产部署 checklist
|
|||
|
|
|
|||
|
|
| 核心内容 | 说明 |
|
|||
|
|
|---------|------|
|
|||
|
|
| 重试策略 | 指数退避 + 幂等性约束 + retryableStatusCodes 配置 |
|
|||
|
|
| TLS / mTLS | 服务间信任基础，Istio Sidecar 透明加密 |
|
|||
|
|
| Buf 工具链 | buf generate / buf.lock CI 集成 |
|
|||
|
|
| 性能调优 | Window Size、gzip 取舍、QPS 万级压测要点 |
|
|||
|
|
|
|||
|
|
## 阅读路径
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph LR
|
|||
|
|
Index["本文档<br/>（索引）"] --> Arch["01 协议与架构"]
|
|||
|
|
Arch --> Proto["02 Proto设计"]
|
|||
|
|
Proto --> RPCC["03 RPC模式"]
|
|||
|
|
RPCC --> Intc["04 拦截器"]
|
|||
|
|
Intc --> Err["05 错误处理"]
|
|||
|
|
Err --> Conn["06 连接管理"]
|
|||
|
|
Conn --> Prod["07 最佳实践"]
|
|||
|
|
|
|||
|
|
style Index fill:#fff9c4
|
|||
|
|
style Arch fill:#e3f2fd
|
|||
|
|
style Prod fill:#ffe0b2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- **推荐路径**：按编号顺序逐篇阅读，每篇独立成篇也可跳读
|
|||
|
|
- **快速上手**：直接读 [[03-RPC模式]] 和 [[07-最佳实践]]，掌握核心用法后按需补其他篇
|
|||
|
|
- **遇到问题时**：优先定位到对应子篇，不必通读全文
|
|||
|
|
|
|||
|
|
## 关联笔记
|
|||
|
|
|
|||
|
|
- [[02-服务治理/05-服务间通信]] — gRPC 与 REST 的基础对比及混合通信模式
|
|||
|
|
- [[02-服务治理/04-服务发现]] — Nacos / Consul / K8s Service 深度对比
|
|||
|
|
- [[02-服务治理/06-容错模式]] — 重试、熔断、限流、降级的完整治理
|
|||
|
|
- [[02-服务治理/03-分布式追踪]] — OpenTelemetry 链路追踪
|
|||
|
|
- [[02-服务治理/02-安全机制]] — mTLS、JWT、RBAC
|