---
tags: [gRPC, RPC, Streaming, Go, Microservice, API Design]
create time: 2026-05-11 16:40
update time: 2026-05-13 00:00
---

# RPC 调用模式总览

## 概述

gRPC 提供四种 RPC 调用模式，从最简单的请求-响应到完全的双向流。选择合适的模式是设计高性能 API 的第一步。搞懂它们的区别，你就知道什么时候该用简单调用、什么时候需要双向通信。

> [!question] 如果只选一种模式能走天下吗？
> 技术上可以——Unary RPC 确实能解决几乎所有问题。但强行用 Unary 实现实时推送，意味着你要轮询（polling），这会产生大量无效请求和延迟。模式选择本质上是在"延迟 vs 资源消耗"之间做 tradeoff。

## RPC 模式全景图

```mermaid
flowchart LR
    U["Unary\n一问一答"] --> S1["简单 · 阻塞 · 一次往返"]
    SS["Server Stream\n一问多答"] --> S2["广播式 · 服务端推送"]
    CS["Client Stream\n多问一答"] --> S3["收集式 · 分批上传"]
    BD["BiDi Stream\n多问多答"] --> S4["全双工 · 独立收发"]

    style U fill:#00B6BC,color:#fff
    style SS fill:#00D866,color:#fff
    style CS fill:#4FC3F7,color:#fff
    style BD fill:#EE5A24,color:#fff
```

## RPC 数据流示意图

```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server

    rect rgba(0, 182, 188, 0.1)
        Note over C,S: Unary — 一次请求，一次响应
        C->>S: request
        S-->>C: response
    end

    rect rgba(0, 216, 102, 0.1)
        Note over C,S: Server Stream — 一次请求，多次响应
        C->>S: request
        S-->>C: response 1
        S-->>C: response 2
        S-->>C: ... n (EOF)
    end

    rect rgba(79, 195, 247, 0.1)
        Note over C,S: Client Stream — 多次请求，一次响应
        C->>S: chunk 1
        C->>S: chunk 2
        C->>S: ... n (done)
        S-->>C: result
    end

    rect rgba(238, 90, 36, 0.1)
        Note over C,S: BiDi Stream — 双向独立通信
        C->>S: msg 1
        S-->>C: reply 1
        C->>S: msg 2
        S-->>C: reply 2
    end
```

## Unary RPC（普通调用）

最经典、最常见的模式，等同于 REST 的 request-response。

**特点：**
- 一次客户端请求，一次服务端响应
- 简单、易调试、可直接映射 HTTP GET/POST
- 适合：CRUD 操作、短查询、标准 API 端点

```go
// proto 定义
// rpc GetUser(GetUserRequest) returns (GetUserResponse);

// Client side
func main() {
    conn, _ := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    defer conn.Close()
    client := pb.NewUserServiceClient(conn)

    resp, err := client.GetUser(context.Background(), &pb.GetUserRequest{Id: 42})
    if err != nil {
        log.Fatal(err) // error comes from transport or server handler
    }
    fmt.Println(resp.Name)
}

// Server side
type Server struct {
    pb.UnimplementedUserServiceServer
}

func (s *Server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
    user := fetchFromDB(req.GetId())
    return &pb.GetUserResponse{Name: user.Name}, nil
}
```

**思考题：**如果一个接口需要 30 秒才能返回结果，你应该用 Unary 还是其他模式？（提示：考虑超时和连接的持有时间）

> [!answer]+ 参考答案
> **可以用 Unary，但要注意三件事：**
>
> 1. **设置合理的 context timeout**：`context.WithTimeout`，避免无限期等待
> 2. **HTTP/2 ping keepalive**：gRPC 默认会发送 keepalive ping 防止代理（Nginx/LB）因"连接空闲"而断开
> 3. **是否真的需要阻塞等待**：如果是异步任务（如报表生成），更好的做法是——Unary 提交任务 + 轮询/回调通知结果，而非让一个 RPC 连接挂 30 秒。
>
> Streaming 并不会延长超时时间——超时由 context 控制，与使用哪种 RPC 模式无关。

