Golang处理大文件gRPC流式传输实战

本文深入剖析了Golang中使用gRPC流式传输处理大文件的实战难点与最佳实践，直击Unary调用导致内存溢出（OOM）和连接卡死的核心症结，强调必须采用BidiStreaming双向流替代单次加载模式，并详解客户端如何手动分片发送、服务端如何及时落盘写入、以及如何通过offset、Eof标记、校验机制和临时文件策略实现可靠传输、断点续传与错误回退——这不是简单的API调用，而是一套兼顾性能、健壮性与工程落地的完整解决方案。

gRPC流式传输为什么传大文件容易卡死或 OOM

因为默认 gRPC 的 Unary 调用会把整个请求/响应体加载进内存，文件一超过几十 MB，ClientConn 或 Server 就可能触发 GC 压力、超时、甚至 out of memory。流式（Streaming）不是“自动变快”，而是把大文件切片成小块，靠 Send() / Recv() 逐步推拉 —— 但前提是客户端和服务端都用对了流类型。

必须用 ServerStreaming 或 BidiStreaming，不能用 Unary

单次上传大文件用 ServerStreaming（服务端返回进度/结果）不够，得用 BidiStreaming（双向流），否则无法边传边校验、断点续传或实时反馈错误。定义 proto 时要明确写：

rpc UploadFile(stream FileChunk) returns (stream UploadStatus);

其中 FileChunk 至少含 bytes data 和 int64 offset；UploadStatus 含 int32 code 和 string message。别偷懒复用 message File —— 那还是 Unary 思维。

• BidiStreaming 允许客户端按需 Send() 分块，服务端随时 Recv() 并异步落盘
• 如果只用 ServerStreaming，客户端还得先把整个文件读进内存再一次性 Send()，没意义
• Go 客户端调用后得到的是 UploadFileClient 接口，不是普通函数，必须自己控制 Send() 循环

客户端分块发送必须手动控制 buffer 大小和 flush 时机

常见错误是直接 os.ReadFile() 整个文件再塞进一个 FileChunk 发出去 —— 这等于又回到 Unary 模式。正确做法是开固定 buffer（比如 32 * 1024 字节），循环 io.ReadFull() 或 bufio.Reader.Read()，每次构造新 FileChunk 并调用 Send()：

buf := make([]byte, 32*1024)
for {
    n, err := file.Read(buf)
    if n > 0 {
        chunk := &pb.FileChunk{
            Data:   buf[:n],
            Offset: int64(offset),
        }
        if err := client.Send(chunk); err != nil {
            return err // 注意：Send 可能因网络中断提前失败
        }
        offset += n
    }
    if err == io.EOF { break }
}

• buffer 太小（如 4KB）会导致 RPC 调用太频繁，增加 gRPC header 开销
• buffer 太大（如 1MB）可能让单次 Send() 阻塞过久，且易触发 maxMessageSize 限制（默认 4MB）
• 别依赖 client.CloseSend() 触发服务端结束 —— 要显式发一个 FileChunk{Eof: true} 标记

服务端接收时必须及时 write 到磁盘，不能攒在内存里

服务端 Recv() 到的每个 FileChunk，应该立刻 os.WriteAt() 或追加到 *os.File，而不是 append 到 [][]byte。否则内存占用随文件大小线性增长。

• 用 os.OpenFile(path, os.O_CREATE|os.O_WRONLY, 0644) 打开文件，避免重复创建
• 用 file.WriteAt(chunk.Data, chunk.Offset) 支持乱序到达（比如重传某块），但要注意并发安全 —— 建议用 sync.Mutex 包一层写操作
• 收到 Eof: true 后才做校验（如 sha256）、重命名、清理临时文件
• 别在 Recv() 循环里做耗时操作（如数据库写入），会阻塞整个流

真正麻烦的从来不是“怎么发”，而是怎么保证每一块都可靠落地、出错可回退、重启可续传 —— 这些得靠 offset、checksum、临时文件名和幂等接口共同兜底，gRPC 流本身不提供这些。

今天关于《Golang处理大文件gRPC流式传输实战》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！