cs-note/hhs/gRPC

tags, create time

tags	create time
gRPC Protobuf Go RPC Microservice	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 压测手法

核心架构

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

学习路径建议

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

关联笔记