## Server Streaming RPC（服务端流）

Client 发一个请求，Server 持续返回多个响应。

**经典场景：**
- 实时通知推送
- 大列表分批返回
- 日志/事件流订阅

```protobuf
rpc Subscribe(SubscribeRequest) returns (stream Event);
```

```go
// Server side - 持续发送事件（注意不要用 log.Fatal，会杀死整个进程）
func (s *Server) Subscribe(req *pb.SubscribeRequest, stream pb.UserService_SubscribeServer) error {
    for _, event := range s.watchEvents(req.Topic) {
        if err := stream.Send(&pb.Event{Data: event}); err != nil {
            return err // channel closed or context canceled
        }
    }
    return nil
}
```

> [!note] import 提示
> 流式示例中用到以下包：`context`, `fmt`, `io`, `log`.
> 每个文件只需 import 实际用到的即可，不必照抄。

```go
// Client side - 遍历接收事件（生产环境建议加 context timeout 和 recover）
func subscribeEvents(client pb.UserServiceClient, topic string) error {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()

    stream, err := client.Subscribe(ctx, &pb.SubscribeRequest{Topic: topic})
    if err != nil {
        return err // dial failed — 上层 main 可以做 Fatal
    }
    defer func() {
        if r := recover(); r != nil {
            log.Printf("panic recovered: %v", r)
        }
    }()
    for {
        event, err := stream.Recv()
        if err == io.EOF {
            break // server finished sending
        }
        if err != nil {
            log.Printf("stream error: %v", err) // ⚠️ 这里用 return/log，不能用 Fatal
            return err
        }
        fmt.Printf("received: %s\n", event.Data)
    }
    return nil
}
```

> [!tip] Context Cancel 与 Recv 的关系
> Client 仍可通过 cancel 随时中断流——服务端 `Recv()` 将返回一个 context canceled 错误。这也是调试流式问题时最容易忽略的一点：**不是 Server 主动关了连接，而是 Client 放弃了**。

## Client Streaming RPC（客户端流）

Client 持续发送多个请求，Server 在所有数据发送完毕后返回一个响应。

**经典场景：**
- 大批量数据上传
- 文件分片聚合处理
- 批量日志采集

```protobuf
rpc Upload(stream FileChunk) returns (UploadResult);
```

```go
// Client side - 流式发送数据分片（注意 defer CleanupSend 做资源清理）
func uploadFile(client pb.FileServiceClient, chunks [][]byte) error {
    ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
    defer cancel()

    stream, err := client.Upload(ctx)
    if err != nil {
        return err
    }
    defer func() {
        if r := recover(); r != nil {
            stream.CloseSend() // panic 时确保 send 方向关闭
        }
    }()
    for _, chunk := range chunks {
        if err := stream.Send(&pb.FileChunk{Data: chunk}); err != nil {
            return err
        }
    }
    result, err := stream.CloseAndRecv() // 结束发送，获取最终结果
    if err != nil {
        return err
    }
    fmt.Printf("upload complete, size: %d\n", result.Size)
    return nil
}

// Server side - 逐块接收后聚合（用 return 而非 Fatal，让 gRPC 框架处理错误上报）
func (s *Server) Upload(stream pb.FileService_UploadServer) error {
    var buffer bytes.Buffer
    for {
        chunk, err := stream.Recv()
        if err == io.EOF {
            break // client closed send direction
        }
        if err != nil {
            return err
        }
        buffer.Write(chunk.Data)
    }
    result, err := stream.SendAndReceive(&pb.UploadResult{Size: int32(buffer.Len())})
    return err
}
```

> [!tip] CloseAndRecv vs CloseSend + Recv
> `CloseAndRecv()` 是 Client Stream 中的便捷方法——它同时完成"关闭发送方向"和"读取响应"两步。等价于先 `stream.CloseSend()` 再 `stream.Recv()`。在 Client Stream 中两者效果相同，但 `CloseAndRecv` 更简洁、出错概率更低。

**优势：**内存友好——不需要一次性 load 全部数据到内存中，每个 chunk 独立收发。

## 错误处理模式总结

