SpringDoc-OpenAPI 项目中的 Bean 初始化循环依赖问题分析与解决方案

问题背景

在 SpringBoot 3.4.0 及以上版本与 SpringDoc 2.7.0 及以上版本集成时，部分开发者遇到了一个关于 openApiResource Bean 初始化的问题。系统启动时会抛出 BeanCurrentlyInCreationException 异常，提示存在循环依赖或异步初始化依赖问题。

问题现象

异常堆栈显示，在创建 openApiResource Bean 时，系统检测到该 Bean 正在被其他线程创建中。具体表现为：

1. OpenAPIService.build() 方法尝试通过 context.getBeansWithAnnotation(RestController.class) 获取所有带有 @RestController 注解的 Bean
2. 其中需要获取 OpenApiWebMvcResource 实例
3. 但 OpenApiWebMvcResource 又需要注入 OpenAPIService 实例
4. 这就形成了一个初始化依赖环

技术分析

深入分析 SpringDoc-OpenAPI 的源码，问题根源在于：

1. 初始化时序问题：OpenAPIService 在构建 OpenAPI 文档时需要扫描所有 @RestController 注解的控制器，包括 SpringDoc 自身的 OpenApiWebMvcResource
2. 线程安全问题：SpringDoc 使用了线程池进行预加载，而 Bean 的初始化过程本身是单线程的
3. SpringBoot 3.x 的变化：新版本 SpringBoot 对 Bean 的加载顺序和初始化机制有所调整，可能影响了这种复杂依赖场景下的行为

解决方案

临时解决方案

1. 禁用预加载：在配置文件中设置 springdoc.pre-loading.enabled=false
2. 延迟初始化：确保 OpenAPIService 在完全初始化后再进行 API 文档的构建

推荐解决方案

基于对问题的理解，可以采用以下更优雅的解决方案：

@Configuration
public class SpringDocFixConfig {
    
    @Autowired
    private AbstractOpenApiResource abstractOpenApiResource;
    
    @Autowired
    private SpringDocConfigProperties springDocConfigProperties;

    @EventListener(ApplicationReadyEvent.class)
    public void initOpenApiAfterStartup() {
        if (springDocConfigProperties.isPreLoadingEnabled()) {
            if (CollectionUtils.isEmpty(springDocConfigProperties.getPreLoadingLocales())) {
                abstractOpenApiResource.getOpenApi();
            } else {
                springDocConfigProperties.getPreLoadingLocales().forEach(locale -> 
                    abstractOpenApiResource.getOpenApi(Locale.forLanguageTag(locale))
                );
            }
        }
    }
}

这种方案的优点在于：

1. 确保所有 Bean 都已完全初始化后再执行 OpenAPI 文档的构建
2. 保持了原有的预加载功能
3. 避免了多线程环境下的初始化竞争问题

最佳实践建议

1. 在复杂系统中，谨慎使用 Bean 初始化阶段的异步操作
2. 对于文档生成这类非关键路径功能，考虑采用懒加载或事件驱动的方式
3. 升级 SpringBoot 和 SpringDoc 版本时，注意测试 API 文档相关功能
4. 在大型项目中，考虑将文档生成与实际业务逻辑解耦

总结

SpringDoc-OpenAPI 是一个强大的 API 文档生成工具，但在复杂项目集成时可能会遇到 Bean 初始化顺序问题。理解 Spring 容器的初始化机制和 Bean 生命周期对于解决这类问题至关重要。通过事件驱动的方式延迟文档生成操作，既解决了初始化依赖问题，又保持了系统的原有功能，是一种值得推荐的解决方案。