Spring Boot 是如何加载 Starter Configuration 的？

Question

**问题描述：** 在使用 Spring Boot 进行项目开发时，Starter Configuration 的加载机制是其自动配置功能的核心之一。常见的问题是，Spring Boot 是如何通过 `spring.factories` 或 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 文件来实现 Starter 配置的自动加载？具体而言，它是如何识别并注册这些自动配置类的？在类路径扫描、条件注解评估及 Bean 创建过程中，Spring Boot 又是如何保证配置类的正确加载与按需启用的？此外，在自定义 Starter 开发中，应如何正确配置相关文件以确保其被 Spring Boot 正确识别和加载？

Answer 1

1. Spring Boot Starter Configuration 加载机制概述

Spring Boot 的自动配置（Auto Configuration）是其简化 Spring 应用开发的核心特性之一。Starter 是一组预定义的依赖和配置，帮助开发者快速集成特定功能模块。在启动过程中，Spring Boot 会加载一系列自动配置类，这些类通常通过两种方式注册：

• META-INF/spring.factories
• META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

这两者分别对应 Spring Boot 不同版本的实现机制。

2. Spring Boot 如何识别并注册自动配置类

2.1 使用 spring.factories（适用于 Spring Boot 2.x 及更早版本）

在早期版本中，Spring Boot 通过读取所有依赖中的 META-INF/spring.factories 文件来发现自动配置类。

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.starter.ExampleAutoConfiguration
    

Spring Boot 在应用启动时会使用 SpringFactoriesLoader 类加载器查找该文件，并将其中声明的类加入自动配置候选列表。

2.2 使用 AutoConfiguration.imports（适用于 Spring Boot 3.0+）

从 Spring Boot 3.0 开始，官方推荐使用新的机制：META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件。

com.example.starter.ExampleAutoConfiguration
    

这种方式更加简洁，且避免了 spring.factories 中可能出现的性能问题。

3. 自动配置类的加载与按需启用机制

3.1 条件注解评估

Spring Boot 使用条件注解（如 @ConditionalOnClass, @ConditionalOnMissingBean 等）控制是否加载某个自动配置类或 Bean。

注解名称	用途说明
@ConditionalOnClass	当指定类存在时才启用配置
@ConditionalOnMissingBean	当容器中没有指定类型的 Bean 时才创建
@ConditionalOnProperty	根据配置文件中的属性决定是否启用配置

3.2 配置类的注册流程

整个过程大致如下：

1. Spring Boot 启动时调用 @EnableAutoConfiguration 注解；
2. 加载所有 AutoConfiguration.imports 或 spring.factories 中声明的类；
3. 对每个自动配置类进行条件判断；
4. 符合条件的类会被注册为 Spring 容器中的 Bean；
5. 最终由 Spring 上下文管理这些 Bean 的生命周期。

4. 自定义 Starter 的开发实践

4.1 步骤概览

开发一个自定义 Starter 包括以下几个关键步骤：

• 定义自动配置类（包含 Bean 定义）
• 添加必要的依赖项（如 starter-web、starter-data-jpa 等）
• 编写 AutoConfiguration.imports 或 spring.factories 文件
• 打包发布为 Maven 模块供其他项目引用

4.2 示例：一个简单的自定义 Starter

假设我们要创建一个用于打印欢迎信息的 Starter：

@Configuration
@ConditionalOnClass(name = "com.example.WelcomeService")
public class WelcomeAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public WelcomeService welcomeService() {
        return new WelcomeService("Hello from custom starter!");
    }
}
    

然后，在 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 中添加：

com.example.starter.WelcomeAutoConfiguration
    

5. 自动配置加载流程图

以下是一个 Mermaid 流程图，展示 Spring Boot 加载自动配置的过程：

graph TD
            A[Spring Boot Application 启动] --> B[扫描 @EnableAutoConfiguration]
            B --> C[读取 AutoConfiguration.imports 或 spring.factories]
            C --> D[获取所有自动配置类]
            D --> E{逐一评估条件注解}
            E -->|满足条件| F[注册为 Spring Bean]
            E -->|不满足| G[跳过加载]
            F --> H[完成自动配置]

6. 常见问题与调试技巧

6.1 自动配置未生效怎么办？

• 检查 AutoConfiguration.imports 是否正确放置在 META-INF/spring/ 路径下
• 确认自动配置类上的注解是否完整（如 @Configuration, @ConditionalOnXxx）
• 使用 --debug 参数运行应用，查看哪些自动配置类被排除

6.2 查看自动配置报告

可以通过命令行运行：

mvn spring-boot:run --debug
    

或者在代码中：

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setMainApplicationClass(DemoApplication.class);
        app.setWebApplicationType(WebApplicationType.NONE);
        ConfigurableApplicationContext context = app.run(args);
        AutoConfigurationReportLoggingListener logger = new AutoConfigurationReportLoggingListener();
        logger.onApplicationEvent(new ApplicationReadyEvent(app, args, context));
    }
}