必须在uploadFromStream或openUploadStream调用时通过metadata参数一次性写入自定义字段，否则无法落地到fs.files.metadata中；后续update会导致元数据缺失或查询失败，且metadata须为合法JSON对象、不支持根层级直接写字段。
metadata参数必须显式传入uploadFromStream，不能靠后续update
GridFS没有“先存文件再补元数据”的原子操作。所有自定义字段必须在uploadFromStream或openUploadStream调用时通过metadata参数一次性写入，否则根本不会落地到fs.files文档中。
常见错误是调用uploadFromStream("a.pdf", stream)后试图用db.fs.files.updateOne补字段——这会导致元数据缺失、GridFSBucket.find()查不到该文件，或触发schema validation失败（尤其在MongoDB 7.0+启用验证时）。
-
metadata必须是合法JSON对象（map[string]interface{}、dict、{}），不能是字符串、数组或null - Node.js驱动要求
metadata是plain object；PyMongo接受dict；Go官方驱动需用options.GridFSUpload().SetMetadata() - 别把
content_type塞进metadata——它是独立参数，和metadata同级，例如uploadFromStream("x.jpg", stream, {contentType: "image/jpeg", metadata: {...}})
metadata字段是唯一安全的自定义入口，别往根层级硬塞
旧资料常误称“把字段直接写到fs.files文档根层级”，这是错的。MongoDB 7.0+官方驱动强制校验结构，手动插入带author、version等字段的文档会失败，或导致后续openDownloadStream()找不到文件。
真正被所有主流驱动（Node.js、PyMongo、Java、Go）原生支持且协议兼容的位置，只有fs.files.metadata这个嵌套对象字段。它会被原样序列化存入，不破坏GridFS规范。
- 正确写法：
{"metadata": {"author": "alice", "tags": ["draft"]}} - 错误写法：
{"author": "alice", "tags": ["draft"], "filename": "x.pdf"}（绕过驱动，写入失败或行为异常） - 避免用
_private这类以下划线开头的键名，部分工具链会过滤掉
时间/枚举等非BSON原生类型必须手动序列化
Spring Data MongoDB的@WritingConverter对GridFS无效——metadata字段不走任何Spring转换链，直接由BSON编码器处理。传LocalDateTime或枚举进去，不是报错就是存成null或乱码。
必须在调用前转成BSON可存类型：
-
LocalDateTime→String：用DateTimeFormatter.ISO_LOCAL_DATE_TIME，如"2026-07-09T14:30:00" -
LocalDateTime→Long：用atZone(ZoneOffset.UTC).toInstant().toEpochMilli()，适合范围查询 - 枚举 →
String：调用.name()，别用.ordinal() - 避免在
metadata里放ObjectId、Document以外的复杂嵌套，MongoDB索引和查询语法对深层路径支持有限
高频查询字段必须单独建索引，且路径要带metadata.前缀
fs.files集合默认只有_id、filename、uploadDate等索引，查metadata.author这种字段不建索引就是全表扫描。
索引字段名必须严格匹配写入时的路径，大小写敏感，且必须包含metadata.前缀：
- 正确命令：
db.fs.files.createIndex({"metadata.author": 1}) - 错误命令：
db.fs.files.createIndex({"author": 1})（查不到）、db.fs.chunks.createIndex(...)（chunks里根本没有metadata） - 复合索引更实用，比如按部门+年份+类型查：
db.fs.files.createIndex({"metadata.dept": 1, "metadata.year": -1, "metadata.type": 1}) - 别对
metadata.tags（数组）建普通索引——除非你明确要用$in或$all，否则效果差
