自动配置 (Auto-configuration)

Spring Boot 的自动配置会尝试根据你添加的 Jar 依赖自动配置你的 Spring 应用程序。例如，如果 HSQLDB 位于你的类路径下，并且你没有手动配置任何数据库连接 Bean，那么 Spring Boot 就会自动配置一个内存数据库。

你需要在你的某个 @Configuration 类上添加 @EnableAutoConfiguration 或 @SpringBootApplication 注解来启用自动配置。

提示

你应该只添加一个 @SpringBootApplication 或 @EnableAutoConfiguration 注解。我们通常建议你只将其中一个添加到你的主要 @Configuration 类上。

1. 逐步替换自动配置

自动配置是非侵入性的。在任何时候，你都可以定义自己的配置来替换自动配置的特定部分。例如，一旦你添加了自己的 DataSource Bean，默认的嵌入式数据库支持就会退缩。

如果你需要找出当前正在应用哪些自动配置以及原因，请使用 --debug 开关启动你的应用程序。这将为核心日志记录器启用调试日志，并将“条件报告（Conditions Report）”打印到控制台。

2. 禁用特定的自动配置类

如果你发现应用了你不想要的特定自动配置类，可以使用 @SpringBootApplication 的 exclude 属性来禁用它们：

Java

import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration;

@SpringBootApplication(exclude = { DataSourceAutoConfiguration.class })
public class MyApplication {
}

Kotlin

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration

@SpringBootApplication(exclude = [DataSourceAutoConfiguration::class])
class MyApplication

如果类不在类路径下，你可以使用 excludeName 属性并指定全限定名（Fully Qualified Name）。如果你更喜欢使用 @EnableAutoConfiguration 而不是 @SpringBootApplication，同样可以使用 exclude 或 excludeName。此外，你还可以通过配置文件中的 spring.autoconfigure.exclude 属性来控制排除列表。

::: note 注意 虽然自动配置类是 public 的，但该类中唯一被视为公共 API 的部分是它的类名（用于排除）。由于这些类的内部内容（如嵌套配置类或 Bean 方法）是供内部使用的，我们不建议直接使用它们。 :::

3. 自动配置包 (Auto-configuration Packages)

“自动配置包”是指各种自动配置特性（如 JPA 实体扫描、Spring Data 仓库扫描）默认查找的包。@EnableAutoConfiguration （直接引用或通过 @SpringBootApplication 间接引用）决定了默认的自动配置包。你可以使用 @AutoConfigurationPackage 注解来配置额外的包。

---

补充教学

1. 自动配置的核心：@ConditionalOn*

自动配置类通常位于 spring-boot-autoconfigure.jar 中。它们之所以能如此智能，是因为大量使用了条件注解，例如：

• @ConditionalOnClass: 只有类路径下存在某个类时才生效。
• @ConditionalOnMissingBean: 只有当你没有手动定义某个 Bean 时才生效。
• @ConditionalOnProperty: 只有某个配置项等于特定值时才生效。

2. 如何阅读 Debug 报告？

启动应用时带上 --debug，你会看到类似 Positive matches（生效的项目）和 Negative matches（不生效的项目及其原因）的列表。这是排查“为什么我的 Bean 没生效”或“为什么它自动连了 H2 数据库”的最快方法。

3. 排除自动配置的常见案例

最常见的场景是在编写测试且不需要连接真实数据库时，排除 DataSourceAutoConfiguration。或者当你引用了一个包含自动配置的第三方 Starter，但你由于架构原因需要完全接管其配置逻辑时。