Spring Data MongoDB 自定义 MongoTemplate 配置问题解析

问题背景

在使用 Spring Data MongoDB 时，开发者经常会遇到需要自定义 MongoDB 配置的情况。在 Spring Boot 2.7.x 版本中，通过继承 AbstractMongoClientConfiguration 并重写相关方法来自定义 MongoTemplate 是一种常见的做法。然而，升级到 Spring Boot 3.1.5 后，这种配置方式可能会遇到一些问题。

具体问题表现

当开发者尝试为 MongoTemplate 指定自定义名称时（如使用 @Bean(name = "newMongoTemplate")），系统会抛出 BeanCreationException 异常，提示找不到匹配的工厂方法。错误信息表明 Spring 容器无法找到名为 mongoTemplate() 的工厂方法来创建 bean。

问题原因分析

这个问题源于 Spring Data MongoDB 配置机制的变化。AbstractMongoClientConfiguration 类已经预定义了一组 @Bean 方法，当开发者尝试覆盖这些方法并添加自定义名称时，可能会导致 Spring 容器在解析 bean 依赖关系时出现混淆。

解决方案

Spring Data MongoDB 团队建议改用 MongoConfigurationSupport 作为基类，这提供了对 bean 创建的更精细控制。以下是推荐的配置方式：

@Configuration
@EnableMongoRepositories(mongoTemplateRef = "newMongoTemplate")
public class MongoConfiguration extends MongoConfigurationSupport {

    @Bean(name = "newMongoDatabaseFactory")
    public MongoDatabaseFactory mongoDbFactory() {
        return new SimpleMongoClientDatabaseFactory(mongoClient(), getDatabaseName());
    }

    @Bean("newMongoTemplate")
    public MongoTemplate mongoTemplate(
            @Qualifier("newMongoDatabaseFactory") MongoDatabaseFactory databaseFactory, 
            MappingMongoConverter converter) {
        return new MongoTemplate(databaseFactory, converter);
    }

    @Bean
    public MappingMongoConverter mappingMongoConverter(
            @Qualifier("newMongoDatabaseFactory") MongoDatabaseFactory databaseFactory,
            MongoCustomConversions customConversions,
            MongoMappingContext mappingContext) {
        DbRefResolver dbRefResolver = new DefaultDbRefResolver(databaseFactory);
        MappingMongoConverter converter = new MappingMongoConverter(dbRefResolver, mappingContext);
        converter.setCustomConversions(customConversions);
        converter.setCodecRegistryProvider(databaseFactory);
        return converter;
    }

    @Bean
    MongoTransactionManager transactionManager(
            @Qualifier("newMongoDatabaseFactory") MongoDatabaseFactory dbFactory) {
        return new MongoTransactionManager(dbFactory);
    }
}

关键改进点

1. 基类变更：从 AbstractMongoClientConfiguration 改为 MongoConfigurationSupport，后者提供了更灵活的配置选项。

2. 显式创建对象：不再依赖父类的实现，而是直接实例化 SimpleMongoClientDatabaseFactory 和 MongoTemplate。

3. 完整配置：需要显式配置 MappingMongoConverter，包括设置自定义转换器和代码注册表提供者。

版本兼容性说明

虽然这个问题在 Spring Boot 2.7.x 中没有出现，但这并不意味着旧版本的行为是正确的。实际上，新的配置方式提供了更清晰、更可控的 bean 创建流程，减少了潜在的配置冲突。

最佳实践建议

1. 对于新项目，建议直接使用 MongoConfigurationSupport 作为基类。

2. 升级现有项目时，需要仔细检查所有与 MongoDB 相关的配置，确保没有隐式依赖父类实现的 bean。

3. 为不同的 MongoDB 连接配置不同的 @Qualifier 名称，以避免 bean 名称冲突。

4. 考虑将复杂的配置分解为多个 @Configuration 类，提高可维护性。

通过采用这种配置方式，开发者可以更灵活地控制 MongoDB 相关的 bean 创建过程，同时避免因版本升级带来的兼容性问题。