---
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