Init

hhs/MS/06-gRPC/README.md

@@ -0,0 +1,133 @@
+---
+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