Spring Boot 自定义自动配置

自定义自动配置允许将通用功能封装为独立模块，其他项目引入依赖即可自动生效。

创建自动配置模块

项目结构

my-starter/
├── src/main/java/
│   └── com/example/autoconfigure/
│       ├── MyAutoConfiguration.java
│       ├── MyProperties.java
│       └── MyService.java
└── src/main/resources/
    └── META-INF/
        └── spring.factories

配置属性类

@ConfigurationProperties(prefix = "my.service")
public class MyProperties {

    private boolean enabled = true;

    private String name = "default";

    private int timeout = 3000;

    // getters and setters
}

自动配置类

@Configuration
@EnableConfigurationProperties(MyProperties.class)
@ConditionalOnClass(MyService.class)
@ConditionalOnProperty(prefix = "my.service", name = "enabled", matchIfMissing = true)
public class MyAutoConfiguration {

    private final MyProperties properties;

    public MyAutoConfiguration(MyProperties properties) {
        this.properties = properties;
    }

    @Bean
    @ConditionalOnMissingBean
    public MyService myService() {
        return new MyService(properties.getName(), properties.getTimeout());
    }
}

注册自动配置

# META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.autoconfigure.MyAutoConfiguration

Spring Boot 2.7+ 新方式

# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.autoconfigure.MyAutoConfiguration

条件注解设计

检测依赖存在

@Configuration
@ConditionalOnClass({RedisClient.class, RedisConnectionFactory.class})
public class MyRedisAutoConfiguration {
    // 只有存在Redis依赖时才加载
}

允许用户覆盖

@Bean
@ConditionalOnMissingBean
public MyService myService() {
    // 用户自定义MyService Bean时，不创建默认实现
    return new DefaultMyService();
}

配置开关

@ConditionalOnProperty(prefix = "my.service", name = "enabled", havingValue = "true", matchIfMissing = true)
// matchIfMissing=true：属性不存在时默认启用

配置顺序控制

@Configuration
@AutoConfigureBefore(RedisAutoConfiguration.class)
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
public class MyAutoConfiguration {
    // 控制与其他自动配置的加载顺序
}

Starter模块分离

推荐将自动配置与Starter分离：

my-starter/                    # Starter模块（空模块，仅管理依赖）
└── pom.xml                   # 依赖my-autoconfigure

my-autoconfigure/              # 自动配置模块
├── src/main/java/
│   └── ...autoconfigure/
└── src/main/resources/
    └── META-INF/spring.factories

<!-- my-starter/pom.xml -->
<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-autoconfigure</artifactId>
    </dependency>
</dependencies>

用户自定义覆盖

// 用户在自己的配置类中定义同名Bean覆盖默认实现
@Configuration
public class UserConfiguration {

    @Bean
    public MyService myService() {
        return new CustomMyService();  // 覆盖自动配置的默认Bean
    }
}

配置元数据

// META-INF/spring-configuration-metadata.json
{
  "properties": [
    {
      "name": "my.service.enabled",
      "type": "java.lang.Boolean",
      "description": "是否启用My服务",
      "defaultValue": true
    },
    {
      "name": "my.service.name",
      "type": "java.lang.String",
      "description": "服务名称"
    }
  ]
}

IDE会读取此文件提供配置提示。

最佳实践

要点总结

• 创建配置类使用@Configuration和条件注解
• spring.factories注册自动配置类
• @ConditionalOnMissingBean允许用户覆盖
• @ConfigurationProperties封装配置属性
• spring-configuration-metadata.json提供IDE提示
• 推荐Starter与自动配置模块分离