all-in-kingsoft/hhs/gRPC/README.md

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

## 核心架构

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

## 学习路径建议

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

## 关联笔记