快捷導航

SpringBoot中ConfigurationProperties使用詳解

更新時間：2026年01月26日 10:41:59 作者：Vintanz

ConfigurationProperties是Spring Boot中管理外部配置的核心工具,通過“配置文件→實體類→代碼使用”的流程,實現(xiàn)了配置的集中管理和動態(tài)綁定,感興趣的可以了解一下

核心作用

通過 @ConfigurationProperties，可以避免在代碼中硬編碼配置（如數(shù)據(jù)庫地址、端口號、第三方API密鑰等），而是從外部配置源動態(tài)讀取，方便環(huán)境切換（開發(fā)、測試、生產(chǎn)）。

基本使用步驟

1. 引入依賴（默認已包含）

@ConfigurationProperties 屬于Spring Boot核心功能，只要項目引入了 spring-boot-starter（或任意 Starter，如 spring-boot-starter-web），就會自動包含相關(guān)依賴，無需額外添加。

2. 創(chuàng)建配置綁定實體類

定義一個JavaBean，使用 @ConfigurationProperties 注解指定配置前綴（prefix），并通過屬性名與配置文件中的key對應(yīng)。

示例：綁定數(shù)據(jù)庫相關(guān)配置

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

// 前綴為"spring.datasource"，對應(yīng)配置文件中"spring.datasource.xxx"的配置
@ConfigurationProperties(prefix = "spring.datasource")
@Component // 注冊為Spring組件，使其被掃描并綁定配置
public class DataSourceProperties {
    // 對應(yīng)配置文件中的"spring.datasource.url"
    private String url;
    // 對應(yīng)"spring.datasource.username"
    private String username;
    // 對應(yīng)"spring.datasource.password"
    private String password;
    // 對應(yīng)"spring.datasource.driver-class-name"（支持寬松綁定，見下文）
    private String driverClassName;

    // 必須提供getter和setter（Spring通過setter注入配置值）
    public String getUrl() { return url; }
    public void setUrl(String url) { this.url = url; }

    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }

    // 省略其他getter/setter
}

3. 外部配置文件（application.yml 或 application.properties）

在配置文件中定義對應(yīng)前綴的配置項，屬性名與實體類的屬性名通過“寬松綁定”規(guī)則匹配。

application.yml 示例：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver # 對應(yīng)實體類的driverClassName

application.properties 示例：

spring.datasource.url=jdbc:mysql://localhost:3306/test
spring.datasource.username=root
spring.datasource.password=123456
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

4. 啟用配置綁定（兩種方式）

方式1：在實體類上添加 @Component 注解（如步驟2示例），使其被Spring掃描并注冊為Bean，自動觸發(fā)配置綁定。

方式2：在配置類上使用 @EnableConfigurationProperties 顯式指定需要綁定的類（適用于實體類未加 @Component 的場景）：

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

@Configuration
// 顯式啟用DataSourceProperties的配置綁定
@EnableConfigurationProperties(DataSourceProperties.class)
public class MyConfig {
}

5. 在代碼中使用綁定的配置

通過依賴注入（@Autowired）將綁定好的實體類注入到Service/Controller中，直接使用配置值。

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 DataSourceProperties dataSourceProperties;

    @GetMapping("/db-info")
    public String getDbInfo() {
        return "數(shù)據(jù)庫URL：" + dataSourceProperties.getUrl() + 
               "，用戶名：" + dataSourceProperties.getUsername();
    }
}

關(guān)鍵特性

1. 寬松綁定（Relaxed Binding）

配置文件中的key與實體類屬性名無需嚴格一致，支持多種命名風格轉(zhuǎn)換：

配置文件中：driver-class-name（短橫線分隔，kebab-case）
實體類中：driverClassName（駝峰式，camelCase）
其他支持：下劃線（driver_class_name）、全大寫（DRIVER_CLASS_NAME）等。

2. 類型轉(zhuǎn)換

Spring會自動將配置文件中的字符串值轉(zhuǎn)換為實體類屬性的類型（如 int、boolean、List、Map 等）。

示例：綁定集合類型

@ConfigurationProperties(prefix = "app")
@Component
public class AppProperties {
    private List<String> allowedOrigins; // 對應(yīng)app.allowed-origins
    private Map<String, String> configMap; // 對應(yīng)app.config-map

    // getter/setter
}

配置文件（application.yml）：

app:
  allowed-origins:
    - http://localhost:8080
    - http://example.com
  config-map:
    key1: value1
    key2: value2

3. 配置校驗

結(jié)合 @Validated 和JSR-303校驗注解（如 @NotNull、@Min、@Pattern），可對配置值進行合法性校驗，避免無效配置。

示例：

import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.NotEmpty;
import javax.validation.constraints.NotNull;

@ConfigurationProperties(prefix = "app")
@Component
@Validated // 啟用校驗
public class AppProperties {

    @NotEmpty(message = "應(yīng)用名稱不能為空") // 校驗非空
    private String name;

    @NotNull(message = "端口號不能為空") // 校驗非null
    private Integer port;

    // getter/setter
}

若配置文件中未設(shè)置 app.name 或 app.port，啟動時會拋出校驗異常，快速發(fā)現(xiàn)配置問題。

4. 配置元數(shù)據(jù)（提高開發(fā)體驗）

通過添加 spring-boot-configuration-processor 依賴，可生成配置元數(shù)據(jù)，在IDE中編寫配置文件時獲得自動提示（如屬性名、類型、描述）。

添加依賴（pom.xml）：

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

添加后，IDE（如IDEA）會在編寫 application.yml 時提示 spring.datasource.url 等屬性，減少拼寫錯誤。

與 @Value 的區(qū)別

特性	@ConfigurationProperties	@Value
用途	批量綁定多個配置屬性到實體類	單個屬性注入（如 @Value("${app.name}")）
類型轉(zhuǎn)換	自動支持復雜類型（List、Map等）	需手動處理復雜類型轉(zhuǎn)換
校驗支持	支持（結(jié)合 @Validated）	不支持
寬松綁定	支持	不支持（需嚴格匹配key）
元數(shù)據(jù)提示	支持（需processor依賴）	不支持

建議：配置項較多時優(yōu)先使用 @ConfigurationProperties；單個簡單配置可使用 @Value。

總結(jié)

@ConfigurationProperties 是Spring Boot中管理外部配置的核心工具，通過“配置文件→實體類→代碼使用”的流程，實現(xiàn)了配置的集中管理和動態(tài)綁定，尤其適合多環(huán)境配置、復雜配置場景，大幅提升了配置的可維護性。

到此這篇關(guān)于SpringBoot中ConfigurationProperties使用詳解的文章就介紹到這了,更多相關(guān)ConfigurationProperties使用內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: