gridfsdownloadstream必须显式close()才能释放资源，不能仅依赖try-with-resources；文件名含中文时需统一utf-8编码或改用metadata查询；大文件读取推荐64kb缓冲区；spring boot 2.4+需手动配置gridfsbucket bean。
GridFSBucket.openDownloadStream() 返回的流不能直接用 try-with-resources 自动关闭
Java 驱动里 GridFSBucket.openDownloadStream() 返回的是 GridFSDownloadStream，它实现了 AutoCloseable，但**必须显式 close() 才能释放底层 GridFS 会话资源**。如果只依赖 try-with-resources，某些场景下（比如流读取中途抛异常、未读完就跳出）会导致连接泄漏或后续操作卡住。
- 务必在 finally 块或 try-with-resources 的 catch 后手动调用
stream.close() - 不要假设「流关了 = 文件下载完了」——
GridFSDownloadStream的read()可能返回 -1 但流对象仍处于打开状态 - 若用 Spring Data MongoDB，优先考虑
GridFsTemplate.getResource()获取Resource，它封装了更安全的生命周期管理
文件名含中文或特殊字符时，find() 查询可能匹配不到
GridFS 默认按 filename 字段精确匹配，而 Java 驱动对字符串编码无自动处理。如果文件是用 Python 或 Node.js 上传且 filename 含 UTF-8 字符，Java 端用 Filters.eq("filename", "报告.pdf") 可能查不到——本质是 BSON 字符串比较失败。
- 上传时统一用
StandardCharsets.UTF_8编码 filename，或改用_id查（更可靠） - 查询前先用
new String(filename.getBytes(StandardCharsets.ISO_8859_1), StandardCharsets.UTF_8)尝试转码（仅限已知乱码模式） - 生产环境建议弃用
filename作为主键，改用业务 ID 存入metadata字段，再用Filters.eq("metadata.bizId", "xxx")
大文件分块读取时，buffer size 设太小会严重拖慢速度
GridFSDownloadStream.read(byte[] buffer) 的性能高度依赖 buffer 大小。默认用 new byte[1024] 会导致每 KB 一次系统调用，实测 100MB 文件耗时翻倍以上。
- 推荐 buffer size ≥ 64KB：
new byte[65536]，与 MongoDB 默认 chunkSize (255KB) 对齐 - 避免在循环内反复 new byte[]，复用同一 buffer 实例
- 注意：buffer 太大会吃 JVM 堆内存，单次读取超 1MB 不建议，尤其在高并发导出场景
Spring Boot 项目里用 MongoTemplate 找不到 GridFSBucket bean
Spring Boot 2.4+ 默认不自动配置 GridFSBucket，即使加了 spring-boot-starter-data-mongodb，直接 @Autowired GridFSBucket 会报 No qualifying bean。
- 手动定义 bean：
@Bean public GridFSBucket gridFSBucket(MongoClient mongoClient, MongoProperties props) { return GridFSBuckets.create(mongoClient.getDatabase(props.getDatabase())); } - 确保
application.yml中spring.data.mongodb.database已明确指定，否则props.getDatabase()可能为 null - 如果用了分片集群，确认该 database 已启用分片，否则
GridFSBucket初始化时可能静默失败
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
