【SpringBoot基礎系列】ConfigurationProperties 配置綁定中那些你不知道的事情

【基礎系列】ConfigurationProperties 配置綁定中那些你不知道的事情

在 SpringBoot 項目中，獲取配置屬性可以說是一個非常簡單的事情，將配置寫在aplication.yml文件之後，我們就可以直接通過@Value註解來綁定並獲取；此外我們也可以將一個結構化的配置，藉助@ConfigurationPorperties綁定到一個 POJO，然後供項目使用，那麼在使用它的時候，不知是否有想過

@ConfigurationPorperties修飾的類如何生效
配置參數與定義的 POJO 類型不匹配時會怎樣
配置參數的必要性校驗可以怎麼支持
自定義的配置參數，idea 中如何自動補全
已廢棄的參數定義，怎樣友好的提示使用方
List/Map 格式的參數，怎麼使用
自定義參數解析規則如何支持

如果上面這些都已經瞭然於心，那麼本文的幫助將不會特別大；如果對此有所疑問，接下來將逐一進行解惑

I. 項目環境

本項目藉助SpringBoot 2.2.1.RELEASE + maven 3.5.3 + IDEA進行開發

下面是核心的pom.xml（源碼可以再文末獲取）

<!-- 這個依賴是幹嘛的，後文會介紹 -->
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
    </dependency>
</dependencies>

II. ConfigurationProperties 詳解

1. 配置綁定

假定我們現在自定義一個功能模塊，裏面有一些我們自定義的參數，支持通過 yaml 配置文件的方式注入

首先我們可以先定義一個配置類 BindConfig

@Data
@ConfigurationProperties(prefix = "hhui.bind")
public class BindConfig {
    private String name;

    private Integer age;

    private List<String> list;

    private Map<String, String> map;
}

請注意上面的註解中，prefix = hhui.bind，簡單來講就是會讀取配置文件中，前綴爲 hhui.bind 的屬性，然後依次賦值到這個類中

BindConfig.name = hhui.bind.name
BindConfig.age = hhui.bind.age
...

對應的配置文件如下

hhui:
  bind:
    name: YiHui
    age: 18
    list:
      - java
      - c
      - python
    map:
      wechat: 小灰灰blog
      blogs: http://blog.hhui.top
      git: http://github.com/liuyueyi

注意事項

配置類必須有公共的 Setter 方法，上文中主要是藉助 lombok 的@Data省略了 Setter 方法的顯示聲明而已
類的屬性名與配置文件中的配置名要求匹配
- 大小寫不敏感
- 支持下劃線轉駝峯
配置類不要求必須是 public

關於上面最後一點，也就表明我們可以在自動 AutoConfiguration 類中，聲明一個內部類來綁定配置信息，如下

@Configuration
@EnableConfigurationProperties({AutoConfiguration.BindConfig.class})
public class AutoConfiguration {

    @Data
    @ConfigurationProperties(prefix = "hhui.bind")
    static class BindConfig {

        private String name;

        private Integer age;

        private List<String> list;

        private Map<String, String> map;
    }
}

2. 註冊生效

我們通過@ConfigurationProperties修飾配置類之後，是否直接會生效呢？通常來講，讓它生效有下面三種方式

a. `@Component`等註解修飾方式

直接在配置類上添加@Component, @Configuration等註解，讓 Spring 容器掃描並加載它

@Data
@Component
@ConfigurationProperties(prefix = "hhui.bind")
public class BindConfig {
}

使用這種方式時，需要注意配置類在自動掃描的包路徑下，否則可能不會被掃描（主要是作爲第三方 jar 包提供服務時，可能出現掃描不到的問題）

b. `@Bean`註冊

把它當成一個普通的 bean，藉助 bean 註冊的方式來實現，也是一個可選的方案，一般的實現方式如下

@Configuration
public class AutoConfiguration {
    @Bean
    public BindConfig bindConfig() {
        return new BindConfig();
    }
}

c. `@EnableConfigurationProperties`方式

在配置類上，添加這個註解之後，可以實現配置註冊，一般常見的使用姿勢如

@EnableConfigurationProperties({BindConfig.class})
@Configuration
public class AutoConfiguration {
}

d. 小結

上面三種註冊方式，前面兩種的思路是將配置類作爲 bean，第三種實現思路和主動註冊 bean 一致（所以想實現主動註冊 bean，可以考慮它的實現邏輯）

3. 參數類型不匹配

如果我們在配置中，一個本來希望接收 int 類型的參數，結果實際上填了一個非整形，會怎樣？

比如前面的配置類，我們實際的配置文件將age填 18y，來看一下最終會發生什麼事情

hhui:
  bind:
    Name: YiHui
    AGE: 18y
    list:
      - java
      - c
      - python
    map:
      wechat: 小灰灰blog
      blogs: http://blog.hhui.top
      git: http://github.com/liuyueyi

簡單演示，直接在啓動類中測試一下會如何

@SpringBootApplication
public class Application {

