wonder/cs-note

Fork 0

Files

T

wonder 30d312ac35 Init

2026-05-24 11:42:38 +08:00

15 KiB

Raw Blame History

tags, create time, update time

RPC 调用模式总览

概述

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

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

RPC 模式全景图

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 数据流示意图

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 端点

// 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，但要注意三件事：

设置合理的 context timeout：context.WithTimeout，避免无限期等待

HTTP/2 ping keepalive：gRPC 默认会发送 keepalive ping 防止代理（Nginx/LB）因"连接空闲"而断开

是否真的需要阻塞等待：如果是异步任务（如报表生成），更好的做法是——Unary 提交任务 + 轮询/回调通知结果，而非让一个 RPC 连接挂 30 秒。

Streaming 并不会延长超时时间——超时由 context 控制，与使用哪种 RPC 模式无关。

Server Streaming RPC（服务端流）

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

经典场景：

实时通知推送
大列表分批返回
日志/事件流订阅

rpc Subscribe(SubscribeRequest) returns (stream Event);

// 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 实际用到的即可，不必照抄。

// 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 在所有数据发送完毕后返回一个响应。

经典场景：

大批量数据上传
文件分片聚合处理
批量日志采集

rpc Upload(stream FileChunk) returns (UploadResult);

// 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] 黄金法则

只有连接建立阶段的 dial/send 错误才能用 log.Fatal——handler 内部永远用 return

io.EOF 不是错误——它表示对方完成了发送方向，是正常退出信号

每次 stream recv/send 都要检查 error，哪怕代码看起来"不可能失败"

context timeout 对所有模式生效——Streaming 不会因为"流式"就自动获得更长超时

Bidirectional Streaming RPC（双向流）

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

经典场景：

聊天室
实时协作编辑
游戏状态同步

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

// 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、背压和心跳保活。

// 背压控制：如果 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 配置示例
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 包维持连接。

模式选型决策指南

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

15 KiB Raw Blame History Unescape Escape

RPC 调用模式总览

概述

RPC 模式全景图

RPC 数据流示意图

Unary RPC（普通调用）

Server Streaming RPC（服务端流）

Client Streaming RPC（客户端流）

错误处理模式总结

Bidirectional Streaming RPC（双向流）

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

模式选型决策指南

性能对比

与 HTTP 方法的映射类比

关联笔记

15 KiB

Raw Blame History