必须显式设置chunkSizeBytes（推荐1MB）和contentType（标准MIME类型），否则文件可能无法正确读取或前端无法识别；metadata需用new Document()初始化且键名禁用点号和美元符。
GridFSUploadOptions 有哪些关键参数必须设置
不设置 chunkSizeBytes 和 contentType，上传后文件可能无法正确读取或前端无法识别类型。MongoDB Java Driver 默认 chunk 大小是 255KB（255 * 1024），但实际中建议显式指定——尤其当附件普遍大于 1MB 时，调大 chunk 可减少 GridFS 内部文档数量，降低元数据开销。
常见误操作是只设 contentType 却忽略 metadata 字段的 Map 初始化，导致后续按业务字段查询失败。
-
chunkSizeBytes：推荐设为1024 * 1024（1MB）或根据平均附件大小调整；小于 256KB 会强制归零并报IllegalArgumentException -
contentType：必须为标准 MIME 类型字符串，如"application/pdf"、"image/jpeg"；设成"pdf"或空字符串会导致浏览器下载时无后缀或乱码 -
metadata：用new Document()构造，键名避免用点号（.）和美元符（$），否则写入失败且报错信息模糊（WriteException: Invalid BSON field name）
上传流文件时如何避免内存溢出和连接超时
直接传 FileInputStream 是安全的，但若封装成 ByteArrayInputStream 或先读全字节到内存，大文件（>100MB）极易触发 OOM。GridFS 的 uploadFromStream 是流式写入，底层自动分块，前提是输入流本身支持 mark/reset（多数 FileInputStream 支持，但网络流或加密流不一定）。
连接超时通常不是 GridFS 层问题，而是 MongoDB 客户端配置缺失。Driver 5.x+ 默认 socket 超时仅 60 秒，大文件上传必然中断。
立即学习“Java免费学习笔记（深入）”；
- 务必在
MongoClientSettings中设置applySocketTimeout，例如SocketTimeoutSettings.builder().readTimeout(300, TimeUnit.SECONDS) - 不要对输入流做
available()判断再分配 byte[]，该方法在部分流中返回 0 或不准确，导致后续read()阻塞 - 上传前用
file.length()做预校验，超过服务端maxFileSize（默认 16MB）需提前拒绝，否则上传中途会抛GridFSUploadException: File size exceeds maximum allowed
为什么 setMetadata() 后查不到文件
GridFS 的 find 方法默认只查 files 集合的根字段（_id、filename、uploadDate 等），metadata 是嵌套子文档，必须用 Filters.eq("metadata.fieldName", value) 显式匹配。直接 Filters.eq("fieldName", value) 查不到任何结果。
另一个常见陷阱：用 String 存数字型业务 ID（如 "12345"）进 metadata，后续用 Filters.eq("metadata.orderId", 12345) 查询会失败——BSON 类型不匹配，必须保持类型一致。
- 查询含 metadata 的文件：用
gridFSBucket.find(Filters.eq("metadata.userId", "U1001")) - metadata 中存时间戳建议用
Instant+new Date(instant.toEpochMilli())，避免时区转换歧义 - 更新 metadata 需先
find出_id，再调rename()或replace()，GridFS 不支持原地 update metadata 字段
使用 GridFSUploadOptions 时最容易漏掉的异常处理
上传过程可能抛三类异常：客户端异常（IllegalArgumentException）、网络异常（MongoSocketReadTimeoutException）、服务端异常（GridFSUploadException）。其中 GridFSUploadException 很容易被当成普通运行时异常忽略，但它包含关键的 getErrorCode() 和原始 getError()，比如 error code 13 表示权限不足，error code 87 表示磁盘满。
- 必须捕获
GridFSUploadException并记录e.getError().getCode()，不能只打e.getMessage() -
MongoCommandException可能出现在设置错误的contentType时（如含控制字符），日志里会显示"Invalid namespace"，实则与命名空间无关 - 上传成功后建议立即用
gridFSBucket.find(Filters.eq("_id", fileId)).first()校验是否存在，防止网络闪断导致“假成功”
GridFS 不是万能附件方案，单文件超 16MB 且并发高时，IO 和锁竞争会明显上升；真正需要分片存储的大对象，应评估 MinIO 或 S3 + 数据库存路径的组合方案。
