@ConfigurationProperties 注解详解

概述

@ConfigurationProperties 是 Spring Framework 提供的一个注解，用于将外部配置（如 YAML 或 properties 文件）绑定到 Java 对象。

它主要用于集中管理应用程序的配置，简化了配置项的读取和使用。

作用

  1. 简化配置管理：将多个相关的配置项聚合到一个类中，便于管理和使用。
  2. 类型安全：通过强类型的 Java 对象来获取配置，避免了使用字符串常量，减少了出错的可能性。
  3. 便于测试：将配置与业务逻辑分离，使得测试变得更加简单。

使用方法

添加依赖

确保在 pom.xml 中添加 Spring Boot Starter：

1
2
3
4
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>

创建配置类

创建一个类并使用 @ConfigurationProperties 注解。示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    private String name;
    private int timeout;
    private boolean enabled;

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

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

    public int getTimeout() {
        return timeout;
    }

    public void setTimeout(int timeout) {
        this.timeout = timeout;
    }

    public boolean isEnabled() {
        return enabled;
    }

    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }
}

配置文件

在 application.yml 或 application.properties 中定义配置项：

application.yml:

1
2
3
4
app:
  name: MyApplication
  timeout: 30
  enabled: true

application.properties:

1
2
3
app.name=MyApplication
app.timeout=30
app.enabled=true

使用配置类

在需要的地方注入配置类并使用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class MyService {

    private final AppProperties appProperties;

    @Autowired
    public MyService(AppProperties appProperties) {
        this.appProperties = appProperties;
    }

    public void printConfig() {
        System.out.println("App Name: " + appProperties.getName());
        System.out.println("Timeout: " + appProperties.getTimeout());
        System.out.println("Enabled: " + appProperties.isEnabled());
    }
}

配置注解的属性

  • **prefix**：指定配置前缀，Spring 会自动将以该前缀开头的配置项映射到该类的属性。
  • **ignoreUnknownFields**（默认值为 true）：如果配置文件中包含未定义的字段，是否忽略。设为 false 时，将抛出异常。
  • **validation**：可以结合 JSR-303（如 Hibernate Validator）进行属性验证。

校验

可以使用 Java Bean Validation（如 Hibernate Validator）来校验配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import javax.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    
    @NotNull
    private String name;

    private int timeout;

    private boolean enabled;

    // Getters and Setters...
}

要启用校验功能，需要在主类上添加 @EnableConfigurationProperties 注解：

1
2
3
4
5
6
7
8
9
10
11
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;

@SpringBootApplication
@EnableConfigurationProperties(AppProperties.class)
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

总结

@ConfigurationProperties 注解是 Spring Boot 中一个非常强大且方便的特性，它使得应用程序的配置管理变得更加简单和灵活。

通过将外部配置与 Java 对象映射，提供了更好的可维护性和类型安全性，减少了硬编码配置的需要。结合校验功能，可以有效地管理和验证应用程序的配置。