gRPC流式传输需按通信模式选对四种流类型、配对收发策略并规避HTTP/2与中间件陷阱：服务端流适用于单请求多响应场景，客户端流适用于多请求单响应，双向流支持完全异步交互；常见卡顿源于错误未检查、EOF未判断、proto实例复用及超时缺失；大文件传输须分块读写、显式调大缓冲区、避免内存溢出；可靠性依赖chunk_id、offset、checksum及心跳机制；连接须复用，proto中stream关键字位置错误将导致接口失效。
gRPC 流式传输不是“开个 stream 就行”，而是要按通信模式选对类型、配对收发策略、绕过 HTTP/2 和中间件的隐形陷阱。
怎么选对流类型：看数据流向，别硬套场景
gRPC 只有四种流语义，全靠 .proto 里 stream 关键字位置决定，写错一个字生成的 Go 接口就完全不能用：
- 服务端流：
rpc GetLogs(Request) returns (stream LogEntry)—— 客户端发一次，服务端 Send 多次，适合日志尾部、指标推送 - 客户端流：
rpc Upload(stream Chunk) returns (UploadResult)—— 客户端 Recv 多次，服务端等收完才 Send 一次，适合大文件分块上传 - 双向流：
rpc Sync(stream FileChunk) returns (stream SyncAck)—— 双方各自 Recv/Send，完全异步，适合断点续传、实时校验 - 别把
stream加在请求侧却当成服务端流用，比如rpc Get(stream Req) returns (Resp)是客户端流，不是服务端流
为什么服务端流卡在第三次 Send 就停了
常见现象是 stream.Send() 第三次阻塞或返回 rpc error: code = Unavailable desc = transport is closing，根本原因不是代码逻辑错，而是：
- 服务端没在每次
Send()后检查错误，错误被吞掉，后续 Send 直接 panic 或静默失败 - 客户端没用循环 +
io.EOF判断退出，而是写了固定次数Recv()，导致连接提前关闭 - 服务端用了同一个
*pb.Response实例反复改字段再Send()—— proto 序列化复用内部 buffer，后一次覆盖前一次，客户端收到乱码或空数据 - 没设超时或心跳，TCP 连接被 NAT/防火墙/Envoy 中间件默默断开，
stream.Context().Err()返回context.DeadlineExceeded却没处理
双向流传大文件必须绕开的三个内存坑
直接 os.ReadFile() → proto.Bytes → stream.Send() 必 OOM，尤其在嵌入式或低内存容器里：
立即学习“go语言免费学习笔记（深入）”；
- 别在 proto 里定义
repeated bytes data或单个超大bytes字段 —— protoc 生成代码会试图一次性分配整块内存 - 服务端接收时别用
for range stream.Recv()—— 一次Recv()卡住，整个 goroutine 永久挂起；改用select+stream.RecvMsg(&msg)+ 超时控制 - 收发缓冲区大小必须显式调大：
grpc.MaxRecvMsgSize(64 * 1024 * 1024)和grpc.MaxSendMsgSize(64 * 1024 * 1024)，否则默认 4MB 会直接报message too large - 真正读写用
io.Copy分块，比如make([]byte, 1024*1024)每次最多 1MB，边读边写，不进内存
客户端流和双向流里如何让重试和进度可控
纯流式没有内置 ACK 或 offset 回调，所有可靠性都要自己建模：
- 每个 chunk 必须带
chunk_id（单调递增）和offset（字节偏移），服务端用os.WriteAt(data, offset)直接落盘，不拼接内存 - 加
checksum字段（如uint32crc32），服务端写完立刻校验，失败就return status.Error(codes.Aborted, "checksum mismatch") - 每发 5 个 chunk 主动发一次心跳消息（
data = []byte{}, is_heartbeat = true），服务端回Ack{chunk_id: n}，双方靠这个同步进度、保活、触发重传 - 客户端别每次调用都
grpc.Dial()新建连接 —— 复用*grpc.ClientConn，否则流还没建好连接先被限频或断开
流式不是功能开关，是协议层、应用层、运维层三者咬合的结果。最容易漏的是中间件超时配置和 proto 里那个不起眼的 stream 关键字位置 —— 写错它，后面所有优化都是无用功。
