SpringBoot @ConfigurationProperties + Validation實現(xiàn)啟動期校驗解決方案

更新時間：2025年09月15日 10:50:47 作者：小明知意

本文給大家介紹SpringBoot @ConfigurationProperties + Validation實現(xiàn)啟動期校驗解決方案,本文通過實例代碼給大家介紹的非常詳細,對大家的學習或工作具有一定的參考借鑒價值,需要的朋友參考下吧

小明成長記：@ConfigurationProperties+Validation實現(xiàn)啟動期校驗

事故回顧：周三下午 2 點，監(jiān)控系統(tǒng)突然告警，某核心服務的錯誤日志激增。小明和小伙伴們立刻被拉進緊急會議。經(jīng)排查，發(fā)現(xiàn)錯誤原因是：一個新上線的短信推送功能，其服務商API URL在線上環(huán)境的配置文件中完全缺失。導致RestTemplate在調(diào)用時，注入的String類型的 URL 為null，最終在運行時拋出了NullPointerException。

甩鍋現(xiàn)場：

部門老大：“這個功能測試環(huán)境不是好好的嗎？為什么線上掛了？誰負責的配置？”
運維同事：“部署流程都是自動化的，配置是根據(jù)開發(fā)提供的清單來管理的。清單里沒寫這個新配置項，我們當然不知道要配。”
小明（內(nèi)心OS）：“完了，這個功能是我做的。我以為大家都會看代碼，知道要配這個……”

老大批示：
“小明，這次的問題根源是配置管理不規(guī)范。你立刻整改代碼，要讓程序在啟動的時候自己告訴我們?nèi)绷耸裁磁渲?，而不是等到用戶用的時候才崩潰！ 以后絕不允許再發(fā)生這種低級錯誤！”

小明的任務：
對代碼進行改造，利用 @ConfigurationProperties 在應用啟動階段對關鍵參數(shù)進行強校驗，避免配置缺失導致運行時出錯。

小明的改造方案：使用@ConfigurationProperties進行啟動期校驗

小明決定采用 Spring Boot 官方推薦的 @ConfigurationProperties + Validation 方案。這樣，如果配置缺失或不符合規(guī)則，應用將根本無法啟動，并在日志中明確打印出缺失的配置項，運維同學直接拿著錯誤信息去補配置即可。

第一步：引入校驗依賴

首先，他檢查了項目的 pom.xml，確保包含了 spring-boot-starter-validation 依賴。這是實現(xiàn)校驗功能的基礎。

<!-- 如果使用的是 Spring Boot 2.3+ 版本，需要顯式引入 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

第二步：創(chuàng)建配置屬性類并添加校驗規(guī)則

小明為短信服務創(chuàng)建了一個專門的配置屬性類，將所有相關的配置項集中管理。

package com.example.demo.config;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import org.springframework.validation.annotation.Validated;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Pattern;
/**
 * 短信服務配置
 * 使用 @Validated 注解開啟校驗
 * 使用 @ConfigurationProperties 綁定前綴為 "sms" 的配置
 */
@Component
@Validated // 關鍵注解1：告訴Spring需要對此Bean進行校驗
@ConfigurationProperties(prefix = "sms") // 關鍵注解2：綁定配置前綴
public class SmsProperties {
    /**
     * 服務商API地址
     * 本次事故的罪魁禍首！
     * @NotBlank 確保該值不能為 null 或空字符串
     */
    @NotBlank(message = "【短信服務】關鍵配置 'sms.url' 未配置，請檢查配置文件！")
    private String url;
    /**
     * 授權密鑰
     */
    @NotBlank(message = "【短信服務】關鍵配置 'sms.secret-id' 未配置")
    private String secretId;
    /**
     * 操作密鑰
     */
    @NotBlank(message = "【短信服務】關鍵配置 'sms.secret-key' 未配置")
    private String secretKey;
    /**
     * 重試次數(shù)
     * @NotNull 確保數(shù)字類型的配置不為空
     * @Min 設置最小值
     */
    @NotNull(message = "【短信服務】配置 'sms.retry-times' 未配置")
    @Min(value = 0, message = "【短信服務】配置 'sms.retry-times' 的值不能小于0")
    private Integer retryTimes;
    /**
     * 是否啟用短信服務（生產(chǎn)環(huán)境才啟用，開發(fā)測試環(huán)境可能不啟用）
     * 這里使用了默認值 false，即使不配置也不會報錯
     */
    private Boolean enabled = false;
    // 標準的 Getter 和 Setter 方法必須存在，否則配置無法注入
    public String getUrl() {
        return url;
    }
    public void setUrl(String url) {
        this.url = url;
    }
    public String getSecretId() {
        return secretId;
    }
    public void setSecretId(String secretId) {
        this.secretId = secretId;
    }
    public String getSecretKey() {
        return secretKey;
    }
    public void setSecretKey(String secretKey) {
        this.secretKey = secretKey;
    }
    public Integer getRetryTimes() {
        return retryTimes;
    }
    public void setRetryTimes(Integer retryTimes) {
        this.retryTimes = retryTimes;
    }
    public Boolean getEnabled() {
        return enabled;
    }
    public void setEnabled(Boolean enabled) {
        this.enabled = enabled;
    }
}

