Spring Boot @EnableConfigurationProperties 注解详解

激活带有`@ConfigurationProperties` 条件注解的类，让 Spring 容器识别并管理该实体类的 Bean。

`@EnableConfigurationProperties` 是 Spring Boot 提供的核心注解，核心作用是：开启配置属性绑定功能，允许将配置文件（application.yml/application.properties）中的值，绑定到自定义的 Java 实体类中，实现配置的统一管理和复用。

简单理解：它是“配置文件”和“Java实体类”之间的“桥梁”，让我们可以用面向对象的方式操作配置，而不用每次都通过 `@Value` 注解逐个获取配置值。

一、核心用途

• 将配置文件中的自定义配置，批量绑定到 Java 实体类（通常带有 `@ConfigurationProperties` 注解）。

• 激活带有 `@ConfigurationProperties` 注解的类，让 Spring 容器识别并管理该实体类的 Bean。

• 替代传统的 `@Value` 注解，解决多配置项批量绑定、类型转换、配置校验等问题，提升配置管理的规范性。

二、核心关联注解

`@EnableConfigurationProperties` 通常与 `@ConfigurationProperties` 配合使用，二者缺一不可：

• `@ConfigurationProperties`：用于标记 Java 实体类，指定配置文件的前缀，声明该类用于接收配置值。

• `@EnableConfigurationProperties`：用于开启配置绑定功能，告诉 Spring Boot 去扫描并绑定带有 `@ConfigurationProperties` 的类。

三、常用用法（分场景）

场景1：基础用法（绑定单个配置实体类）

1. 自定义配置实体类（带 @ConfigurationProperties）

import org.springframework.boot.context.properties.ConfigurationProperties;
import lombok.Data;

// 绑定配置文件中前缀为 "my.app" 的配置
@Data //  lombok 注解，简化get/set方法（可手动编写）
@ConfigurationProperties(prefix = "my.app")
public class AppConfigProperties {
    // 配置项：my.app.name
    private String name;
    // 配置项：my.app.port
    private Integer port;
    // 配置项：my.app.enabled（可选，可设置默认值）
    private Boolean enabled = true;
}

2. 开启配置绑定（两种方式）

方式1：在配置类上添加 @EnableConfigurationProperties，指定要绑定的实体类

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration
// 开启配置绑定，并指定要绑定的实体类
@EnableConfigurationProperties(AppConfigProperties.class)
public class AppConfig {
    // 此时 AppConfigProperties 会被 Spring 容器管理，可直接注入使用
}

方式2：在实体类上直接添加 @Component（无需在配置类加 @EnableConfigurationProperties）

@Data
@Component // 直接将实体类注册为Bean
@ConfigurationProperties(prefix = "my.app")
public class AppConfigProperties {
    private String name;
    private Integer port;
    private Boolean enabled = true;
}

说明：两种方式效果一致，推荐方式1（解耦，实体类无需感知 Spring 容器）。

3. 配置文件（application.yml）

# 自定义配置，前缀为 my.app
my:
  app:
    name: test-app
    port: 8080
    # enabled: false  # 可选，不配置则使用实体类默认值 true

4. 注入使用

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TestController {

    // 直接注入绑定好配置的实体类
    @Autowired
    private AppConfigProperties appConfigProperties;

    @GetMapping("/config")
    public String getConfig() {
        return "应用名称：" + appConfigProperties.getName() + 
               "，端口：" + appConfigProperties.getPort() + 
               "，是否启用：" + appConfigProperties.getEnabled();
    }
}

场景2：绑定多个配置实体类

在 @EnableConfigurationProperties 中传入多个实体类，用逗号分隔即可：

@Configuration
// 同时绑定 AppConfigProperties 和 DbConfigProperties 两个实体类
@EnableConfigurationProperties({AppConfigProperties.class, DbConfigProperties.class})
public class AppConfig {
    // 两个实体类均会被 Spring 管理，可直接注入
}

四、关键注意事项

• 实体类必须提供 getter/setter 方法（否则配置无法绑定，可通过 lombok 的 @Data 注解简化）。

• 配置项的类型必须与实体类字段类型一致（如配置文件中 port 是数字，实体类字段必须是 Integer/Long，不能是 String），否则会出现类型转换异常。

• `@EnableConfigurationProperties` 只能用在 配置类（@Configuration 标记） 或 主启动类上，不能用在普通 Bean 上。

• 若实体类同时添加了 @Component 和 @ConfigurationProperties，无需再用 @EnableConfigurationProperties 开启（Spring 会自动扫描）。

• 可配合 `@Validated` 注解实现配置校验（如限制 port 的范围、name 非空等），需导入 validation 依赖。

五、与 @Value 注解的对比

六、总结

1. 核心作用：开启配置文件与 Java 实体类的绑定功能，实现配置的批量管理。

2. 核心搭配：与 `@ConfigurationProperties` 配合使用，二者协同完成配置绑定。

3. 优势：简化配置获取、支持类型自动转换、可配置校验，适合复杂配置场景，是 Spring Boot 配置管理的推荐方式。