Spring Boot中@EnableConfigurationProperties加载失败原因分析 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Spring Boot @EnableConfigurationProperties 加载失败原因分析

大家好，今天我们来深入探讨Spring Boot中 @EnableConfigurationProperties 注解使用时可能遇到的问题以及如何排查和解决这些问题。@EnableConfigurationProperties 是 Spring Boot 提供的一个非常方便的注解，用于将配置类 (Configuration Properties) 注册到 Spring 容器中，使得我们可以通过 @ConfigurationProperties 注解将外部配置（如 application.properties 或 application.yml）绑定到 Java Bean 上。但实际使用过程中，我们可能会遇到加载失败的情况，导致配置无法生效。本次讲座将详细剖析可能的原因，并提供相应的解决方案。

1. @EnableConfigurationProperties 的基本原理

首先，我们需要了解 @EnableConfigurationProperties 的作用机制。简单来说，它做了以下几件事情：

导入 ConfigurationPropertiesBindingPostProcessor: @EnableConfigurationProperties 通过 @Import 注解导入了 EnableConfigurationPropertiesRegistrar，而 EnableConfigurationPropertiesRegistrar 的核心作用是注册 ConfigurationPropertiesBindingPostProcessor 这个 BeanPostProcessor 到 Spring 容器。
ConfigurationPropertiesBindingPostProcessor 的作用: ConfigurationPropertiesBindingPostProcessor 会在 Spring 容器完成 Bean 的创建后，检查所有带有 @ConfigurationProperties 注解的 Bean，并尝试将其中的属性与外部配置进行绑定。

2. 常见加载失败的原因及解决方案

接下来，我们来分析一些常见的 @EnableConfigurationProperties 加载失败的原因，以及相应的解决方案。

2.1 配置类未被 Spring 管理

这是最常见的原因之一。如果你的配置类没有被 Spring 容器扫描到，那么即使你使用了 @EnableConfigurationProperties，Spring 也无法识别并加载它。

原因：
- 配置类没有被 @Component, @Configuration, @Service, @Repository, @Controller 等 Spring 组件注解标记。
- 配置类所在的包没有被 Spring 的组件扫描路径覆盖。

解决方案：

确保配置类被 Spring 组件注解标记： 在你的配置类上添加 @Configuration 注解，或者其他任何 Spring 组件注解，例如 @Component。

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

@Configuration
@ConfigurationProperties(prefix = "my.config")
public class MyConfig {
    private String name;
    private int age;

    // Getters and setters
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

确保配置类所在的包被 Spring 扫描： 在你的 Spring Boot 应用的主类上，使用 @SpringBootApplication 注解，它默认会扫描主类所在的包及其子包。如果你的配置类位于其他包，你需要显式指定扫描路径。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = {"com.example.demo", "com.example.config"}) // 确保包含配置类所在的包
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

2.2 @EnableConfigurationProperties 注解缺失或位置错误

如果你的配置类已经被 Spring 管理，但仍然无法加载，那么你需要检查 @EnableConfigurationProperties 注解的使用是否正确。

原因：
- 忘记添加 @EnableConfigurationProperties 注解。
- 将 @EnableConfigurationProperties 注解添加到了错误的类上。

解决方案：

添加 @EnableConfigurationProperties 注解： 确保在你的 Spring Boot 应用的主类或者任何被 @Configuration 注解标记的配置类上添加 @EnableConfigurationProperties 注解，并指定需要加载的配置类。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(MyConfig.class) // 指定需要加载的配置类
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

}

检查 @EnableConfigurationProperties 的位置： @EnableConfigurationProperties 应该放在带有 @SpringBootApplication 或者 @Configuration 注解的类上，确保它能够被 Spring 扫描到并生效。

2.3 配置属性名称与配置类属性名称不匹配

配置属性名称与配置类的属性名称不匹配是另一个常见的问题。Spring Boot 默认使用 relaxed binding 规则，它允许配置属性名称与配置类的属性名称之间存在一定的差异，但如果差异过大，或者配置属性名称完全错误，那么绑定就会失败。

原因：
- 配置属性名称拼写错误。
- 配置属性名称与配置类的属性名称不符合 relaxed binding 规则。
解决方案：
1. 检查配置属性名称： 仔细检查你的 application.properties 或 application.yml 文件，确保配置属性名称与配置类的属性名称一致。
```
# application.properties
my.config.name=testName
my.config.age=20
```
2. 遵循 relaxed binding 规则： Spring Boot 允许使用以下几种方式来命名配置属性：
  - Kebab case (kebab-case): 例如 my-config-name
  - Camel case (camelCase): 例如 myConfigName
  - Snake case (snake_case): 例如 my_config_name
  确保你的配置属性名称与配置类的属性名称符合这些规则。例如，如果配置类的属性名为 myConfigName，那么以下配置属性名称都是有效的：
  - my.config-name
  - my.configName
  - my.config_name
