跳到主要内容
约 7 分钟2 张卡

Spring Boot 自动配置

Spring Boot 自动配置是 Boot 根据类路径、配置属性和容器里已有的 Bean,按条件替应用注册默认组件的机制。例如,应用自己声明了 ObjectMapper,Boot 就不再注册默认的 ObjectMapper。

理解自动配置,要能解释默认组件从哪里来、满足什么条件才注册、怎样让位给用户配置。这也能帮助我们排查某个 Bean 为什么没有出现。本文以 Boot 3.5 为准,Boot 2.7 的登记方式见常见问题。

1. 面试核心​

先记住这几条,再读正文
  • Boot 3.x 由 @EnableAutoConfiguration 从 AutoConfiguration.imports 读取自动配置候选,再经过排除、排序和条件匹配决定注册哪些定义。卡 · 候选自动配置类
  • @ConditionalOnMissingBean 在已处理的定义里找到匹配的 Bean 时,跳过默认 Bean 的注册,用户配置因此优先。
  • 自动配置的 before、after 只控制定义的处理顺序,Bean 实例什么时候创建仍由依赖关系等因素决定。
  • @ConditionalOnProperty 省略 havingValue 时,属性存在且值不为 false 就算匹配;布尔开关应显式写 havingValue="true",Boot 3.5 也可以改用 @ConditionalOnBooleanProperty。卡 · 属性条件
  • 用 --debug 启动可以打印条件评估报告,Actuator 的 conditions 端点可以在运行时查询同样的结果。

2. 候选自动配置类​

Boot 要先知道有哪些默认配置可选,才能逐个判断当前应用适不适用。这份候选清单登记在下面这个文件里:

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

文件每行写一个配置类的全限定名:

com.example.payment.autoconfigure.PaymentAutoConfiguration

读取这份清单的是 @EnableAutoConfiguration,它已经包含在 @SpringBootApplication 里。它通过一个导入选择器把清单里的类交给容器:选择器负责决定哪些配置类进入容器的处理流程。候选类经过排除、排序和条件匹配,通过的才会注册 BeanDefinition,也就是容器后面用来创建 Bean 的定义。自动配置类本身用 @AutoConfiguration 声明。

自动配置类放在专用的包里,只通过 imports 文件进入容器,内部依赖用明确的 @Import 组织。如果改用宽泛的组件扫描,无关的类可能被一起带进容器,生效范围就不再只由登记文件和条件决定了。

不想要某份默认配置时,可以用 @SpringBootApplication(exclude=...) 排除它,也可以设置 spring.autoconfigure.exclude。排除适合明确停用一项功能;如果是依赖冲突导致配置出错,应该检查依赖树把冲突修掉,而不是把配置排除了事。

3. 条件注解​

条件注解用来声明配置生效的前提,例如类路径里必须有某个类,或容器里不能已有某类 Bean。下面的支付配置同时检查客户端依赖和用户是否定义了服务:

@AutoConfiguration
@ConditionalOnClass(PaymentClient.class)
@EnableConfigurationProperties(PaymentProperties.class)
class PaymentAutoConfiguration {
@Bean
@ConditionalOnMissingBean
PaymentService paymentService(PaymentProperties properties) {
return new PaymentService(properties.endpoint());
}
}

类路径里没有 PaymentClient 时,整个 PaymentAutoConfiguration 都会跳过。有这个类,才继续检查已处理的定义里是否有 PaymentService。方法上的 @ConditionalOnMissingBean 没有指定类型,就按返回类型 PaymentService 判断:没有匹配项,才注册默认 Bean;已有匹配项,就跳过这个方法。

常用条件和它们检查的对象如下:

注解判断条件
@ConditionalOnClass类路径包含指定类
@ConditionalOnBean已处理定义中存在指定 Bean
@ConditionalOnMissingBean已处理定义中缺少指定 Bean
@ConditionalOnProperty属性存在且值匹配
@ConditionalOnWebApplication应用属于指定 Web 类型

此外还有按资源是否存在、按表达式结果判断的条件。条件写在类上时控制整组配置,写在 @Bean 方法上时只控制这一个 Bean。

可选依赖缺失时怎样避免类加载失败,见 Spring Boot Starter。

4. 用户配置优先​

退让是自动配置发现用户已经提供了所需组件,便跳过默认 Bean 注册的行为。上一节的 @ConditionalOnMissingBean 就是这样工作的:用户自己声明一个 PaymentService,自动配置便保留用户的实现。

注意退让发生在注册之前,默认定义根本没有进入容器。这和「两份同名定义都注册了,后一份覆盖前一份」是两回事。

