Spring Data MongoDB 中 ApplicationListener 导致的循环依赖问题解析

问题背景

在将项目从 Spring Boot 2.7.9 升级到 3.3.1 版本时，开发者遇到了一个典型的循环依赖问题。这个问题特别出现在使用 Spring Data MongoDB 的场景下，当服务类实现了 ApplicationListener 接口并依赖 MongoTemplate 时就会触发。

问题本质

这个问题的核心在于 Spring 容器的初始化顺序和 ApplicationListener 的特殊性。ApplicationListener 实现类会在 Spring 容器生命周期的早期阶段就被处理，因为容器需要它们来接收和处理各种技术性应用事件。而 MongoDB 的对象转换基础设施也会发布这样的事件。

当 MongoMappingContext 初始化时，它会触发一系列依赖关系：

1. MongoTemplate 需要 MappingMongoConverter
2. MappingMongoConverter 需要 MongoMappingContext
3. MongoMappingContext 会扫描 @Document 注解的类
4. 如果这些类所在的包中包含了 ApplicationListener 实现类，就会导致循环依赖

典型触发场景

开发者总结了几个典型的触发场景：

1. 服务类实现了 ApplicationListener 接口并直接注入 MongoTemplate
2. 重写了 AbstractMongoClientConfiguration.getMappingBasePackages 方法，返回的包中包含 @Document 注解类
3. 配置类位于项目的根包下
4. 结合使用 WebSocket 和 MongoDB Session 存储时

解决方案

对于这个问题，Spring 团队给出了明确的解决方案：

1. 使用延迟注入

对于实现了 ApplicationListener 的服务类，应该避免直接注入 MongoTemplate，而是采用以下两种方式之一：

使用 ObjectProvider/ObjectFactory：

public ApplicationListenerServiceImpl(ObjectProvider<MongoTemplate> mongoTemplate) {
    this.mongoTemplate = mongoTemplate.getObject();
}

使用 @Lazy 注解：

public ApplicationListenerServiceImpl(@Lazy MongoTemplate mongoTemplate) {
    this.mongoTemplate = mongoTemplate;
}

2. 两种方式的区别

ObjectProvider/ObjectFactory 方式只是简单包装了目标 bean 的查找过程，而 @Lazy 注解方式则需要 Spring 创建代理对象。前者在性能和资源消耗上更为轻量。

3. 框架层面的改进

对于 Spring Session 中 AbstractSessionWebSocketMessageBrokerConfigurer 的非静态 ApplicationListener 声明导致的基础设施初始化问题，Spring 团队已经提交了改进方案。

最佳实践建议

1. 尽量避免让业务服务类直接实现 ApplicationListener 接口，可以考虑使用事件监听器专用类
2. 对于必须实现 ApplicationListener 的服务类，采用延迟注入策略
3. 合理规划包结构，避免 @Document 类与 ApplicationListener 实现类混在同一个包下
4. 在升级 Spring Boot 版本时，特别注意 2.7.12 版本引入的这一变化

总结

这个问题展示了 Spring 容器初始化顺序和依赖管理的重要性。理解 ApplicationListener 的特殊生命周期和合理使用延迟注入策略，是解决这类循环依赖问题的关键。对于框架使用者来说，遵循这些最佳实践可以避免类似的初始化问题，确保应用平稳运行。