stream关键字位置错误会导致gRPC流类型生成错误：服务端流需stream在returns后，客户端流需stream在参数中，双向流需两者均有；否则接口方法名、Send/Recv逻辑全错。
proto里stream关键字写错位置，生成的Go接口就完全不能用
服务端流、客户端流、双向流的区别，只取决于stream出现在rpc声明中的哪个位置——它不是修饰符，是语法硬约束。写错一个字，生成的 Go 接口类型名、方法签名、甚至是否带Send/Recv都会错乱。
常见错误写法：
-
rpc Bad(stream Req) returns (Resp)→ 生成的是客户端流接口，但开发者误当服务端流用，调Recv()却收不到数据 -
rpc Bad(Req) returns (Resp)（漏stream）→ 生成 unary 接口，根本没Send()方法 -
rpc Bad(stream Req) returns (stream Resp)→ 实际是双向流，但业务只需要单向上传，结果客户端还得写RecvMsg()逻辑
正确写法必须严格对应语义：
- 服务端流：
rpc GetLogs(LogRequest) returns (stream LogResponse) - 客户端流：
rpc Upload(stream Chunk) returns (UploadResult) - 双向流：
rpc Sync(stream FileChunk) returns (stream SyncAck)
message 必须显式定义，不能直接用bytes或string作参数；repeated bytes data是高危模式，protoc 会尝试一次性分配整块内存，容易 OOM。
立即学习“go语言免费学习笔记（深入）”；
服务端Send()卡住或客户端Recv()只读一条就退出
这不是网络问题，而是流控制逻辑没写对。gRPC 的Send()和Recv()都是同步阻塞调用，不加判断就循环，极易 hang 住。
服务端常见卡点：
- 没在每次
stream.Send(&msg)后检查err，错误被吞掉，下一次Send()直接 panic 或静默失败 - 复用同一个
*pb.Response实例反复改字段再Send()—— proto 序列化复用内部 buffer，后一次覆盖前一次，客户端收到空或乱码 - 循环中遇到 DB 查询失败等错误，直接
return err，没发完最后一批数据，客户端收不到io.EOF，一直等下去
客户端标准读法不是for range stream（那不是 channel），而是：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
for {
res, err := stream.Recv()
if err != nil {
if err == io.EOF {
break
}
log.Fatal(err)
}
handle(res)
}传大文件时内存暴涨或连接被中间件断开
直接os.ReadFile()→proto.Bytes→stream.Send()在低内存环境必崩；Nginx/Envoy 默认 60s 超时、HTTP/2 流控僵死、TCP 连接无保活，都会导致传输到 70% 就断。
必须显式绕过这些坑：
- 服务端和客户端都设大缓冲区：
grpc.MaxRecvMsgSize(64 * 1024 * 1024)、grpc.MaxSendMsgSize(64 * 1024 * 1024) - chunk 消息只含
bytes data、int64 offset、uint32 seq，单次≤1MB；禁止repeated bytes data - 服务端接收不用
for range stream.Recv()，改用select+stream.RecvMsg(&msg)+ 超时控制 - 每发 5 个 chunk 主动发一次心跳消息（空
data+is_heartbeat: true），服务端回 ACK，双方靠这个保活并同步进度
客户端发起前确保*grpc.ClientConn是复用的，别每次grpc.Dial()新建连接——否则连接数爆炸，中间件直接限流。
双向流里goroutine管理不当，协程永久挂起
双向流要求收发逻辑分离，但很多人把Recv()和Send()塞进同一个 goroutine，或没做超时控制，结果某次Recv()卡住，整个协程就永远 hang 在那里。
安全做法是拆成两个独立 goroutine：
- 一个专责
RecvMsg()：用select监听stream.RecvMsg()和ctx.Done()，出错或超时立即退出 - 另一个专责
SendMsg()：按业务节奏发，每次SendMsg()后检查err，失败则通知对方并关闭流 - 两个 goroutine 共享一个
sync.WaitGroup或chan struct{}协调退出
别在Recv()循环里直接os.WriteAt()——频繁磁盘写会拖垮吞吐；先缓存到bytes.Buffer，累积到 4MB 再 flush 到临时文件，流结束再rename。
最常被忽略的是：stream.Context().Err()返回context.DeadlineExceeded或connection reset by peer时，你得立刻清理本地资源，而不是等 GC —— 协程不会自动回收，句柄泄漏会越积越多。
