all-in-kingsoft/hzh/MS/06-gRPC/README.md

tags, create time

tags	create time
grpc	2026-05-07 16:30

gRPC 知识索引

概述

本目录系统整理 gRPC 的核心知识点，从底层协议到生产实践，由浅入深覆盖 gRPC 的每一个关键领域。与 02-服务治理/服务间通信 中的入门对比不同，这里聚焦于「用了 gRPC 之后」—— 如何设计 Proto、如何编写拦截器、如何处理流式调用、连接怎么管、出错怎么查。

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 万级压测要点

阅读路径

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-服务治理/服务间通信 — gRPC 与 REST 的基础对比及混合通信模式
• 02-服务治理/服务发现/README — Nacos / Consul / K8s Service 深度对比
• 02-服务治理/容错模式/README — 重试、熔断、限流、降级的完整治理
• 02-服务治理/分布式追踪/README — OpenTelemetry 链路追踪
• 02-服务治理/安全机制/README — mTLS、JWT、RBAC