第三步：在業(yè)務代碼中注入使用

改造原來的代碼，不再直接使用 @Value 注入單個屬性，而是注入這個完整的配置 Bean。

package com.example.demo.service;
import com.example.demo.config.SmsProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
@Service
public class SmsService {
    // 直接注入配置Bean
    private final SmsProperties smsProperties;
    @Autowired
    public SmsService(SmsProperties smsProperties) {
        this.smsProperties = smsProperties;
    }
    public void sendSms(String phoneNumber, String content) {
        // 使用配置
        if (Boolean.TRUE.equals(smsProperties.getEnabled())) {
            String targetUrl = smsProperties.getUrl(); // 這里拿到的url肯定是有效的
            String secretId = smsProperties.getSecretId();
            // ... 實際調(diào)用發(fā)送邏輯
            System.out.println("正在調(diào)用短信服務: " + targetUrl);
        } else {
            System.out.println("短信服務未啟用，已忽略發(fā)送。");
        }
    }
}

第四步：準備配置文件

錯誤的配置 (application.yml) - 用于復現(xiàn)事故：

sms:
  # url: https://api.sms-service.com/send # 故意注釋掉，模擬遺忘配置
  secret-id: your_secret_id_here
  # secret-key: your_secret_key_here # 也注釋掉一個
  retry-times: -1 # 配置了一個非法的值

第五步：啟動應用，觀察效果

當小明啟動應用時，應用根本無法啟動，控制臺會立即打印出如下非常清晰的錯誤信息：

***************************
APPLICATION FAILED TO START
***************************
Description:
Binding to target org.springframework.boot.context.properties.bind.BindException: Failed to bind properties under 'sms' to com.example.demo.config.SmsProperties failed:
    Property: sms.url
    Value: null
    Reason: 【短信服務】關鍵配置 'sms.url' 未配置，請檢查配置文件！
    Property: sms.secret-key
    Value: null
    Reason: 【短信服務】關鍵配置 'sms.secret-key' 未配置
    Property: sms.retry-times
    Value: -1
    Reason: 【短信服務】配置 'sms.retry-times' 的值不能小于0
Action:
Update your application's configuration

改造后的成效

啟動即發(fā)現(xiàn)：配置問題在應用啟動之初就被發(fā)現(xiàn)，無法形成部署包，根本不會影響線上用戶。
責任清晰：錯誤信息極其明確，直接指出是哪個配置前綴（sms）下的哪個屬性（url、secret-key）出了問題，以及原因。運維同學無需再問開發(fā)，直接看日志就能完成配置。
溝通成本降低：開發(fā)人員只需提供配置屬性類的定義（可以作為文檔），運維按圖索驥即可。message 屬性中的中文提示更是大大提升了溝通效率。
代碼更健壯：配置集中管理，結(jié)構清晰，避免了散落的 @Value，易于維護和擴展。

小明將改造后的代碼提交上線后，部門老大對此表示了肯定。從此，團隊的配置管理流程變得更加規(guī)范，再也沒有發(fā)生過因配置缺失導致的線上故障。

到此這篇關于SpringBoot @ConfigurationProperties + Validation實現(xiàn)啟動期校驗解決方案的文章就介紹到這了,更多相關SpringBoot @ConfigurationProperties Validation啟動校驗內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: