Java中操作MongoDB GridFS必须使用官方Mongo Java Driver（≥4.0，推荐4.11+），核心类是GridFSBucket，需通过GridFSBuckets.create(database, bucketName)创建，依赖fs.files和fs.chunks两个集合管理元数据与分块数据。
GridFS在Java中用哪个驱动和类？
Java连接MongoDB GridFS必须用官方Mongo Java Driver，且版本不能低于4.0（推荐4.11+），旧版的mongo-java-driver已废弃。核心类是GridFSBucket，它封装了文件分块、元数据管理、读写逻辑——不是直接操作GridFSBucket就能用，得先有MongoClient和MongoDatabase实例。
常见错误是误用GridFSBucket构造方式：它不接受URI字符串，必须通过GridFSBuckets.create(database, "bucketName")创建。默认bucket名是fs，但如果你改过，比如用files，就必须显式传参，否则读不到你存的文件。
- 驱动依赖写法：
org.mongodb:mongodb-driver-sync:4.11.2（同步API，最常用） - 别漏掉
com.mongodb.ConnectionString——URI里必须含数据库名，例如mongodb://localhost:27017/myapp - GridFS集合名实际对应两个集合：
fs.files（元数据）和fs.chunks（数据块），不能手动删其中一个
上传文件时怎么控制chunkSize和metadata？
默认chunkSize是255KB（261120字节），这个值影响内存占用和查询效率：设太小，chunk太多，fs.chunks膨胀快；设太大，单次读取压力高，且无法流式上传大文件。修改它必须在创建GridFSBucket时传GridFSBucketOptions，不能运行时改。
metadata字段不是任意加——它必须是Document类型，且只支持BSON基本类型（String、Integer、Date等）。存JSON字符串或嵌套对象没问题，但别塞Java对象实例，会序列化失败。
立即学习“Java免费学习笔记（深入）”；
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 设置chunkSize：
GridFSBucket bucket = GridFSBuckets.create(db, "myfiles", new GridFSBucketOptions().chunkSizeBytes(512 * 1024)) - 上传带metadata：
ObjectId id = bucket.uploadFromStream("report.pdf", inputStream, new Document("author", "alice").append("version", 2)) - 注意
uploadFromStream返回的是ObjectId，不是文件名——后续查文件得靠这个ID或filename字段
按filename查文件为什么总查不到？
GridFS默认允许同名文件存在，每次上传都生成新文档到fs.files，所以用find查filename会返回多个结果。Java SDK没提供“取最新一个”的快捷方法，得自己排序+limit。
更隐蔽的问题是大小写敏感：MongoDB的filename字段区分大小写，"Report.PDF"和"report.pdf"是两个文件。另外，如果上传时没设filename（比如用uploadFromStream重载方法没传name参数），GridFS会生成随机UUID作名，根本没法按名查。
- 查最新同名文件：
FindIterable<document> files = bucket.find(Filters.eq("filename", "data.csv")).sort(Sorts.descending("_id")).limit(1)</document> - 查指定ID的文件：
GridFSDownloadStream stream = bucket.openDownloadStream(objectId)（比按名查更可靠） - 别用
bucket.find(Filters.eq("filename", ...))直接遍历——它返回的是Document，不是可读流，要下载还得再调openDownloadStream
流式下载大文件时内存爆了怎么办？
GridFSDownloadStream本身是流式接口，但很多人直接调readAllBytes()或转成ByteArrayInputStream，等于把整个文件读进内存——1GB文件就崩。正确做法是边读边写到磁盘或响应输出流，且必须手动close()，否则连接泄漏。
另一个坑是超时：GridFS读取没有内置超时，如果网络卡住或MongoDB慢，线程会一直挂。得靠MongoClientSettings里的heartbeatFrequency和maxConnectionLifeTime间接控制，或者在外层加try-with-resources配合ExecutorService做超时中断。
- 安全下载示例：
try (GridFSDownloadStream stream = bucket.openDownloadStream(fileId)) { Files.copy(stream, Paths.get("/tmp/output.zip"), StandardCopyOption.REPLACE_EXISTING); } - 避免用
stream.available()判断长度——它永远返回0，GridFS流不支持available语义 - 如果需要进度回调，得自己包装
GridFSDownloadStream，重写read(byte[])并在每次读完后触发回调
GridFS不是万能存储，小文件（fs.files文档却忘了删对应fs.chunks，下次读就会报ChunkNotFound错误，这种脏数据只能手动清理。