3. 使用 @Value 注解： 如果你只想绑定单个属性，而不是整个配置类，可以使用 @Value 注解。
```
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class MyComponent {

    @Value("${my.config.name}")
    private String name;

    // Getter and setter
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}
```

2.4 配置属性类型不匹配

如果配置属性的类型与配置类的属性类型不匹配，那么绑定也会失败。例如，如果配置属性的值是字符串，而配置类的属性类型是整数，那么 Spring Boot 会尝试进行类型转换，如果转换失败，就会抛出异常。

原因：
- 配置属性的值与配置类的属性类型不兼容。
- 类型转换失败。

解决方案：

确保配置属性类型匹配： 确保你的配置属性的值与配置类的属性类型兼容。例如，如果配置类的属性类型是整数，那么配置属性的值应该是一个整数。
```
# application.properties
my.config.age=20  # 确保这是一个有效的整数值
```

使用 Spring 的转换器： 如果你需要进行自定义的类型转换，可以使用 Spring 的 Converter 接口。创建一个实现了 Converter 接口的类，并将其注册到 Spring 容器中。

import org.springframework.core.convert.converter.Converter;
import org.springframework.stereotype.Component;

@Component
public class StringToIntegerConverter implements Converter<String, Integer> {

    @Override
    public Integer convert(String source) {
        try {
            return Integer.parseInt(source);
        } catch (NumberFormatException e) {
            // 处理转换失败的情况
            return null; // 或者抛出自定义异常
        }
    }

}

使用 @DateTimeFormat 注解： 如果你的配置类包含日期类型的属性，可以使用 @DateTimeFormat 注解来指定日期格式。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import org.springframework.format.annotation.DateTimeFormat;

import java.util.Date;

@Configuration
@ConfigurationProperties(prefix = "my.config")
public class MyConfig {

    @DateTimeFormat(pattern = "yyyy-MM-dd")
    private Date birthday;

    // Getter and setter
    public Date getBirthday() {
        return birthday;
    }

    public void setBirthday(Date birthday) {
        this.birthday = birthday;
    }
}

# application.properties
my.config.birthday=2023-10-27

2.5 配置属性不存在或为空

如果配置属性不存在或者为空，那么绑定可能会失败，具体取决于配置类的属性是否允许为空。

原因：
- 配置属性在 application.properties 或 application.yml 文件中不存在。
- 配置属性的值为空。

解决方案：

确保配置属性存在： 确保你的 application.properties 或 application.yml 文件中包含所有必需的配置属性。

