gRPC流式响应需严格匹配proto声明、收发逻辑与错误处理三者，否则易导致客户端收不到数据、服务端卡死或连接静默断开。
gRPC 流式响应不是“加个 stream 就能跑”，而是必须严格匹配 proto 声明、收发逻辑和错误处理三者，否则客户端收不到数据、服务端卡死、连接静默断开都是常态。
proto 中 stream 关键字位置决定流类型，写错一个字接口就废
服务端流（如实时词义推送、例句流）要求 stream 只出现在 returns 侧；客户端或双向流写错位置，生成的 Go 接口类型名、方法签名全错，Send() 或 Recv() 根本不存在。
- 正确服务端流写法：
rpc GetDefinitions(WordRequest) returns (stream Definition) - 错误写法：
rpc GetDefinitions(stream WordRequest) returns (Definition)→ 实际生成的是客户端流接口，但你却在服务端写Recv()，编译都过不去 - proto 里别用
repeated bytes data表示音频/图片块，protoc 会尝试一次性分配整块内存，低配容器直接 OOM
服务端 Send() 卡住或只发一次就停，大概率是没检查错误或复用了 message 实例
Go 的 stream.Send() 是同步阻塞调用，不检查返回 err，下一次调用可能 panic 或静默失败；更隐蔽的是反复修改同一个 *pb.Definition 实例字段再 Send——protobuf 序列化复用内部 buffer，后一次覆盖前一次，客户端收到空响应或乱码。
- 每次
stream.Send(&msg)后必须判断err != nil，特别要区分io.EOF（客户端断开）和context.Canceled（超时或主动取消） - 循环内每次 Send 前都应新建 message 实例：
msg := &pb.Definition{Text: "hello"}，别用msg.Text = "hello"复用 - 别在 Send 循环中混入阻塞操作（如未设 timeout 的 DB 查询），否则整个流 hang 住，客户端永远等不到
io.EOF
客户端 Recv() 只读一条就退出，是因为没写标准循环结构
gRPC 流不是 channel，不能 for range stream。标准读法是显式循环 + io.EOF 判断，否则第一次 Recv() 返回 err 就退出，后续数据全丢。
立即学习“go语言免费学习笔记（深入）”；
- 正确模式：
for {
res, err := stream.Recv()
if err != nil {
if err == io.EOF {
break
}
log.Printf("recv error: %v", err)
return
}
process(res)
}- 如果业务需要保活，应在
stream.Context().Done()上 select，而不是依赖固定次数循环 - 大文本或音频流场景，客户端也需设置
grpc.MaxRecvMsgSize(32 * 1024 * 1024)，否则默认 4MB 限制直接报rpc error: code = ResourceExhausted
语言学习类流式服务最容易被忽略的点：背压与中间件超时
比如单词发音流、实时翻译结果流，上游生成快、下游渲染慢，不加控制就会在内存堆积 event；同时 Nginx/Envoy 默认 60s 超时、HTTP/2 流控窗口僵死，传输到一半就断连，且无明确错误提示。
- 服务端用带缓冲 channel（如
ch := make(chan *pb.AudioChunk, 50)）做应用层背压，慢消费者不会拖垮生产者 - 客户端和服务端都显式配置：
grpc.KeepaliveParams(keepalive.ServerParameters{Time: 30 * time.Second})和grpc.WithKeepaliveParams(keepalive.ClientParameters{Time: 30 * time.Second}) - 别依赖
context.WithTimeout做长连接保护，它只管单次 RPC 生命周期；流式通信必须靠 keepalive + 自定义心跳消息兜底
