GridFS不支持自定义转换器，metadata字段需手动序列化为BSON原生类型（如LocalDateTime转String或Long、枚举转name()），且须为fs.files（或自定义bucket对应集合）手动创建带metadata.前缀的索引以保障查询性能。
GridFS 本身不支持自定义转换器——GridFsTemplate 和 GridFSBucket 都绕过 Spring Data 的类型转换体系，直接操作 Document 和原始字节流。所谓“配置 GridFS 自定义转换器”是个常见误解，真正能插手的地方只有元数据（metadata）字段的序列化逻辑，且必须手动控制。
GridFS 的 metadata 不走 Spring Data Converter 链路
当你调用 gridFSBucket.uploadFromStream() 或 gridFsTemplate.store() 时传入的 Document（或 Map），会被原样写入 fs.files 集合的 metadata 字段，中间不经过任何 @WritingConverter 或 @ReadingConverter。Spring Data MongoDB 的自定义转换器只对实体类（@Document 标注的 POJO）生效，而 GridFS 文件记录不是实体，不参与映射流程。
常见错误现象：
- 写了
@WritingConverter<localdatetime string></localdatetime>，但上传文件时metadata.put("createdAt", LocalDateTime.now())仍报org.bson.codecs.configuration.CodecConfigurationException - 在
CustomConversions里注册了转换器，但files集合里metadata.createdAt是空或乱码
根本原因：BSON 编码器不认识你的 Java 类型，也不查 Spring 的 ConversionService。
手动序列化 metadata 中的特殊类型（如 LocalDateTime、Enum、嵌套对象）
必须把非 BSON 原生支持的类型（LocalDateTime、ZonedDateTime、自定义枚举、复杂 Map 等）提前转成 BSON 可存的格式，再塞进 Document。推荐统一用字符串或长整型表示时间，用字符串表示枚举名。
实操建议：
-
LocalDateTime→String：用DateTimeFormatter.ISO_LOCAL_DATE_TIME格式化，例如"2026-04-14T05:27:00"，可读、可索引、无及时区歧义 -
LocalDateTime→Long：用atZone(ZoneOffset.UTC).toInstant().toEpochMilli()，适合排序和范围查询 - 枚举 →
String：调用myEnum.name()，别用ordinal()（重构易崩） - 避免在
metadata放嵌套Document或数组以外的结构；MongoDB 查询语法对深层嵌套字段支持有限，建索引也麻烦
示例：
Document metadata = new Document()
.append("userId", "usr_abc123")
.append("type", FileType.IMAGE.name()) // 枚举转字符串
.append("uploadedAt", Instant.now().toEpochMilli()) // Long 时间戳
.append("tags", Arrays.asList("avatar", "v2")); // 纯字符串列表
给 metadata 字段建索引才能高效查询
GridFS 默认不会为 metadata 里的字段建索引，所有基于 metadata 的查询（如 find(Filters.eq("metadata.userId", "usr_abc123"))）都会触发 collection scan，数据量一过万就明显变慢。
必须手动在 fs.files 集合上创建复合索引：
- 用
mongo shell执行：db.fs.files.createIndex({"metadata.userId": 1, "metadata.type": 1, "metadata.uploadedAt": -1}) - 或在 Spring Boot 启动时用
MongoTemplate创建：mongoTemplate.indexOps("fs.files").ensureIndex(new Index().on("metadata.userId", Direction.ASC).on("metadata.type", Direction.ASC)); - 注意：索引字段路径必须带
metadata.前缀，不能只写userId - 如果用了非默认 bucket 名（比如
"uploads"），索引要建在uploads.files上，不是fs.files
为什么不用 GridFsTemplate 而推荐 GridFSBucket
GridFsTemplate 在 Spring Data MongoDB 3.0+ 已被标记为 @Deprecated，它内部封装了一层 MappingMongoConverter，容易让人误以为能自动处理 POJO 元数据——实际只是把整个 POJO toString() 或抛异常，不可靠。
GridFSBucket 更轻量、更透明：
- 输入输出都是明确的
Document和InputStream/OutputStream，没隐藏转换逻辑 - 不依赖
MappingMongoConverter，不会偷偷尝试转换你传进去的LocalDateTime - API 直接对应 MongoDB 原生驱动语义，出问题容易定位到 BSON 层
- 上传/下载过程可控（支持断点续传、进度监听等高级场景）
真正需要“转换”的地方，是你自己构造 Document metadata 的那一行代码——其余全是显式、可测、可调试的。