    public Application(BindConfig config) {
        System.out.println(config);
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class);
    }

}

參數異常之後，直接啓動失敗，如果對參數的要求沒有那麼嚴格，即允許失敗，我們可以通過設置ignoreInvalidFields = true

@Data
@ConfigurationProperties(prefix = "hhui.bind", ignoreInvalidFields = true)
public class BindConfig {
}

再次執行之後，會發現正常啓動，輸出如下

BindConfig(name=YiHui, age=null, list=[java, c, python], map={wechat=小灰灰blog, blogs=http://blog.hhui.top, git=http://github.com/liuyueyi})

注意查看上面的 age，因爲傳入的參數非法，所以是 null

說明

結合默認值 + ignoreInvalidFields 方式來支持配置的最大可用性：

直接在配置類中，設置屬性的默認值，表示當這個配置不存在或者設置非法時，使用默認的配置

@Data
@ConfigurationProperties(prefix = "hhui.bind", ignoreInvalidFields = true)
public class BindConfig {

    private String name;

    private Integer age = 18;

    private List<String> list;

    private Map<String, String> map;
}

再次執行輸出如

BindConfig(name=YiHui, age=18, list=[java, c, python], map={wechat=小灰灰blog, blogs=http://blog.hhui.top, git=http://github.com/liuyueyi}, mainPwd=Pwd(user=一灰灰blog, pwd=yihuihui, code=9))

4. 配置解析規則

常見的配置除了基本類型之外，能嵌套自定義對象麼，非基本類型又可以如何解析呢？

a. POJO,List,Map 參數類型

我們新定義一個 Pwd 類

@Data
public class Pwd {
    private String user;

    private String pwd;

    private Integer code;
}

然後擴展一下BindConfig

@Data
@ConfigurationProperties(prefix = "hhui.bind", ignoreInvalidFields = true)
public class BindConfig {

    private String name;

    private Integer age = 18;

    private List<String> list;

    private Map<String, String> map;

    private Pwd mainPwd;
}

這個時候 mainPwd 對應的 yaml 配置文件可以如下設置

hhui:
  bind:
    Name: YiHui
    AGE: 1h
    list:
      - java
      - c
      - python
    map:
      wechat: 小灰灰blog
      blogs: http://blog.hhui.top
      git: http://github.com/liuyueyi
    # 下面這個對應的是 BindConfg.mainPwd; 可以寫成 main_pwd也可以寫成mainPwd
    main_pwd:
      user: 一灰灰blog
      pwd: yihuihui
      code: 9

從上面的介紹也可以看出，對於自定義的 POJO 類是支持的，使用姿勢也沒什麼區別

此外，對於 List 和 Map 的使用也給出了實例

b.自定義配置解析

上面我們自定義的Pwd類，主要藉助setter方法，將匹配的屬性塞入進去；如果我的配置就是一個 json 串，可以注入到一個 POJO 類麼

hhui:
  bind:
    Jwt: '{"token": "11111111123", "timestamp": 1610880489123}'

對應的 Jwt 類如下

@Data
public class Jwt {
    private String token;

    private Long timestamp;
}

這個時候如想實現上面的配置解析，可以通過實現org.springframework.core.convert.converter.Converter接口來支持，並通過@ConfigurationPropertiesBinding註解來表明這是個配置屬性轉換類，不加這個註解會不生效哦

@Component
@ConfigurationPropertiesBinding
public class JwtConverter implements Converter<String, Jwt> {
    @Override
    public Jwt convert(String source) {
        return JSONObject.parseObject(source, Jwt.class);
    }
}

說明

使用自定義的配置解析規則時，注意兩點

實現接口Converter
使用@ConfigurationPropertiesBinding修飾註解

Spring 提供了一些默認的配置解析規則，如

文件大小DataSize
- 對應的 value 可以是 1B, 1KB, 1MB, 1GB...
持續時間Duration
- 對應的 value 可已是 1ns，1us，1ms，1s，1m，1h，1d

5. 配置不存在場景

一個配置類，對應的類中沒有這個屬性會怎樣？

如針對前面的BindConfig，沒有notExist這個屬性，但是配置文件中，卻加上了這個

hhui:
  bind:
    notExist: true

實測之後，發現沒有任何影響，通過查看@ConfigurationProperties註解的成員，發現可以設置ignoreUnknownFields=false，從字面上表示出現了未能識別的成員，不會略錯誤，但是在實際測試中，並沒有生效

6. 參數校驗

參數校驗可以說比較常用的 case 了，比如前面的配置age，基本上不會允許這個參數能是負數，如需要對參數進行校驗，我們可以藉助@Validated來實現校驗

添加 pom 依賴

<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
</dependency>

然後再配置類上添加@Validated，然後就可以在需要校驗的字段上添加對應的限制

@Data
@Validated
@ConfigurationProperties(prefix = "hhui.bind", ignoreInvalidFields = true, ignoreUnknownFields = false)
public class BindConfig {
    @Min(13)
    @Max(66)
    private Integer age = 18;
}

如果我們將 age 參數設置不滿足上面的條件

hhui:
  bind:
    age: 10

再次測試會發現報如下錯誤

7. IDEA 自動補全提示

平時在 Spring 開發過程中，在 yaml 文件中添加配置時，配合 idea 有非常友好的提示，可以非常友好的補全參數配置

那麼我們自定義的參數想實現這個效果應該怎麼做呢？

添加文章最開頭的依賴

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

添加上面的依賴之後，打包mvn clean package，然後會發現在 META-INF 下面有個spring-configuration-metadata.json

{
  "groups": [
    {
      "name": "hhui.bind",
      "type": "com.git.hui.boot.bind.config.BindConfig",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig"
    }
  ],
  "properties": [
    {
      "name": "hhui.bind.age",
      "type": "java.lang.Integer",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig",
      "defaultValue": 18
    },
    {
      "name": "hhui.bind.jwt",
      "type": "com.git.hui.boot.bind.config.Jwt",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig"
    },
    {
      "name": "hhui.bind.list",
      "type": "java.util.List<java.lang.String>",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig"
    },
    {
      "name": "hhui.bind.main-pwd",
      "type": "com.git.hui.boot.bind.config.Pwd",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig"
   },
    {
      "name": "hhui.bind.map",
      "type": "java.util.Map<java.lang.String,java.lang.String>",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig"
    },
    {
      "name": "hhui.bind.name",
      "type": "java.lang.String",
      "sourceType": "com.git.hui.boot.bind.config.BindConfig"
    }
  ],
  "hints": []
}

然後自動補全就有了

說明

idea 推薦添加插件Spring Assistant，支持非常友好的配置注入

8.小結

本文介紹了@ConfigurationProperties修飾 POJO 類，實現配置的綁定，可以通過將這個類聲明爲一個普通 bean 的方式進行註冊，也可以藉助@EnableConfigurationProperties來註冊

在配置參數時，需要注意如果參數類型不一致，會導致項目啓動失敗；可以通過設置ConfigurationProperties#ignoreInvalidFields = true，來避免這種場景

通過實現接口Converter + @ConfigurationPropertiesBinding來自定義參數解析轉換規則，可以實現各路姿勢的參數解析

配置的自動提示支持也比較簡單，添加org.springframework.boot:spring-boot-configuration-processor依賴，打包之後在 META-INF 中會多一個 json 文件spring-configuration-metadata.json

II. 其他

0. 項目

項目源碼

系列博文

1. 一灰灰 Blog

盡信書則不如，以上內容，純屬一家之言，因個人能力有限，難免有疏漏和錯誤之處，如發現 bug 或者有更好的建議，歡迎批評指正，不吝感激

下面一灰灰的個人博客，記錄所有學習和工作中的博文，歡迎大家前去逛逛

一灰灰 Blog 個人博客 https://blog.hhui.top
一灰灰 Blog-Spring 專題博客 http://spring.hhui.top
微信公衆號: 一灰灰blog

【SpringBoot基礎系列】ConfigurationProperties 配置綁定中那些你不知道的事情

I. 項目環境

II. ConfigurationProperties 詳解

1. 配置綁定

2. 註冊生效

a. `@Component`等註解修飾方式

b. `@Bean`註冊

c. `@EnableConfigurationProperties`方式

d. 小結

3. 參數類型不匹配

4. 配置解析規則

a. POJO,List,Map 參數類型

b.自定義配置解析

5. 配置不存在場景

6. 參數校驗

7. IDEA 自動補全提示

8.小結

II. 其他

0. 項目

1. 一灰灰 Blog

【SQL進階】CASE語句的使用

npm error Cannot read properties of null (reading 'isDescendantOf')

網頁爬蟲開發：使用Scala和PhantomJS訪問知乎

一文講透 OceanBase 單機版：架構介紹、部署流程、性能測試、MySQL對比、資源配置等等

車載以太網的未來：OPEN Alliance下17個技術委員會的最新進展與行業影響（上）

com.fasterxml.jackson.databind.JsonMappingException: Invalid UTF-8 start byte 0xb1

向量數據庫引領 AI 創新——Zilliz 亮相 2024 亞馬遜雲科技中國峯會

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結

【SpringBoot基礎系列】ConfigurationProperties 配置綁定中那些你不知道的事情

I. 項目環境

II. ConfigurationProperties 詳解

1. 配置綁定

2. 註冊生效

a. @Component等註解修飾方式

b. @Bean註冊

c. @EnableConfigurationProperties方式

d. 小結

3. 參數類型不匹配

4. 配置解析規則

a. POJO,List,Map 參數類型

b.自定義配置解析

5. 配置不存在場景

6. 參數校驗

7. IDEA 自動補全提示

8.小結

II. 其他

0. 項目

1. 一灰灰 Blog

a. `@Component`等註解修飾方式

b. `@Bean`註冊

c. `@EnableConfigurationProperties`方式