198 lines
6.2 KiB
Markdown
198 lines
6.2 KiB
Markdown
---
|
|
tags: [grpc, rpc-patterns, streaming, bidirectional]
|
|
create time: 2026-05-07 16:00
|
|
---
|
|
|
|
# RPC 模式详解
|
|
|
|
## 概述
|
|
|
|
gRPC 支持 **四种 RPC 调用模式**，每种对应不同的客户端/服务端消息交互时序。理解它们不仅仅是记住名词，更要掌握「什么时候该用哪种」以及「各种模式的坑在哪里」。
|
|
|
|
> [!question] 先看一个实际场景
|
|
>
|
|
> 你需要实现一个订单列表功能：用户在前端点击按钮 → 后端查询数据库 → 一次返回 100 条订单记录。
|
|
>
|
|
> 你会选择哪种 RPC 模式？如果用 Unary 一行行发回来会怎样？
|
|
|
|
Unary 模式下这 100 条记录会变成 100 次独立的 HTTP/2 Stream，虽然 HTTP/2 支持多路复用，但这依然浪费了宝贵的 Stream 标识符空间。更好的方式是用 **Server Streaming** 在一个 Stream 内批量发送。
|
|
|
|
## Unary —— 普通请求/响应
|
|
|
|
最常见的调用方式，一问一答：
|
|
|
|
```go
|
|
// client side
|
|
resp, err := client.GetOrder(ctx, &pb.GetOrderRequest{Id: "ORD-001"})
|
|
if err != nil {
|
|
// handle error
|
|
}
|
|
|
|
// server side
|
|
func (s *orderServer) GetOrder(ctx context.Context, req *pb.GetOrderRequest) (*pb.Order, error) {
|
|
return s.store.Get(req.GetId())
|
|
}
|
|
```
|
|
|
|
适用场景：CRUD 常规操作、单次计算任务、短平快的查询。这是占 gRPC 流量 **90%+** 的模式。
|
|
|
|
## Server Streaming —— 服务端流式
|
|
|
|
服务端一次性返回多个结果，适合批量查询或推送：
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant C as Client
|
|
participant S as Server
|
|
|
|
C->>S: ListOrders(request)
|
|
S-->>C: Order[1]
|
|
S-->>C: Order[2]
|
|
S-->>C: Order[3]
|
|
S-->>C: EOF
|
|
|
|
Note right of C: 客户端收到完整列表
|
|
```
|
|
|
|
```go
|
|
func (s *orderServer) ListOrders(req *pb.ListOrdersRequest, stream pb.OrderService_ListOrdersServer) error {
|
|
orders := s.store.ListAll()
|
|
for _, o := range orders {
|
|
if err := stream.Send(o); err != nil {
|
|
return err
|
|
}
|
|
}
|
|
return nil
|
|
}
|
|
```
|
|
|
|
> [!warning] 服务端必须主动关闭流
|
|
>
|
|
> 如果服务端 `Send` 循环中没有遇到错误或主动返回 `nil`，Stream 永远不会结束，客户端将永远阻塞在 `Recv()`。务必确保所有路径都会退出循环或返回错误。
|
|
|
|
## Client Streaming —— 客户端流式
|
|
|
|
客户端连续发送多条消息，服务端最后返回聚合结果。适合大数据上传：
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant C as Client
|
|
participant S as Server
|
|
|
|
C->>S: BatchRecord[1]
|
|
C->>S: BatchRecord[2]
|
|
C->>S: BatchRecord[3]
|
|
C->>S: CloseSend()
|
|
|
|
Note right of S: 收集所有数据
|
|
S-->>C: BatchResult{count: 3}
|
|
```
|
|
|
|
```go
|
|
func (s *orderServer) UploadLogs(stream pb.OrderService_UploadLogsServer) error {
|
|
var count int32
|
|
for {
|
|
log, err := stream.Recv()
|
|
if err == io.EOF {
|
|
break
|
|
}
|
|
if err != nil {
|
|
return err
|
|
}
|
|
s.store.Log(log.Message)
|
|
count++
|
|
}
|
|
return stream.SendAndClose(&pb.UploadResult{Count: count})
|
|
}
|
|
```
|
|
|
|
适用场景：批量写入日志、文件分块上传、批量创建记录。注意要在客户端控制流速，避免一次性塞爆缓冲区。
|
|
|
|
## Bidi Streaming —— 双向流式
|
|
|
|
双方各自独立发送流，完全异步。**最适合实时场景**（聊天、行情推送、协同编辑）：
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant CS as Client Stream
|
|
participant SS as Server Stream
|
|
|
|
CS->>SS: Msg[1]: "Hello"
|
|
SS->>CS: Reply[1]: "Hi!"
|
|
CS->>SS: Msg[2]: "What's up?"
|
|
SS->>CS: Reply[2]: "Not much"
|
|
CS->>SS: Msg[3]...
|
|
SS->>CS: Reply[3]...
|
|
CS--)SS: Cancel
|
|
SS--)CS: Cancel
|
|
```
|
|
|
|
```go
|
|
// 实战示例：WebSocket-like 的实时通知推送
|
|
func (s *server) SubscribeNotifications(
|
|
req *pb.SubscribeRequest,
|
|
stream pb.NotificationService_SubscribeServer,
|
|
) error {
|
|
// 注册订阅
|
|
notifier.Register(stream.Context().Done(), func() {
|
|
stream.Send(&pb.Notification{})
|
|
})
|
|
<-stream.Context().Done()
|
|
return stream.Context().Err()
|
|
}
|
|
```
|
|
|
|
> [!question] 选型思考
|
|
>
|
|
> 假设你要实现一个实时订单状态推送功能（前端监听订单从"待支付"→"已发货"→"已完成"的变化），你会选哪种流式模式？为什么不用 WebSocket？
|
|
|
|
gRPC 双向流是**强类型 + 全双工**的替代方案，不需要额外建 WebSocket 通道，Proto 定义即契约，代码自动生成即客户端 SDK。对于纯内部服务链路，gRPC 双向流通常优于 WebSocket。
|
|
|
|
### Bidi Streaming 的生命周期管理
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
Start["建立双向连接"] --> Idle["空闲等待"]
|
|
Idle --> SendMsg["客户端 send"]
|
|
Idle --> SendReply["服务端 send"]
|
|
SendMsg --> Idle
|
|
SendReply --> Idle
|
|
SendMsg --> ClientCancel{"client cancel?"}
|
|
SendReply --> ServerCancel{"server cancel?"}
|
|
ClientCancel -->|yes| Cleanup["释放资源"]
|
|
ServerCancel -->|yes| Cleanup
|
|
Cleanup --> End["断开连接"]
|
|
|
|
style Start fill:#e3f2fd
|
|
style End fill:#ffcdd2
|
|
style Cleanup fill:#fff3e0
|
|
```
|
|
|
|
> [!keypoint] 黄金法则
|
|
>
|
|
> 双向流的**任何一方都可以随时单方面关闭发送端**（`CloseSend` 或 `context.Done`）。另一方应检测到 EOF 并及时清理资源，而不是无限等待。
|
|
|
|
## 四种模式速查
|
|
|
|
| 模式 | 客户端消息数 | 服务端消息数 | 典型场景 |
|
|
|------|------------|------------|---------|
|
|
| Unary | 1 | 1 | CRUD 常规操作 |
|
|
| Server Stream | 1 | N | 列表查询、日志流拉取 |
|
|
| Client Stream | N | 1 | 批量写入、大文件分块上传 |
|
|
| Bidi Stream | N | M | 聊天室、实时协作、行情推送 |
|
|
|
|
> [!note] 组合使用
|
|
>
|
|
> 同一个 Service 中可以混合使用四种模式。比如 `OrderService` 里：
|
|
> - `CreateOrder` 用 Unary（创建后立即返回结果）
|
|
> - `ListOrders` 用 Server Stream（大量数据分批返回）
|
|
> - `ImportRecords` 用 Client Stream（批量导入）
|
|
> - `NotifyOrderStatus` 用 Bidi Stream（实时状态变更推送）
|
|
|
|
## 关联笔记
|
|
|
|
- [[01-协议与架构]] — 流式建立在 HTTP/2 Stream 的多路复用之上
|
|
- [[04-拦截器]] — 流式调用同样可以通过 StreamInterceptor 进行切面处理
|
|
- [[05-错误处理]] — 流式调用的错误处理与普通模式有差异
|
|
- [[06-连接管理]] — 长时间存活的流式连接需要 Keepalive 保活
|