GridFsTemplate 默认不生效，因 Spring Boot 未自动配置；需手动声明 @Bean 并显式传入 bucket 名（如 "files"），支持多 bucket 共存但须命名区分且符合 MongoDB 集合命名规范。
必须显式传入 bucket 名，否则默认用 fs；不配置就直接用 GridFsTemplate 会报 NoSuchBeanDefinitionException。
为什么 GridFsTemplate 默认不生效
Spring Boot 的 spring-boot-starter-data-mongodb 只自动装配 MongoTemplate 和 MongoDatabaseFactory，GridFsTemplate 不在自动配置范围内。哪怕你写了 @Autowired GridFsTemplate gridFsTemplate，IOC 容器里根本没这个 bean。
- 错误现象：
Field gridFsTemplate required a bean of type 'org.springframework.data.mongodb.gridfs.GridFsTemplate' that could not be found - 原因：starter 没扫描、没注册、也没提供默认构造逻辑
- 不是“漏配”，是设计如此——GridFS 属于可选扩展能力，得你自己声明
怎么用 GridFsTemplate 指定自定义 bucket 名
关键在构造时传第三个参数 bucket，比如 "files" 或 "tempFs"。它会自动在对应数据库下创建 files 和 files.chunks 集合（注意前缀一致）。
-
GridFsTemplate构造函数签名是：GridFsTemplate(MongoDbFactory, MongoConverter, @Nullable String bucket) - 别手写
new GridFsTemplate(...)，要用@Bean方法让 Spring 管理生命周期 -
MongoDbFactory和MongoConverter直接从容器注入即可，Spring Boot 已自动配好
@Configuration
public class GridFsConfig {
@Bean(name = "gridFsTemplate")
public GridFsTemplate gridFsTemplate(MongoDbFactory dbFactory, MongoConverter converter) {
return new GridFsTemplate(dbFactory, converter, "files");
}
}
多个 bucket 怎么共存且不冲突
一个应用里要同时用 "files" 存正式文件、"tempFs" 存临时文件，就得注册多个命名 bean，靠 @Qualifier 区分。
- 每个
@Bean必须设name，否则同类型 bean 会覆盖 - 使用时加
@Qualifier("gridTempFsTemplate")显式指定 - 不同 bucket 对应的
files和chunks集合名前缀不同，互不影响 - 注意：MongoDB 不限制 bucket 数量，但每个 bucket 的集合需独立建索引（如
db.files.files.createIndex({"metadata.userId": 1})）
容易被忽略的坑：bucket 名大小写和特殊字符
bucket 名最终映射为集合前缀，MongoDB 集合名规则直接生效——它区分大小写，且不能含空格、点号、美元符等。
- 错例：
"user files"→ 启动失败或运行时报Invalid namespace - 错例：
"user.files"→ MongoDB 拒绝创建集合 - 建议只用小写字母 + 下划线，如
"user_files"、"upload_bucket" - 一旦上线，别轻易改 bucket 名——已有文件无法跨 bucket 自动迁移
