当前位置：首页 > news >正文

Spring boot中的@ConfigurationProperties注解

news 2025/11/1 2:50:10

Spring boot中的@ConfigurationProperties注解

@ConfigurationProperties 是 Spring Boot 提供的一个强大注解，用于将配置文件（如 application.properties 或 application.yml）中的配置绑定到一个 Java 对象中。它不仅简化了配置管理，还提供了类型安全、松散绑定、校验等功能。以下是对 @ConfigurationProperties 的详细解析。

1.核心概念

1.1作用

@ConfigurationProperties 用于将配置文件中的属性绑定到一个 POJO（Plain Old Java Object）类的字段上。它允许开发者以面向对象的方式管理配置，而不是通过松散的键值对。

1.2使用场景

支持松散绑定，允许配置文件中的键名与 Java 字段名不完全一致。
支持嵌套配置，可以将复杂的配置结构化管理。
支持默认值和校验。
集中管理应用程序的配置。
提供类型安全的配置访问。

2.基本使用

2.1定义配置类

假设你有一个配置文件 application.properties，内容如下：

这些内容都是以app开头的，

app.firstName=Donald
app.secondName=Trump
app.yourHometown=NewYork

你可以通过定义一个带有 @ConfigurationProperties 注解的类来绑定这些配置：

设置@ConfigurationProperties的prefix 属性为 “app”，

@Component
@Data
@ConfigurationProperties(prefix = "app")
public class SimpleConfig {private String firstName;private String secondName;private String yourHometown;
}

2.2使用配置

在应用程序中，你可以通过注入这个配置类来访问配置值：

@Service
public class AppService {@Autowiredprivate SimpleConfig simpleConfig;public void printAppInfo() {//可以分别打印属性的值}
}

3.松散绑定

@ConfigurationProperties 支持松散绑定，这意味着配置文件中的键名可以使用不同的格式（如-、_等），Spring Boot 会自动匹配到对应的 Java 字段。

以下配置都能绑定到 SimpleConfig类的字段上：

app.first-name=Gulimall
app.second-name=An e-commerce platform
app.your-Hometown=1.0.0

4.嵌套配置

@ConfigurationProperties 支持嵌套配置，可以将复杂的配置结构化管理。

配置文件

app.firstName=Donald
app.secondName=Trump
app.yourHometown=NewYorkapp.database.url=jdbc:mysql://localhost:3306/America
app.database.username=root
app.database.password=123456

嵌套配置类

@Component
@Data
@ConfigurationProperties(prefix = "app")
public class SimpleConfig {private String firstName;private String secondName;private String yourHometown;@Datapublic static class Database {private String url;private String username;private String password;}}

使用嵌套配置

@Service
public class AppService {@Autowiredprivate SimpleConfig simpleConfig;public void printAppInfo() {System.out.println("Database URL: " + appConfig.getDatabase().getUrl());}}

5.默认值和校验

5.1默认值

可以通过字段赋值提供默认值：

@Component
@Data
@ConfigurationProperties(prefix = "app")
public class SimpleConfig {private String firstName="Donald";private String secondName="Trump";private String yourHometown;
}

5.2校验

@ConfigurationProperties 支持使用JSR-303校验注解（如 @NotNull、@Size 等）对配置进行校验。

具体参考JSR-303校验注解的使用方法

6.集合绑定

配置文件

app.languages[0]=Java
app.languages[1]=Python
app.languages[2]=JavaScript

配置类

@Component
@ConfigurationProperties(prefix = "app")
public class AppConfig {private List<String> languages = new ArrayList<>();
}

7.动态配置更新

@ConfigurationProperties 支持与 Spring 的 @RefreshScope 注解结合，实现配置的动态更新。这对于使用 Spring Cloud Config 的微服务架构非常有用。

@RefreshScope
@Component
@ConfigurationProperties(prefix = "app")
public class SimpleConfig {private String name;
}

当配置中心的配置发生变化时，@RefreshScope 会重新加载配置类中的值。

补充：可以配置以下依赖，该依赖会扫描项目中使用了 @ConfigurationProperties 注解的类，提供配置文件的自动提示和补全功能。

<dependency><groupId>org.springframework.boot</group><artifactId>spring-boot-configuration-processor</artifactId><optional>true</optional>
</dependency>