@ConfigurationProperties 註解使用姿式，這一篇就夠了

時間 2019-12-20

標籤 configurationproperties 註解使用一篇夠了简体版

原文原文鏈接

在編寫項目代碼時，咱們要求更靈活的配置，更好的模塊化整合。在 Spring Boot 項目中，爲知足以上要求，咱們將大量的參數配置在 application.properties 或 application.yml 文件中，經過 @ConfigurationProperties 註解，咱們能夠方便的獲取這些參數值html

使用 @ConfigurationProperties 配置模塊

假設咱們正在搭建一個發送郵件的模塊。在本地測試，咱們不想該模塊真的發送郵件，因此咱們須要一個參數來「開關」 disable 這個功能。另外，咱們但願爲這些郵件配置一個默認的主題，這樣，當咱們查看郵件收件箱，經過郵件主題能夠快速判斷出這是測試郵件java

在 application.properties 文件中建立這些參數:git

咱們可使用 @Value 註解或着使用 Spring Environment bean 訪問這些屬性，是這種注入配置方式有時顯得很笨重。咱們將使用更安全的方式(@ConfigurationProperties )來獲取這些屬性github

@ConfigurationProperties 的基本用法很是簡單:咱們爲每一個要捕獲的外部屬性提供一個帶有字段的類。請注意如下幾點:面試

前綴定義了哪些外部屬性將綁定到類的字段上
根據 Spring Boot 寬鬆的綁定規則，類的屬性名稱必須與外部屬性的名稱匹配
咱們能夠簡單地用一個值初始化一個字段來定義一個默認值
類自己能夠是包私有的
類的字段必須有公共 setter 方法

Spring 寬鬆綁定規則 (relaxed binding)

Spring使用一些寬鬆的綁定屬性規則。所以，如下變體都將綁定到 hostName 屬性上:spring

若是咱們將 MailModuleProperties 類型的 bean 注入到另外一個 bean 中，這個 bean 如今能夠以類型安全的方式訪問那些外部配置參數的值。shell

可是，咱們仍然須要讓 Spring 知道咱們的 @ConfigurationProperties 類存在，以便將其加載到應用程序上下文中( 面試還不知道 BeanFactory 和 ApplicationContext 的區別？)編程

激活 @ConfigurationProperties

對於 Spring Boot，建立一個 MailModuleProperties 類型的 bean，咱們能夠經過下面幾種方式將其添加到應用上下文中數組

首先，咱們能夠經過添加 @Component 註解讓 Component Scan 掃描到
安全

很顯然，只有當類所在的包被 Spring @ComponentScan 註解掃描到纔會生效，默認狀況下，該註解會掃描在主應用類下的全部包結構

咱們也能夠經過 Spring 的 Java Configuration 特性實現一樣的效果:

只要 MailModuleConfiguration 類被 Spring Boot 應用掃描到，咱們就能夠在應用上下文中訪問 MailModuleProperties bean

咱們還可使用 @EnableConfigurationProperties 註解讓咱們的類被 Spring Boot 所知道，在該註解中實際上是用了@Import(EnableConfigurationPropertiesImportSelector.class) 實現，你們能夠看一下

激活一個 @ConfigurationProperties 類的最佳方式是什麼？

全部上述方法都一樣有效。然而，我建議模塊化你的應用程序，並讓每一個模塊提供本身的@ConfigurationProperties 類，只提供它須要的屬性，就像咱們在上面的代碼中對郵件模塊所作的那樣。這使得在不影響其餘模塊的狀況下重構一個模塊中的屬性變得容易。

所以，我不建議在應用程序類自己上使用 @EnableConfigurationProperties，如許多其餘教程中所示，是在特定於模塊的 @Configuration 類上使用@EnableConfigurationProperties，該類也能夠利用包私有的可見性對應用程序的其他部分隱藏屬性。

沒法轉換的屬性

若是咱們在 application.properties 屬性上定義的屬性不能被正確的解析會發生什麼？假如咱們爲本來應該爲布爾值的屬性提供的值爲 'foo':

默認狀況下，Spring Boot 將會啓動失敗，並拋出異常:

Failed to bind properties under 'myapp.mail.enabled' to java.lang.Boolean:

    Property: myapp.mail.enabled
    Value: foo
    Origin: class path resource [application.properties]:1:20
    Reason: failed to convert java.lang.String to java.lang.Boolean

當咱們爲屬性配置錯誤的值時，而又不但願 Spring Boot 應用啓動失敗，咱們能夠設置 ignoreInvalidFields 屬性爲 true (默認爲 false)

這樣，Spring Boot 將會設置 enabled 字段爲咱們在 Java 代碼裏設定好的默認值。若是咱們沒有設置默認值，enabled 將爲 null，由於這裏定義的是 boolean 的包裝類 Boolean

未知的屬性

和上面的狀況有些相反，若是咱們在 application.properties 文件提供了 MailModuleProperties 類不知道的屬性會發生什麼？

默認狀況下，Spring Boot 會忽略那些不能綁定到 @ConfigurationProperties 類字段的屬性

然而，當配置文件中有一個屬性實際上沒有綁定到 @ConfigurationProperties 類時，咱們可能但願啓動失敗。也許咱們之前使用過這個配置屬性，可是它已經被刪除了，這種狀況咱們但願被觸發告知手動從 application.properties 刪除這個屬性

爲了實現上述狀況，咱們僅須要將 ignoreUnknownFields 屬性設置爲 false (默認是 true)

如今，應用啓動時，控制檯會反饋咱們異常信息

Binding to target [Bindable@cf65451 type = com.example.configurationproperties.properties.MailModuleProperties, value = 'provided', annotations = array<Annotation>[@org.springframework.boot.context.properties.ConfigurationProperties(value=myapp.mail, prefix=myapp.mail, ignoreInvalidFields=false, ignoreUnknownFields=false)]] failed:

    Property: myapp.mail.unknown-property
    Value: foo
    Origin: class path resource [application.properties]:3:29
    Reason: The elements [myapp.mail.unknown-property] were left unbound.

棄用警告⚠️(Deprecation Warning)
ignoreUnknownFields 在將來 Spring Boot 的版本中會被標記爲 deprecated，由於咱們可能有兩個帶有 @ConfigurationProperties 的類，同時綁定到了同一個命名空間 (namespace) 上，其中一個類可能知道某個屬性，另外一個類殊不知道某個屬性，這樣就會致使啓動失敗

啓動時校驗 @ConfigurationProperties

若是咱們但願配置參數在傳入到應用中時有效的，咱們能夠經過在字段上添加 bean validation 註解，同時在類上添加 @Validated 註解

若是咱們忘記在 application.properties 文件設置 enabled 屬性，而且設置 defaultSubject 爲空

應用啓動時，咱們將會獲得 BindValidationException

Binding to target org.springframework.boot.context.properties.bind.BindException: Failed to bind properties under 'myapp.mail' to com.example.configurationproperties.properties.MailModuleProperties failed:

    Property: myapp.mail.enabled
    Value: null
    Reason: must not be null

    Property: myapp.mail.defaultSubject
    Value: null
    Reason: must not be empty

固然這些默認的驗證註解不能知足你的驗證要求，咱們也能夠自定義註解

若是你的驗證邏輯很特殊，咱們能夠實現一個方法，並用 @PostConstruct 標記，若是驗證失敗，方法拋出異常便可, 關於 @PostConstruct，能夠查看 Spring Bean 的生命週期，我從哪裏來？