baeldung 2024-12-16
1. 概述
简而言之，Spring Boot 的自动配置（auto-configuration）能够根据类路径（classpath）中存在的依赖项，自动为我们配置 Spring 应用程序。
这可以显著加快开发速度并简化配置，因为它消除了手动定义某些由自动配置类提供的 Bean 的需要。
在接下来的部分中，我们将学习如何创建自己的 Spring Boot 自动配置。
2. Maven 依赖
首先，添加以下依赖项：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>com.mysql</groupId>
<artifactId>mysql-connector-j</artifactId>
</dependency>
spring-boot-starter-data-jpa 和 mysql-connector-j 的最新版本可以从 Maven Central 下载。
3. 创建自定义自动配置
要创建自定义自动配置，我们需要创建一个带有 @Configuration 注解的类，并将其注册为自动配置候选类。
下面以创建 MySQL 数据源的自定义配置为例：
@Configuration
public class MySQLAutoconfiguration {
//...
}
接下来，我们需要在标准文件 resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 中注册该类：
com.baeldung.autoconfiguration.MySQLAutoconfiguration
注意：在 Spring Boot 2.7 及更高版本中，自动配置类应通过
META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件注册，而不是旧版的spring.factories。
如果希望我们的自动配置类具有比其他候选类更高的优先级，可以使用 @AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE) 注解。
我们通常结合使用 @Conditional 系列注解来设计自动配置类和 Bean，这样可以在必要时替换整个自动配置或其中的特定部分。
需要注意的是：只有当应用程序中未显式定义自动配置所要创建的 Bean 时，自动配置才会生效。如果用户自己定义了某个 Bean，它将覆盖自动配置提供的默认实现。
3.1 类条件（Class Conditions）
我们可以使用 @ConditionalOnClass 注解指定：仅当某个类存在于 classpath 上时才加载配置；或者使用 @ConditionalOnMissingClass 表示该类不存在时才加载。
例如，我们希望只有在存在 DataSource 类时才加载 MySQL 配置（这意味着应用会使用数据库）：
@Configuration
@ConditionalOnClass(DataSource.class)
public class MySQLAutoconfiguration {
//...
}
3.2 Bean 条件（Bean Conditions）
若希望仅在特定 Bean 存在或不存在时才创建某个 Bean，可使用 @ConditionalOnBean 或 @ConditionalOnMissingBean。
例如，我们添加一个 entityManagerFactory Bean，仅当存在名为 dataSource 的 Bean 且尚未定义 entityManagerFactory 时才创建它：
@Bean
@ConditionalOnBean(name = "dataSource")
@ConditionalOnMissingBean
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
LocalContainerEntityManagerFactoryBean em = new LocalContainerEntityManagerFactoryBean();
em.setDataSource(dataSource());
em.setPackagesToScan("com.baeldung.autoconfiguration.example");
em.setJpaVendorAdapter(new HibernateJpaVendorAdapter());
if (additionalProperties() != null) {
em.setJpaProperties(additionalProperties());
}
return em;
}
再比如，配置一个事务管理器，仅当尚未定义 JpaTransactionManager 类型的 Bean 时才创建：
@Bean
@ConditionalOnMissingBean(type = "JpaTransactionManager")
JpaTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
JpaTransactionManager transactionManager = new JpaTransactionManager();
transactionManager.setEntityManagerFactory(entityManagerFactory);
return transactionManager;
}
3.3 属性条件（Property Conditions）
使用 @ConditionalOnProperty 注解可以根据 Spring 环境属性的存在与否及其值来决定是否加载配置。
首先，通过 @PropertySource 指定属性文件位置：
@PropertySource("classpath:mysql.properties")
public class MySQLAutoconfiguration {
//...
}
然后，我们可以让 dataSource Bean 仅在 usemysql 属性存在且值为 "local" 时才被创建，并使用默认连接参数连接本地数据库 myDb：
@Bean
@ConditionalOnProperty(name = "usemysql", havingValue = "local")
@ConditionalOnMissingBean
public DataSource dataSource() {
DriverManagerDataSource dataSource = new DriverManagerDataSource();
dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
dataSource.setUrl("jdbc:mysql://localhost:3306/myDb?createDatabaseIfNotExist=true");
dataSource.setUsername("mysqluser");
dataSource.setPassword("mysqlpass");
return dataSource;
}
如果 usemysql 的值为 "custom"，则从属性文件中读取自定义的数据库连接信息：
@Bean(name = "dataSource")
@ConditionalOnProperty(name = "usemysql", havingValue = "custom")
@ConditionalOnMissingBean
public DataSource dataSource2() {
DriverManagerDataSource dataSource = new DriverManagerDataSource();
dataSource.setDriverClassName("com.mysql.cj.jdbc.Driver");
dataSource.setUrl(env.getProperty("mysql.url"));
dataSource.setUsername(env.getProperty("mysql.user") != null
? env.getProperty("mysql.user") : "");
dataSource.setPassword(env.getProperty("mysql.pass") != null
? env.getProperty("mysql.pass") : "");
return dataSource;
}
对应的 mysql.properties 文件内容如下：
usemysql=local
如果应用程序希望覆盖默认配置，只需在自己的 mysql.properties（或 application.properties）中设置 usemysql=custom 并提供 mysql.url、mysql.user 和 mysql.pass 的值即可。
3.4 资源条件（Resource Conditions）
使用 @ConditionalOnResource 注解可确保配置仅在指定资源存在时才加载。
例如，我们定义一个 additionalProperties() 方法，仅当 mysql.properties 文件存在时才返回 Hibernate 相关属性：
@ConditionalOnResource(resources = "classpath:mysql.properties")
@Conditional(HibernateCondition.class)
Properties additionalProperties() {
Properties hibernateProperties = new Properties();
hibernateProperties.setProperty("hibernate.hbm2ddl.auto",
env.getProperty("mysql-hibernate.hbm2ddl.auto"));
hibernateProperties.setProperty("hibernate.dialect",
env.getProperty("mysql-hibernate.dialect"));
hibernateProperties.setProperty("hibernate.show_sql",
env.getProperty("mysql-hibernate.show_sql") != null
? env.getProperty("mysql-hibernate.show_sql") : "false");
return hibernateProperties;
}
在 mysql.properties 中添加 Hibernate 配置：
mysql-hibernate.dialect=org.hibernate.dialect.MySQLDialect
mysql-hibernate.show_sql=true
mysql-hibernate.hbm2ddl.auto=create-drop
3.5 自定义条件（Custom Conditions）
如果 Spring Boot 提供的条件注解无法满足需求，我们可以自定义条件。
例如，创建一个 HibernateCondition 类，用于检查 classpath 上是否存在 Hibernate 的 EntityManager 实现：
static class HibernateCondition extends SpringBootCondition {
private static String[] CLASS_NAMES = {
"org.hibernate.ejb.HibernateEntityManager",
"org.hibernate.jpa.HibernateEntityManager"
};
@Override
public ConditionOutcome getMatchOutcome(ConditionContext context, AnnotatedTypeMetadata metadata) {
ConditionMessage.Builder message = ConditionMessage.forCondition("Hibernate");
return Arrays.stream(CLASS_NAMES)
.filter(className -> ClassUtils.isPresent(className, context.getClassLoader()))
.map(className -> ConditionOutcome.match(
message.found("class").items(Style.NORMAL, className)))
.findAny()
.orElseGet(() -> ConditionOutcome.noMatch(
message.didNotFind("class", "classes")
.items(Style.NORMAL, Arrays.asList(CLASS_NAMES))));
}
}
然后将其应用于方法：
@Conditional(HibernateCondition.class)
Properties additionalProperties() {
//...
}
3.6 应用上下文条件（Application Conditions）
我们还可以通过 @ConditionalOnWebApplication 或 @ConditionalOnNotWebApplication 注解，控制配置是否仅在 Web 应用（或非 Web 应用）环境中加载。
4. 测试自动配置
创建一个简单示例来验证我们的自动配置。
首先定义一个实体类 MyUser 和对应的 Spring Data Repository：
@Entity
public class MyUser {
@Id
private String email;
// 标准构造函数、getter、setter
}
public interface MyUserRepository extends JpaRepository<MyUser, String> { }
在主应用类上启用自动配置（通过 @SpringBootApplication，它内部包含 @EnableAutoConfiguration）：
@SpringBootApplication
public class AutoconfigurationApplication {
public static void main(String[] args) {
SpringApplication.run(AutoconfigurationApplication.class, args);
}
}
编写一个 JUnit 测试，保存一个 MyUser 实体：
@RunWith(SpringJUnit4ClassRunner.class)
@SpringBootTest(classes = AutoconfigurationApplication.class)
@EnableJpaRepositories(basePackages = { "com.baeldung.autoconfiguration.example" })
public class AutoconfigurationLiveTest {
@Autowired
private MyUserRepository userRepository;
@Test
public void whenSaveUser_thenOk() {
MyUser user = new MyUser("user@email.com");
userRepository.save(user);
}
}
由于我们没有显式定义 DataSource，应用程序将使用我们创建的自动配置连接到名为 myDb 的 MySQL 数据库。
连接字符串中包含 createDatabaseIfNotExist=true，因此数据库无需预先存在。但数据库用户（如 mysqluser 或通过 mysql.user 指定的用户）必须已创建。
可通过日志确认是否使用了 MySQL 数据源：
web - 2017-04-12 00:01:33,956 [main] INFO o.s.j.d.DriverManagerDataSource - Loaded JDBC driver: com.mysql.cj.jdbc.Driver
5. 禁用自动配置类
如果我们希望排除某个自动配置类，可以通过以下方式：
- 在配置类上使用
@EnableAutoConfiguration的exclude属性：
@Configuration
@EnableAutoConfiguration(exclude = {MySQLAutoconfiguration.class})
public class AutoconfigurationApplication {
//...
}
- 或在
application.properties中设置：
spring.autoconfigure.exclude=com.baeldung.autoconfiguration.MySQLAutoconfiguration
6. 结论
本文展示了如何创建一个自定义的 Spring Boot 自动配置类。通过合理使用条件注解（如 @ConditionalOnClass、@ConditionalOnProperty 等），我们可以构建灵活、可复用且易于集成的自动配置模块，从而提升开发效率和项目可维护性。