GridFsTemplate不能用于响应式下载,因其是阻塞式API,返回GridFSFile或InputStream,会阻塞Netty线程;必须使用GridFSBucket的openDownloadStream()获取Mono流,并通过DataBufferUtils转为Flux实现真正响应式流式响应。

为什么不能直接用 GridFsTemplate 做响应式下载
因为 GridFsTemplate 是阻塞式 API,内部调用的是老版 MongoDB Java Driver 的同步方法。它返回 GridFSFile 或 InputStream,没法接入 Mono/Flux 流链。你在 WebFlux 里用它,会立刻阻塞 Netty 线程,失去响应式意义,还可能触发 IllegalStateException: block()/blockFirst()/blockLast() are blocking 错误。
必须绕过 GridFsTemplate,直连底层驱动的 GridFSBucket —— 它的 openDownloadStream(ObjectId) 返回的是 Mono<gridfsdownloadstream></gridfsdownloadstream>,这才是真正的响应式入口。
如何用 GridFSBucket 实现流式响应
核心是把 GridFSDownloadStream 包装成 Flux<databuffer></databuffer>,再交给 ServerResponse.bodyValue() 或 writeWith() 推送出去。别手动读取、拼接、转字节数组 —— 那就又掉回阻塞坑里了。
-
GridFSBucket必须声明为@Bean,且参数类型是MongoClient(不是MongoTemplate),否则注入失败 - 下载时先用
find(Filters.eq("_id", id))拿到GridFSFile,再传file.getObjectId()给openDownloadStream() - 用
DataBufferUtils.readByteChannel()把GridFSDownloadStream转成Flux<databuffer></databuffer>,它会自动按 chunk 大小分片、非阻塞读取 - 记得设响应头:
Content-Type(从metadata.contentType取)、Content-Disposition(含原始filename)
常见错误:下载大文件卡住或内存溢出
问题不在 GridFS,而在你没控制好背压或缓冲策略。比如:
- 直接调
downloadStream.all().block()—— 全部加载进内存,100MB 文件就 OOM - 用
Flux.fromStream()包装InputStream—— 还是同步流,无法响应背压 - 没设
response.headers().setContentLength(),浏览器无法显示进度条,容易误判为卡死 - 忘记调
downloadStream.close()(通过doFinally或onTerminateDetach),导致连接泄漏
正确做法是信任 DataBufferUtils.readByteChannel() 的流控能力,它会根据下游 request(n) 自动拉取对应数量的 DataBuffer。
WebClient 调用时如何保持响应式链路不断
如果你的 WebFlux 服务本身是作为网关,需要把 GridFS 文件透传给下游,千万别用 webClient.get().retrieve().bodyToMono(byte[].class) —— 这又全量加载了。
应该用 bodyToFlux(DataBuffer.class),然后用 flatMap 或 writeWith 直接接力:
webClient.get()
.uri("http://upstream/file/{id}", id)
.retrieve()
.bodyToFlux(DataBuffer.class)
.doOnNext(buffer -> buffer.readableBytes()) // 可选:记录大小
.switchIfEmpty(Flux.error(new FileNotFoundException()))
.writeWith(outputMessage.getBody());
整个过程不落地、不缓存、不阻塞,真正端到端响应式。但注意:下游服务也得支持流式接收,否则中间某环转成 byte[] 就前功尽弃。
最易被忽略的一点:GridFS 的 chunkSize 默认 255KB,而 Netty 的 DataBuffer 默认大小是 8KB。如果没做适配,大量小 buffer 会增加 GC 压力。建议在 application.yml 中显式配置 spring.codec.max-in-memory-size: 256KB,与 GridFS chunk 对齐。


