Bean 条件只能看到评估时已经处理过的定义。Boot 让自动配置排在用户配置之后处理,就是为了让 @ConditionalOnMissingBean 能看到用户的定义。自动配置之间如果也有依赖,比如某个条件需要看到另一份自动配置注册的 Bean,就用 before、after 显式声明顺序,不要指望文件名或扫描顺序碰巧合适。

条件评估时,容器需要从定义中判断 Bean 的类型,所以 @Bean 方法的返回类型要提供足够的信息。如果方法只声明返回一个宽泛的接口,按具体实现类匹配的条件就可能识别不到这个 Bean。对外提供扩展点时,同样要把类型、配置属性和自动配置顺序写清楚,用户才能稳定地替换默认实现。

处理顺序确定的只是定义。实例什么时候创建,仍然由依赖关系、@DependsOn(声明显式的初始化依赖)和懒加载(推迟到第一次使用时才创建)决定。所以自动配置先处理,不代表它的对象先创建。

5. 属性条件​

属性条件用配置值做功能开关。设计一个开关,要想清楚属性缺失、值匹配、值写错三种情况分别怎么处理:

  • 属性缺失时,功能默认开还是关。
  • 属性存在时,哪些值算匹配。
  • 属性值写错时,是否让启动失败。如果不失败,一个拼写错误就可能悄悄改变行为。

下面的配置要求调用方显式开启重试:

@Bean
@ConditionalOnProperty(
prefix = "payment.retry",
name = "enabled",
havingValue = "true",
matchIfMissing = false
)
RetryPolicy retryPolicy() {
return new RetryPolicy();
}

只有 payment.retry.enabled=true 时才会注册 RetryPolicy。属性没写时,matchIfMissing=false 让条件不成立。

如果省略 havingValue,规则就变成「属性存在且值不为 false」。这时 enabled=foo 也算匹配,条件并没有把值当严格的布尔值检查。所以布尔开关要明确写 havingValue="true"。Boot 3.5 起还可以用专门的 @ConditionalOnBooleanProperty(prefix = "payment.retry", name = "enabled"),它默认要求属性值为 true,缺失时不匹配,和上面的写法等价。

一个注解里声明多个 name 时,这些属性都要匹配才算成立。集合下标形式的属性要用专门的条件判断,因为集合整体和某个下标是不同的属性键。超时范围这类取值约束不归条件管,交给 @ConfigurationProperties 绑定之后的校验,发现错误就让启动明确失败。

6. 条件评估报告​

条件评估报告记录自动配置条件的匹配结果,可以帮助解释某个 Bean 为什么没有注册。用 --debug 启动可以查看报告;应用提供了 Actuator 的 conditions 端点时,也可以通过端点查询。先找到目标自动配置,再看是哪类条件没通过:

  • 类条件失败,检查运行时的依赖树。
  • Bean 条件失败,查看已有的定义、定义来源和返回类型,确认是不是因为用户 Bean 而退让了。
  • 属性条件失败,检查属性的最终值和它来自哪里。
  • Web 条件失败,确认应用的 Web 类型。

条件成立只说明允许注册。Bean 在构造或初始化时失败,是另一类问题,要继续顺着异常链查。

7. 启动副作用​

自动配置的职责是声明组件和它们的装配关系,条件评估应该能重复执行、结果一致。如果在类加载或配置解析期间访问网络、创建线程或写文件,启动就要等外部环境响应。精简的测试上下文也会执行这些条件,副作用会拖慢测试,应用关闭时这些资源也很难清理。

确实需要连接外部系统,就把这个动作交给有生命周期的 Bean:设置连接超时,报告健康状态,停止时释放资源。还要想清楚连接失败要不要阻止应用就绪,让应用开始接收流量的时机和它真实的服务能力一致。

8. 常见问题​

8.1 spring.factories 还能登记自动配置吗?​

Boot 3.x 不能,要用 imports 文件。Boot 2.7 引入了 AutoConfiguration.imports,同时仍兼容在 spring.factories 里登记;Boot 3.0 移除了 spring.factories 中的自动配置候选登记。初始化器等其他扩展仍然可以用 spring.factories,两类用途要分开看。

8.2 @ConditionalOnMissingBean 为什么没有退让?​

9. 面试题卡片​

先想答案,再翻面先在心里答一遍,再点开卡片对照参考回答。卡片之间可以左右切换,看完会回到这里。
逐张翻看 2 张 →
未标记的卡读完后明天进入复习;已标记的按状态安排

10. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明