四种模式共用同一套错误处理原则：

| 场景 | Unary | Server Stream | Client Stream | BiDi Stream |
|------|:-----:|:-------------:|:-------------:|:-----------:|
| **Stream 创建失败（Client）** | — | `log.Fatal` ✅ | `log.Fatal` ✅ | `log.Fatal` ✅ |
| **Recv 返回 io.EOF** | — | `break` ✅ | `break` ✅ | `close(done)` ✅ |
| **Recv 返回其他 error** | `return/log` ✅ | `return/log` ✅ | `return/log` ✅ | 分别处理两端 ✅ |
| **Send 返回 error** | — | `return` ✅ | `return` ✅ | `return` ✅ |
| **Context canceled** | RPC 自动取消 | 同 error ✅ | 同 error ✅ | `select <-ctx.Done()` ✅ |

> [!important] 黄金法则
> 1. **只有连接建立阶段的 dial/send 错误才能用 `log.Fatal`**——handler 内部永远用 return
> 2. **io.EOF 不是错误**——它表示对方完成了发送方向，是正常退出信号
> 3. **每次 stream recv/send 都要检查 error**，哪怕代码看起来"不可能失败"
> 4. **context timeout 对所有模式生效**——Streaming 不会因为"流式"就自动获得更长超时

## Bidirectional Streaming RPC（双向流）

Client 和 Server 可以同时独立地发送消息，是全双工通信。

**经典场景：**
- 聊天室
- 实时协作编辑
- 游戏状态同步

```protobuf
rpc Chat(stream ChatMessage) returns (stream ChatMessage);
```

```go
// Server side - 转发逻辑，两端各自独立循环（增加 context cancel 处理）
func (s *Server) Chat(stream pb.ChatService_ChatServer) error {
    ctx := stream.Context()
    done := make(chan struct{})

    // goroutine 1: 读取客户端消息
    go func() {
        for {
            msg, err := stream.Recv()
            if err == io.EOF {
                close(done)
                return
            }
            if err != nil {
                log.Printf("recv error: %v", err)
                return
            }
            // 广播给其他 connected clients...
            s.broadcast(msg)
        }
    }()

    // goroutine 2: 定时推送服务器消息
    ticker := time.NewTicker(5 * time.Second)
    defer ticker.Stop()
    for {
        select {
        case <-ctx.Done():
            return ctx.Err() // client disconnected → clean exit
        case <-done:
            return nil
        case t := <-ticker.C:
            if sendErr := stream.Send(&pb.ChatMessage{Text: fmt.Sprintf("heartbeat: %s", t)}); sendErr != nil {
                log.Printf("send heartbeat error: %v", sendErr)
                return sendErr
            }
        }
    }
}
```

**关键点：**
- 两端的 Send 和 Recv 是独立的——一端 Recv 完（EOF）不影响另一端继续 Send
- 必须用两个 goroutine 分别处理 recv 和 send 循环——单线程无法同时读写
- `io.EOF` 只表示对方的关闭，不代表己方也要停止发送
- **Context Cancel 优先级高于 EOF**：Client 断开连接时，`stream.Context().Done()` 先触发。生产代码中永远要检查它
- 建议在 handler 中使用 `defer stream.SendAndClose(...)` 或 defer 清理逻辑确保资源释放

### 背压与心跳（生产级要点）

BiDi Stream 在长连接场景下，有三个必须考虑的问题：context cancel、io.EOF、背压和心跳保活。

```go
// 背压控制：如果 Send 堆积过多，buffer 满时自动阻塞发送端
func (s *Server) handleStream(stream pb.ChatService_ChatServer) error {
    sendCh := make(chan *pb.ChatMessage, 100) // buffer size = 100
    go func() {
        for msg := range sendCh {
            // Send 是阻塞的——buffer 满时自动触发背压
            if err := stream.Send(msg); err != nil {
                return // connection lost, goroutine exits cleanly
            }
        }
    }()
    // ...recv loop 往 sendCh 里塞消息即可
}
```

> [!tip] 背压原理
> gRPC 的 `Send()` 是**有缓冲阻塞**的。当 internal buffer 写满时，发送端会自动 pause——这就是 HTTP/2 Flow Control 提供的天然背压机制，不需要手动实现。但你应该设置合理的 buffer size，过大浪费内存，过小影响吞吐。建议从 100 起步，根据实际监控调整。

> [!note] Keepalive 配置示例
> ```go
> conn, _ := grpc.Dial(addr,
>     grpc.WithKeepaliveParams(keepalive.ClientParameters{
>         Time:                10 * time.Second, // ping interval
>         Timeout:             20 * time.Second, // wait for ping ack
>         PermitWithoutStream: true,             // 即使无活跃 RPC 也发 ping
>     }),
> )
> ```
> 这对穿越 Nginx / AWS ALB 等负载均衡器至关重要——它们通常会对空闲连接执行 TCP idle timeout 断开。服务端也需要配置类似的 keepalive，否则 Server→Client 方向的心跳缺失会导致 Client 误判连接死亡。

> [!warning] 复杂度警告
> BiDi Streaming 是最强大但也最容易出错的模式。你必须同时处理：context cancel、io.EOF、网络异常、心跳保活、背压（backpressure）。生产环境中除非必要，否则优先考虑其他三种模式。

> [!question] 为什么需要 PermitWithoutStream?
> 因为某些场景中连接处于"空闲状态"——没有正在进行的 RPC 调用——此时 LB 会因为检测到 TCP 层无任何流量而主动断开连接。设置 `PermitWithoutStream: true` 确保即使没有活跃流，gRPC 仍会持续发送 ping 包维持连接。

## 模式选型决策指南

```mermaid
flowchart TD
    Start["是否需要\n实时交互?"] -->|否| Simple["单次请求?"]
    Start -->|是| BiDi["高频交互?"]

    Simple -->|是| U["Unary RPC\n最简单 ⭐"]
    Simple -->|否| SS["Server Stream\n一次请求多次返回"]

    BiDi -->|是| BD["Bidirectional Stream\n全双工通信 🔥"]
    BiDi -->|否| CS["数据量超大?"]

    CS -->|是| CB["Client Stream\n分批上传"]
    CS -->|否| SS

    style U fill:#00D866,color:#fff
    style BD fill:#FF6B35,color:#fff
```

> [!tip] 选型原则
> **默认选 Unary**。只有在三种情况下考虑其他模式：(1) 需要实时推送——用 Server Stream；(2) 数据量大且需流式发送——用 Client Stream；(3) 双向高频交互——用 BiDi Stream。永远不要为了炫技而选择更复杂的模式。

## 性能对比

| 维度 | Unary | Server Stream | Client Stream | BiDi Stream |
|------|-------|---------------|---------------|-------------|
| **RTT** | 1 | 1+N | M+1 | M+N |
| **实现复杂度** | ⭐ | ⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |
| **内存占用** | 高（一次加载完整响应） | 低（逐条处理） | 低（分片发送） | 低（双向流控） |
| **超时风险** | 高（连接全程持有一直到完整响应） | 低（请求已发出，可取消） | 中（大文件需合理 timeout） | 中（长连接需 keepalive） |
| **典型场景** | CRUD、短查询 | 订阅推送、列表分页 | 大文件上传、批量采集 | 聊天室、实时协作、游戏同步 |

## 与 HTTP 方法的映射类比

| gRPC 模式 | 近似的 HTTP 模式 |
|-----------|-----------------|
| Unary | GET / POST |
| Server Stream | SSE (Server-Sent Events) |
| Client Stream | Multipart Upload |
| BiDi Stream | WebSocket |

> [!note] 类比 ≠ 等价
> 这些只是功能层面的类比。gRPC 是二进制协议且基于 HTTP/2，行为特征和 HTTP 层语义有本质差异——比如 HTTP/2 的多路复用让 gRPC Stream 比 WebSocket 更高效。

## 关联笔记
- [[hhs/gRPC/2. gRPC 核心篇/06-Service 定义与代码生成]]
- [[hhs/gRPC/3. 服务端实现/09-Streaming Handler]]