SpringBoot 3 启用 spring.factories 后如何升级替换原有的 spring.factories ？

前言

Spring Boot 3 弃用 spring.factories 不是简单的"喜新厌旧"，而是一次为了解决历史包袱、拥抱云原生和原生编译的"外科手术式"切割。这背后是旧机制在新时代下的全面溃败。

为何要弃用 spring.factories

根本原因在于，spring.factories 基于运行时全量扫描和反射的机制，已成为Spring Boot追求更快启动、更好模块化，特别是支持GraalVM原生镜像（Native Image）的核心障碍。

1. 启动性能差

启动时必须扫描所有Jar包的spring.factories文件，依赖越多，启动越慢。

2. 与GraalVM原生编译冲突

其运行时动态扫描和反射机制，与GraalVM要求静态分析所有代码的AOT（提前编译）模式根本性不兼容。

3. 无视条件加载

先加载所有类到内存，再用@Conditional注解判断是否启用，造成资源浪费。

4. 模块化支持差

与Java 9+模块系统（JPMS）强调的显式依赖和封装性理念冲突。

5. 配置难以维护

配置分散在众多第三方Jar中，出现问题时难以全局掌控和排查。

精准迁移指南

SpringBoot 3.0 新方案的核心思路是按功能"分文件"，推出了 imports 文件机制实现 spring.factories 原有的能力。

新机制把配置文件都统一放到 META-INF/spring/ 目录下，按扩展点类型拆分文件，一种扩展点对应一个文件。

例如：

自动配置类对应：AutoConfiguration.imports
ApplicationContextInitializer对应：ApplicationContextInitializer.imports
FailureAnalyzer对应：FailureAnalyzer.imports

升级的核心操作是将原有配置从 META-INF/spring.factories 迁移到新的 META-INF/spring/ 目录下。

1. 自动配置类迁移 (最常见)

这是最直接的改动。将原来在 spring.factories 中 EnableAutoConfiguration 键下的所有类，移动到新文件，每行一个。

复制代码

# 旧: META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.FooAutoConfiguration,\
com.example.BarAutoConfiguration

# 新: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.FooAutoConfiguration
com.example.BarAutoConfiguration

同时，将自动配置类上的 @Configuration 注解替换为 @AutoConfiguration，以获得更好的AOT支持。

2. 其他扩展点迁移

对于ApplicationListener、ApplicationContextInitializer等，Spring Boot 3提供了两种迁移路径：

方式一：使用对应的 imports 文件 (推荐)

例如，为ApplicationListener创建 META-INF/spring/org.springframework.context.ApplicationListener.imports 文件并写入类名。

方式二：使用 @Bean 在配置类中显式声明

这种方式更灵活，且完全避开了文件配置。

复制代码

@Configuration
public class MyConfig {
    @Bean
    public ApplicationListener<MyEvent> myListener() {
        return new MyApplicationListener();
    }
}

3. 处理第三方依赖的兼容性

Spring Boot 3.0 在一定时期内保留了对于 spring.factories 中部分非自动配置项的向后兼容。但如果你的项目依赖的第三方库尚未更新，可能会导致其自动配置失效。此时，你可以：

等待或催促该库发布兼容Spring Boot 3的版本。
临时自行创建 imports 文件：在你自己项目的 META-INF/spring 目录下，手动创建并写入需要的那几个第三方自动配置类的全限定名。这是一种有效的临时解决方案。

升级实践建议

使用迁移工具：在升级前，先使用Spring Boot官方提供的 spring-boot-properties-migrator 和 spring-boot-autoconfigure-processor 依赖，它们能帮助你识别不兼容的配置并生成新的imports文件。
分步迁移：对于大型项目，不要试图一次性修改所有依赖。可以先将项目框架升级到Spring Boot 2.7（该版本已引入新机制作为过渡），逐一解决内部模块的迁移，最后再升级到Spring Boot 3.x。
彻底测试：务必对应用启动、核心功能、集成测试等进行充分验证，确保没有因自动配置加载顺序或缺失而导致的问题。

总而言之，这次变革是Spring Boot向更高性能、更云原生架构进化的必然一步。虽然迁移需要付出一些成本，但新机制带来的启动性能提升和对原生编译的完美支持，无疑是值得的。

🎁 福利时间

如果你正在备战面试或者想要学习其他知识，给大家推荐一个宝藏知识库，作者整理了一些列 Java 程序员需要掌握的核心知识，有需要的自取不谢。

知识库地址：https://farerboy.com/