提供默认值： 可以使用 @Value 注解的默认值功能，为配置类的属性提供默认值。

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class MyComponent {

    @Value("${my.config.name:defaultName}") // 提供默认值 "defaultName"
    private String name;

    // Getter and setter
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

使用 @ConfigurationProperties 的 ignoreInvalidFields 和 ignoreUnknownFields 属性：

ignoreInvalidFields: 如果设置为 true，则忽略无效的字段，例如类型转换失败的字段。
ignoreUnknownFields: 如果设置为 true，则忽略 application.properties 或 application.yml 文件中未在配置类中定义的属性。

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

@Configuration
@ConfigurationProperties(prefix = "my.config", ignoreInvalidFields = true, ignoreUnknownFields = true)
public class MyConfig {
    private String name;
    private int age;

    // Getters and setters
    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

2.6 配置文件的加载顺序问题

在 Spring Boot 中，配置文件的加载顺序可能会影响最终的配置结果。例如，如果你的 application.properties 和 application.yml 文件中都定义了相同的配置属性，那么后加载的文件中的值会覆盖先加载的文件中的值。

原因：
- 配置文件的加载顺序不符合预期。
- 不同的配置文件中定义了相同的配置属性，导致覆盖。
解决方案：
1. 了解配置文件的加载顺序： Spring Boot 默认按照以下顺序加载配置文件：
  1. 命令行参数
  2. 来自 SPRING_APPLICATION_JSON 的属性（环境变量或系统属性中嵌入的 JSON）
  3. ServletConfig 初始化参数
  4. ServletContext 初始化参数
  5. 来自 java:comp/env 的 JNDI 属性
  6. Java 系统属性 (System.getProperties())
  7. 操作系统环境变量
  8. 随机生成的 random.* 属性
  9. 打包在应用之外的 application-{profile}.properties 或 application-{profile}.yml 文件
  10. 打包在应用之内的 application-{profile}.properties 或 application-{profile}.yml 文件
  11. 打包在应用之外的 application.properties 或 application.yml 文件
  12. 打包在应用之内的 application.properties 或 application.yml 文件
  13. @PropertySource 注解指定的 properties 文件
  14. 默认属性配置 (通过 SpringApplication.setDefaultProperties 指定)
2. 使用 Profile： 使用 Spring Profile 可以根据不同的环境加载不同的配置文件。例如，你可以创建 application-dev.properties 和 application-prod.properties 文件，分别用于开发环境和生产环境。
3. 使用 spring.config.location 属性： 可以使用 spring.config.location 属性来指定配置文件的位置。
```
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(MyConfig.class)
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setDefaultProperties(java.util.Collections.singletonMap("spring.config.location", "classpath:/my-config.properties"));
        app.run(args);
    }

}
```

2.7 循环依赖问题

虽然不常见，但在复杂的 Spring 应用中，配置类之间可能存在循环依赖，这会导致 @ConfigurationProperties 的绑定过程出现问题。

原因：
- 配置类之间存在循环依赖，导致 Bean 的创建顺序不正确。
解决方案：
1. 避免循环依赖： 重新设计你的配置类，尽量避免循环依赖。
2. 使用 @Lazy 注解： 可以使用 @Lazy 注解来延迟 Bean 的初始化，从而解决循环依赖问题。
```
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Lazy;

@Configuration
public class ConfigA {

    private final ConfigB configB;

    public ConfigA(@Lazy ConfigB configB) {
        this.configB = configB;
    }
}
```
3. 使用 @Autowired(required = false)： 有时，可以将依赖设置为可选的，并在需要时进行检查。

3. 调试技巧

当遇到 @EnableConfigurationProperties 加载失败的问题时，可以使用以下调试技巧来定位问题：

启用 DEBUG 日志： 在 application.properties 或 application.yml 文件中设置 logging.level.org.springframework.boot.context.properties=DEBUG，可以查看 Spring Boot 配置属性绑定的详细日志。
使用断点调试： 在 ConfigurationPropertiesBindingPostProcessor 类的 postProcessBeforeInitialization 方法中设置断点，可以查看配置属性绑定的过程。
检查 Spring 容器中的 Bean： 使用 Spring 的 ApplicationContext API，可以查看 Spring 容器中注册的所有 Bean，以及它们的属性值。

表格总结常见问题和解决方案

问题	原因	解决方案
配置类未被 Spring 管理	配置类没有被 Spring 组件注解标记，或者所在的包没有被 Spring 扫描。	1. 确保配置类被 `@Component` 或 `@Configuration` 等注解标记。 2. 使用 `@ComponentScan` 指定扫描路径。
`@EnableConfigurationProperties` 注解缺失或位置错误	忘记添加 `@EnableConfigurationProperties` 注解，或者添加到错误的类上。	1. 添加 `@EnableConfigurationProperties` 注解，并指定需要加载的配置类。 2. 确保 `@EnableConfigurationProperties` 注解位于带有 `@SpringBootApplication` 或 `@Configuration` 注解的类上。
配置属性名称与配置类属性名称不匹配	配置属性名称拼写错误，或者不符合 relaxed binding 规则。	1. 检查配置属性名称，确保与配置类的属性名称一致。 2. 遵循 relaxed binding 规则（kebab-case, camelCase, snake_case）。 3. 使用 `@Value` 注解绑定单个属性。
配置属性类型不匹配	配置属性的值与配置类的属性类型不兼容，或者类型转换失败。	1. 确保配置属性类型匹配。 2. 使用 Spring 的 `Converter` 接口进行自定义类型转换。 3. 使用 `@DateTimeFormat` 注解指定日期格式。
配置属性不存在或为空	配置属性在配置文件中不存在，或者值为空。	1. 确保配置属性存在。 2. 使用 `@Value` 注解提供默认值。 3. 使用 `@ConfigurationProperties` 的 `ignoreInvalidFields` 和 `ignoreUnknownFields` 属性。
配置文件的加载顺序问题	配置文件的加载顺序不符合预期，或者不同的配置文件中定义了相同的配置属性。	1. 了解配置文件的加载顺序。 2. 使用 Spring Profile。 3. 使用 `spring.config.location` 属性指定配置文件的位置。
循环依赖问题	配置类之间存在循环依赖，导致 Bean 的创建顺序不正确。	1. 避免循环依赖。 2. 使用 `@Lazy` 注解延迟 Bean 的初始化。 3. 使用 `@Autowired(required = false)` 设置依赖为可选的。

4. 总结

@EnableConfigurationProperties 加载失败的原因有很多，但通过仔细检查配置类的注解、配置属性的名称和类型、以及配置文件的加载顺序，我们可以有效地定位问题并解决问题。希望本次讲座能够帮助大家更好地理解和使用 @EnableConfigurationProperties 注解。

简要回顾：

定位问题关键在于检查配置类的注解、属性以及文件加载顺序。
灵活运用 DEBUG 日志和断点调试能够加速排查过程。
通过合理的配置和代码调整，确保配置正确加载并生效。

Spring Boot @EnableConfigurationProperties 加载失败原因分析

发表回复 取消回复

发表回复取消回复