gRPC Stream与Unary调用：从超时炸裂到性能跃升的实战解析

一次线上告警让我注意到这个问题的价值某个核心服务在调用另一个团队提供的gRPC接口时服务端一直用一元调用Unary返回一个上万条记录的大列表结果客户端频繁出现upstream request timeout服务端内存也快炸了。改造成Server Streaming之后同样一批数据首包延迟从 800ms 降到 60ms整体内存占用下降了将近一半。这是我早期不看接口定义、拿到一个 proto 文件就开始填请求字段踩出来的教训。从那以后每次新建服务或者评审别人的 proto我都会先问一句这个接口到底该不该加 stream加了之后在传输、超时、内存、错误处理上和普通调用有什么不一样。很多人以为 gRPC 无非就是“请求-响应”但要理解有没有 stream关键不是看用没用 HTTP/2而是看参与通信的两端在一条调用上下文里能互发多少消息。理解清楚这一点你才能在架构评审时给出一锤定音的建议也能在处理诡异报错时快速定位方向。1. 先分清楚有stream和无stream不是同一个维度1.1 一元调用Unary最常见的“无stream”形态gRPC 默认的调用方式叫 Unary Call也叫一元调用。客户端发送一个请求消息服务端处理完返回一个响应消息然后这次调用就结束了。从调用者的角度看它和普通 HTTP POST 没有太多区别发一个 JSON/Protobuf等一个响应。但注意一个容易被忽略的细节gRPC 底层走的是 HTTP/2所以哪怕是一次未加 stream 的 Unary 调用在传输层上也会开启一条 HTTP/2 Stream流。换句话说“没有 stream”只是业务模型上没有多消息流动底层仍然是有流的。这句话很关键否则你在看抓包工具时很容易被绕晕。真正的区别在于应用层消息的数量和生命周期。Unary 调用建立流之后双方各发一个消息流就关闭。它的优势是语义简单、超时控制精确、负载均衡策略好做最适合“一问一答”的场景。比如根据订单 ID 查订单详情、根据用户 ID 查账户余额都属于这一类。我在做支付系统时所有涉及状态修改的命令接口都会强制使用 Unary因为这类接口最怕重试、乱序和延迟语义含糊Unary 的“发一个收一个”正好避免了这些麻烦。1.2 三种流式模式到底在流什么gRPC 一共定义了三种流式模式加上 Unary正好凑成四种Server Streaming服务端流式客户端发一个请求服务端可以连续返回多条消息直到主动结束。典型场景是订阅通知、大列表分页、监控指标推送。比如你要拉取一个用户的所有订单服务端不需要把十万条订单拼成一个超大响应而是一条一条或一批一批地推给客户端。Client Streaming客户端流式客户端可以连续发送多条消息服务端最后只返回一个响应。典型场景是文件上传、传感器数据上报、批量请求。比如向服务端批量写入一万条日志客户端可以边产生边发不需要全部积压在内存后再装配成一个请求。Bidirectional Streaming双向流式客户端和服务端各自维护自己的发送方向双方可以同时、多次收发消息。典型场景是聊天、实时协同编辑、机器人和用户的多轮对话。注意“同时”不代表双方要轮流等对方HTTP/2 的多路复用让两个方向互相独立。为什么这三种模式都能叫“有 stream”因为它们都在同一次调用上下文里承载了多条应用消息。流不是指“消息比较大”而是指“消息有先后、有持续、有结束标记”。理解这一点后再回看 Unary你会发现它其实可以被看作一个“只发一条消息、只收一条消息”的退化流只是 gRPC 为它做了专门优化和更严格的错误语义罢了。1.3 一张表看清边界通信模式请求消息数响应消息数适用场景Unary无 stream11查询详情、修改状态、简单请求响应Server Streaming1N订阅、拉取大列表、日志推送、下行同步Client StreamingN1上传文件、批量写入、遥测上报Bidirectional StreamingNN聊天、实时交互、长连接协商这张表看似简单但在真写代码时很容易搞混。我见过同事把 Server Streaming 误用成 Bidirectional Streaming只因为觉得服务端要多次返回消息结果客户端把requestStream(true)也打开了导致握手阶段就多了一个方向的状态调试时花了半小时才意识到问题。所以拿到一个 proto先数清楚请求方向到底有几个消息再动手。2. proto定义与代码实现的差异2.1 proto文件里怎么表达stream在 proto 文件里stream 的声明方式非常直白。对照下面这个片段就能看出来stream关键字出现在消息类型前出现了几次就代表哪个方向是流式的syntax proto3; package example.v1; service OrderService { // 无 stream一问一答 rpc GetOrder(GetOrderRequest) returns (Order); // 服务端流式请求一条响应多条 rpc ListOrders(ListOrdersRequest) returns (stream Order); // 客户端流式请求多条响应一条 rpc UploadOrders(stream UploadOrderRequest) returns (UploadSummary); // 双向流式两边都是多条 rpc ChatByOrders(stream ChatOrderRequest) returns (stream ChatOrderReply); }这里有个很常见的认知误区很多人以为returns (stream Order)是服务端一次性把Order列表序列化成一个大流。实际上它只是定义了应用层的消息边界每个Order仍然是独立的消息编码成 Protobuf 后按顺序写在同一个 HTTP/2 Stream 上。服务端每返回一个Order客户端就可以感知到一次新的消息到达不需要等待整个流结束。换句话说stream本质上是把“一个巨型响应”拆成了“多个小消息”。它改变的是服务端和客户端的处理粒度而不是传输协议本身。2.2 服务端编程模型差异以 Java 的 gRPC 为例Unary 接口的服务端实现一般长这样Override public void getOrder(GetOrderRequest request, StreamObserverOrder responseObserver) { Order order orderService.fetch(request.getOrderId()); responseObserver.onNext(order); responseObserver.onCompleted(); }而 Server Streaming 接口的服务端实现你会频繁调用onNext最后再调onCompletedOverride public void listOrders(ListOrdersRequest request, StreamObserverOrder responseObserver) { try (CursorOrder cursor orderDao.scroll(request.getCustomerId())) { while (cursor.hasNext()) { if (responseObserver.isCancelled()) { break; } responseObserver.onNext(cursor.next()); } responseObserver.onCompleted(); } catch (Exception e) { responseObserver.onError(e); } }注意这里我显式检查了responseObserver.isCancelled()。流式接口最大的编程模型差异就是你的循环不能自顾自地跑到底要随时准备响应中途取消。如果一个流已经断了你还在继续onNext轻则抛异常重则触发连接重置把原本能救回来的调用彻底搞坏。这一点在 Unary 接口里几乎不需要操心因为请求响应本来就快但 stream 接口可能运行几小时你必须把取消当成正常分支处理。2.3 客户端调用方式的差异客户端这边Unary 调用通常同步就能拿结果比如 Go 里client.GetOrder(ctx, req)直接返回(*Order, error)。但一旦有 stream你会发现 API 形态完全变了。拿 Go 的客户端举例// Unary直接返回 order, err : client.GetOrder(ctx, pb.GetOrderRequest{OrderId: id}) // Server Streaming先得一个 stream 对象再逐条 Recv stream, err : client.ListOrders(ctx, pb.ListOrdersRequest{CustomerId: id}) for { order, err : stream.Recv() if errors.Is(err, io.EOF) { break } if err ! nil { // 处理中断错误 break } process(order) }这个 API 形态上的差别直接影响了业务代码的写法。很多团队在重构时忘了这一步把接口从 Unary 改成 Server Streaming 后客户端调用的地方不能只改参数而要把整个逻辑从“拿到结果再处理”改成“边收边处理”。如果客户端还按照旧逻辑去等一个完整的 Response哪怕服务端已经开始推流客户端也会一直阻塞到流结束白白浪费了流式的好处。3. 资源占用、性能与背压的真实差异3.1 连接与内存开销从 HTTP/2 的连接模型看Unary 和 Stream 共享同一套多路复用机制。一个客户端进程里gRPC 连接池会维护若干条 HTTP/2 连接所有 Unary 调用都在这几条连接上负载均衡。因为一个 Unary 调用占用的流很快结束连接可以承载大量并发调用连接本身不会成为瓶颈。有 stream 的调用就不一样了。一个 Server Streaming 调用会长期占用一条 HTTP/2 Stream。虽然同一物理连接上可以并存很多流但每个流都持有发送队列、接收队列、状态机和流量控制窗口。如果你的服务端有大量长期 stream比如实时推送每个客户端占用的连接资源其实是和 stream 数量成正比增长的。之前我在做长连接推送服务时做过一个简单的压力测试同样的物理内存Unary 模式可以扛住每分钟十万次请求Server Streaming 模式如果每个用户单独一个 stream两万个在线用户就已经把客户端连接池内存吃上来一块。也更占用内存的是你在服务端选择怎么发消息。如果还是按旧思维先把所有数据装进ListOrder再逐个onNext那 stream 和 Unary 在内存上没有任何区别甚至因为多一次的循环调用反而更慢。正确的做法是像前面代码写的那样用数据库游标、迭代器或通道逐条读出逐条发送让 Service 层的数据不落全量内存。否则你以为自己用了流式其实只是把超大响应拆成多个小块发给客户端中间的组合成本一点没少。3.2 吞吐量、时延与首字节吞吐量这块不能笼统地说 stream 一定比无 stream 高。如果消息本身很小比如每次只是一个数字那大量小消息反而会放大 Protobuf 编码和 gRPC 框架调度的开销。这时候把多条消息封装成一个列表型 Response走一次 Unary性能反而更好。所以我在设计接口时会看消息的平均大小和单次调用的数据总量如果总量小小于几十 KB老老实实用 Unary如果总量大几 MB 甚至上百 MB或者消息是持续产生的用 stream 才能规避超时和内存暴涨。时延方面stream 的核心优势是首字节延迟和整体完成时间解耦。大家最容易体会到的就是大列表场景Unary 必须等服务端把所有数据组装完、序列化完、发完客户端才能开始解析而 Server Streaming 只要服务端查到第一批数据就可以先推给客户端所以“第一条消息到达客户端”的时间会大大提前。我实测过一个场景一个读取 50 万行订单数据的接口Unary 模式从客户端发请求到拿到完整响应耗时 2.8 秒期间服务端堆内存 GC 明显改成 Server Streaming 每次发 1000 条一个批次后客户端在 80ms 内收到第一包到最后一个包收完不到 1.5 秒。虽然总链路数据没少传但客户端可以边收边渲染或边落库业务体感完全不一样。3.3 deadline与cancel的行为差异Unary 接口的 deadline 很好理解context.WithTimeout(ctx, 2*time.Second)后整次调用 2 秒超时要么成功要么失败。但 stream 接口的 deadline 是对整条流而言的不是每条消息的 deadline。一个 5 分钟的 stream客户端设置context.WithTimeout(ctx, 5*time.Minute)意味着从流建立开始算满 5 分钟无论消息收发是否活跃都会强制断开。这点很容易被忽略如果你在一条双向流上只想对“空闲”做超时使用 deadline 是不合适的应该自己实现心跳或者读取超时事件。取消行为的差异更大。服务端在 Unary 接口里一旦开始处理很少会中途感知到取消因为处理很快而 stream 接口里客户端取消后服务端的StreamObserver.isCancelled()会尽快变成true并且底层 HTTP/2 会发送 RST_STREAM 帧。如果服务端不监听这个状态还继续往关闭的流上onNext就会得到StatusRuntimeException: CANCELLED。在双向流里如果双方都持有自己的流取消的传播方向还讲究一个先后顺序往往一不留神就出现“客户端以为关闭了服务端还一直发”的状态。这也是为什么代码里要随时检查取消状态。4. 线上stream踩坑实录与排查思路4.1 “stream disconnected before completion”到底在报什么网上搜 gRPC 相关问题最难排查的一类就是stream disconnected before completion: transport error: network error: error和stream disconnected before completion: stream closed before response.completed。从字面看是客户端还没收到服务端的onCompleted底层连接就断开了。我遇到过几种根因各有各的特征服务端 panic 或被 kill进程退出前没来得及发GOAWAY或onError客户端直接看到 transport error。这种情况服务端日志里往往有 panic 日志或者容器 OOM。客户端和服务端之间的负载均衡层迁移连接如果中间有 Envoy 或 Nginx它可能因为空闲或主动健康检查把连接断开尤其你开启长连接但没有心跳时。客户端视角就是 network error。写了但没调 onCompleted服务端把数据都onNext出去了但忘了调onCompleted导致流一直悬挂。客户端一旦主动关闭流就会看到 stream closed before response completed。注意这是服务端 bug不是网络问题。排查方法很简单先看服务端有没有输出onCompleted或onError日志如果没有再抓包看底层是否收到 RST_STREAM 或 GOAWAY。我记得一次线上事故服务端用线程池执行任务任务异常后只打了 error 日志没调responseObserver.onError客户端一直等到超时才报CANCELLED后来在代码规范里强制要求所有 stream 方法必须在任何退出路径上调用onCompleted或onError二选一缺一不可。4.2 idle timeout与网络中间层“积极拒绝”还有一个高频报错是stream disconnected before completion: idle timeout waiting for sse以及由于目标计算机积极拒绝无法连接。前者经常出现在服务端接了 SSEServer-Sent Events或类似长轮询出口的架构里因为 gRPC 流本身不产生周期性消息如果中间代理配置了 idle timeout比如 60 秒没有任何 TCP 数据就会主动掐断连接。后者严格说不是 stream 的特有错误但它经常在 stream 场景出现尤其是客户端连服务端地址时端口没监听或者是防火墙对长连接做了 RST 拒绝。处理这类问题的核心是保活。gRPC 客户端通常有keepalive参数但很多人只知道开不知道怎么调。我常用的一组参数是keepAliveTime30s、keepAliveTimeout10s、permitWithoutStreamtrue。注意第三个参数很关键如果permitWithoutStream为false那么在没有 active stream 时 keepalive 可能不会发送。而我们的 stream 本身就是 active所以通常没问题但为了保险还是要打开。服务端也要允许 keepalive否则客户端发起的 PING 会被忽略。另外如果错误是“积极拒绝”别一开始就往应用层查。先在本机telnet host port或者用grpcurl测一下确认端口是否开着。如果端口通再考虑是不是劫持了 HTTP/2 的中间设备做了连接拦截。我有一次就是被一个老旧的硬件防火墙坑了它只识别普通 TCP遇到 HTTP/2 的长连接直接发 RST导致 stream 总是秒断最后绕开那个设备才定位到原因。4.3 流式接口中的多字段排序别把顺序交给gRPC热搜里有个词是“stream流 多字段排序”这其实暗合了 stream 接口设计的一个常见问题。gRPC 的 stream 本身是保序的——HTTP/2 流里消息按发送顺序到达。但这个顺序是“消息到达顺序”不是业务上的排序顺序。如果业务需要按多个字段排序后推给客户端服务端必须在生成流之前就完成排序逻辑。我踩过的坑是在服务端写了一个模糊查询接口直接沿着数据库索引顺序onNext客户端误以为这就是业务顺序后来产品要求在返回列表里按时间倒序再按金额倒序我第一版直接在客户端做全量排序结果数据量大时客户端内存爆炸。后来改成服务端先把全部结果收集到一个小顶堆中做多字段排序再开始推到 stream。虽然牺牲了首字节延迟但保证了客户端永远不需要全量缓冲。如果你更需要首包快、又要全局排序那通常要引入外部存储排序或者提前建索引可以做的选择很多但千万别把“不负责排序”当成 stream 的特性推给客户端。4.4 好用的stream调试工具和一个实操技巧平时我用得最多的调试工具是grpcurl它支持-d传 JSON 请求对 stream 接口也能正确识别。比如服务端流式接口你可以这样测grpcurl -plaintext -d {customer_id: 42} localhost:9090 example.v1.OrderService.ListOrders它会按服务端推送的每条消息逐行输出 JSON。如果接口是双向流需要交互式输入我会写一个小脚本往 stdin 里不断塞请求或者先用一个简单的单发消息验证。还有个更轻量的方法用 gRPC 反射注册服务后直接在客户端代码里加一个StreamDump的测试入口把onNext的消息打到日志里。集成测试里我会构造一个只发空请求、一直Recv的“无限流”配合超时判断来验证服务端是否会意外onCompleted。最后分享一个很实用的小技巧在 Client Streaming 和 Bidi Streaming 里客户端在关闭发送方向时会调用CloseSend但 gRPC 的语义并不保证服务端能立刻感知到。如果你的业务要求服务端必须在收到所有请求后再返回响应保险的做法是在最后一个请求里显式加一个finaltrue的字段而不是依赖框架的 EOF。这样即使网关或代理层把 EOF 吞了服务端仍然知道处理到哪里是终点避免一条流挂半天的“假死”状态。我自己现在定接口规范时会有一条铁律默认 Unary除非数据量或时效性明确需要流式并且必须在 proto 注释里写上“为什么用 stream”。因为一旦接口带上 stream它的超时、取消、内存模型和错误恢复全都变了调用方的心智负担也直线上升。可当你确实遇到大列表、长连接、实时推送这些场景又会庆幸当初多问了一句“是不是该加 stream”。这两种模式没有谁绝对好只有合不合适。你在做下一个接口前可以先拿一张纸写写这个接口要传多少条消息客户端能不能边收边处理如果请求或响应超过了几千条消息那大概率就需要 stream 了。