# 關於SpringBoot的外部化配置使用記錄 > 宣告: 若有任何紕漏、錯誤請不吝指出! 記錄下使用`SpringBoot`配置時遇到的一些麻煩，雖然這種麻煩是因為知識匱乏導致的。 記錄下避免一段時間後自己又給忘記了，以防萬一。 如果放到部落格裡能幫助到遇到同樣問題的同志，自是極好！ `SpringBoot`的外部化配置，主要就是指平時用到的一些配置檔案，這些配置由於不是硬編碼，放在了配置檔案中，所以相對來說是一個外部化的配置`Externalized Configuration` `SpringBoot`官方外部化配置的線上文件[Externalized Configuration](https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-external-config) ## 初級用法 `SpringBoot`對配置提供了極大的便利，僅僅需要編寫一個`Yaml`檔案或者`Properties`檔案，按照其規定的格式，書寫好我們的配置資訊，然後編寫一個相應的`Java`類，使用註解`@ConfigurationProperties`和`@Configuration`配合使用，或者`@Configuration`和`@Value`配合使用，即可將配置的值，對映到我們配置類或者`JavaBean`中。 有如下`Java`配置類 ```java @Configuration @ConfigurationProperties(prefix="spring.server") public class AppConfig{ private String name; private String port; public void setName(String name){ this.name = name; } public void setPort(String port){ this.port = port; } } ``` 如下配置檔案， `Yaml`格式配置檔案 ```yaml # application.yml spring: server: name: spring-app port: 9527 ``` `Properties`格式配置檔案 ```properties # application.properties spring.server.name=spring-app spring.server.port=9237 ``` > 使用`@ConfigurationProperties`，必須要有`Setter`方法，繫結時是通過`Setter`方法繫結的 > > 參見`org.springframework.boot.context.properties.ConfigurationPropertiesBindingPostProcessor#postProcessBeforeInitialization`，這是一個`BeanPostProcessor` 這樣在`SpringBoot`中，我們就可以將`AppConfig`這個`Bean`注入到別的`Bean`中使用我們的配置了。 以上這些在開發中基本上也就滿足需要了，大部分我們的配置都很簡單，通常都是數值型的和字串。 但是，凡事不能絕對。 ## 高階用法 以下配置參考[這位](https://blog.csdn.net/justry_deng/article/details/90758250) ### Array/List 假如有如下需求，應用僅對幾個有限的`IP`開放訪問，然後我們想把這幾個獲得許可的`IP`地址寫在配置檔案中。 這個時候如果配置解析僅僅支援字串和數值型的話，就需要我們自己獲取到配置值以後，再去進行一些後續的處理，比如轉換成陣列或者列表。 好在，優秀的框架，總能滿足大部分的需求，`SpringBoot`是直接配置直接到陣列或者列表的對映到 使用方式 #### `Java`配置類 ```java @Configuration @ConfigurationProperties(prefix="allows") public class AllowedAccessConfig{ private String[] ipList; // 欄位型別可以是 List public void setPort(String[] port){ this.ipList = ipList; } } ``` #### 配置檔案 ```yaml # application.yml allows: ipList: - 192.168.1.1 - 192.168.1.2 - 192.168.1.3 - 192.168.1.4 # or allows: ipList: 192.168.1.1, 192.168.1.2, 192.168.1.3, 192.168.1.4 ``` ```properties # application.properties allows.ipList[0]=192.168.1.1 allows.ipList[1]=192.168.1.2 allows.ipList[2]=192.168.1.3 allows.ipList[3]=192.168.1.4 # or allows.ipList= 192.168.1.1, 192.168.1.2, 192.168.1.3, 192.168.1.4 ``` ### Map 如果陣列或者列表不滿足需求，需要`key-vlaue`型的，沒問題，`SpringBoot`也是支援的。 假設一個對接方不同的業務，使用了不同的`AES`金鑰，那麼在配置的時候，就要根據業務型別作為`key`，對應的金鑰作為`value`。 #### `Java`配置類 ```java @Configuration @ConfigurationProperties(prefix="aes.keys") public class AesKeyConfig{ private Map keys; public void setKeys(Map keys){ this.keys = keys; } } ``` #### 配置檔案 ```yaml # application.yml aes: keys: order: 28jsaS2asf2fSA2 pay: @ra@3safdsR5&sDa # or aes: keys[order]: 28jsaS2asf2fSA2 keys[pay]: @ra@3safdsR5&sDa ``` ```properties # application.properties aes.keys.order=28jsaS2asf2fSA2 aes.keys.pay=@ra@3safdsR5&sDa # or aes.keys[order]=28jsaS2asf2fSA2 aes.keys[pay]=@ra@3safdsR5&sDa ``` ### Enum 列舉？那必須支援 不過實際意義不怎麼大，如果配置的值要可以轉換成列舉值的話，配置的值必須和列舉值的`name`一致，大小寫都不能差，因為`SpringBoot`實現的配置到列舉的轉換，使用的是 ```java /* java.lang.Enum#valueOf */ public static > T valueOf(Class enumType, String name) { // 這裡的name就是列舉值的字元表示，一般都是大寫的 T result = enumType.enumConstantDirectory().get(name); if (result != null) return result; if (name == null) throw new NullPointerException("Name is null"); throw new IllegalArgumentException( "No enum constant " + enumType.getCanonicalName() + "." + name); } ``` > 關於這段程式碼的理解，可以參考另外一片文章[深入理解Java列舉](https://www.cnblogs.com/heartlake/p/12805535.html) 如果列舉還有其他欄位的話，就沒辦法了 ### JavaBean 什麼？ 還是不能滿足？想要直接把配置繫結到一個`JavaBean`？ 幹就完事了！ #### `JavaBean` ```java @Configuration @ConfigurationProperties(prefix="upload") public class UploadConfig{ private String rootPath; private String fileType; private int fileSize; private boolean rename; // 省略 Setter方法 } ``` #### 配置檔案 ```yaml # application.yml upload: root-path: /xx/xx/xx file-type: zip fileSize: 1M rename: false ``` ```properties # application.properties upload.rootPath=/xx/xx/xx upload.fileType=zip upload.fileSize=1M upload.rename=false ``` 以上幾種用法，可以組合使用，非常的靈活 不過如果是`JavaBean`的陣列或者`List`，或者作為`Map`的`value`，會發現繫結不上去。 原因在於，繫結預設是基於`Setter`方法，進行單個欄位的繫結，賦值，而這裡要的是一個`JavaBean`，需要建立一個`JavaBean`物件，再去做屬性繫結賦值。 如果按照這兩步走，也可以做到成功繫結到一個作為元素的`JavaBean`物件。 只是`SpringBoot`並沒有那麼做，而是提供了一個`@ConstructorBinding`註解，讓我們使用構造器繫結資料。 ### 複雜配置 #### `JavBean` ```java @Configuration @ConfigurationProperties(prefix="app") public class AppConfig{ private Map multiDataSourceMap; public void setMultiDataSourceMap(Map multiDataSourceMap){ this.multiDataSourceMap = multiDataSourceMap; } } public class DataSourceMetadata{ private String url; private String driverClass; private String username; private String passowrd; // 省略Setter和Getter } ``` #### 配置檔案 ```yaml app: multiDataSourceMap: ds1: url: jdbc:// driver-class: com.mysql.cj.Driver username: xxx password: xxx ds2: url: jdbc:// driver-class: com.mysql.cj.Driver username: 12sds password: adfwqw # or app: multiDataSourceMap: ds1: { url: jdbc:// driver-class: com.mysql.cj.Driver username: xxx password: xxx } ds2: { url: jdbc:// driver-class: com.mysql.cj.Driver username: 12sds password: adfwqw } ``` 然後啟動，走起，立馬會發現熟悉又可氣的`NPE` 原因很簡單，`SpringBoot`沒能從配置檔案讀取相應的配置資料並且例項化一個`Map`，因為 它現在面對的情況比以前複雜了，現在的`JavaBean`是一個`Map`的`value`值 解決方法就是使用構造器繫結的方式，並且需要在構造器使用此註解`@ConstructorBinding` ```java public class DataSourceMetadata{ private String url; private String driverClass; private String username; private String passowrd; @ConstructorBinding public DataSourceMetadata(String url, String driverClass, String username, String passowrd){ this.url = url; this.driverClass = driverClass; this.username = username; this.password = password; } // 省略Setter和Getter } ``` 只要這麼一搞就正常了，不會有煩人的`NPE` > 我並不知道是否有別的方式也可以做到，比如繼續使用Setter方法來進行資料繫結 ## 瘦身計劃 上面的這些配置，如果都有的話，全部寫到`application.yml`或者`application.properties`檔案中，會導致配置檔案內容太多，而且各種配置混合在一起，不便於管理和維護。 如果需要改動某個配置，就要改動整個檔案，存在一定的風險導致其他配置被誤改。 所以應該一類配置，放到一起去管理。 同樣的，一類配置通常對應一個功能，如果其中一項配置的改動，那麼相應的測試，也能保證同一個配置檔案的修改不會引發其他問題。 所以有必要將`application.yml`拆分了。 花了一番力氣，拆分了一個出來`upload.yml`，然後使用如下方式引入配置檔案 > 配置檔案預設是放在 `resources`目錄下(`maven`/`gradle`)，配置檔案在編譯打包後，會位於`classes`的根目錄下，也就是我們所謂的`classpath` ```java @Configuration @PropertySource("classpath:upload.yml") @ConfigurationProperties(prefix="upload") public class UploadConfig{ private String rootPath; private String fileType; private int fileSize; private boolean rename; // 省略 Setter方法 } ``` 問題來了，死活沒法將資料繫結到`JavaBean`的屬性上。 `Debug`看原始碼，陷進去出不來。試著使用`profile`來解決，雖然可以解決，但是畢竟不是同一個使用場景，並不合適。 最後找人求救，告知`@PropertySource`不支援`yaml`檔案，僅支援`properties`，於是試了下，果然是的 > `SpringBoot`版本是`2.2.6`，有個群友說他`1.5`的還是支援的，不過`SpringBoot`官方明確寫到不支援的 > > #### 2.7.4. YAML Shortcomings > > YAML files cannot be loaded by using the `@PropertySource` annotation. So, in the case that you need to load values that way, you need to use a properties file. 上面看到，其實`yaml`配置更有優勢一些，所以如果想繼續使用`yaml`的話，也不是不可以 #### `@PropertySource`支援自定義檔案格式 ```java // 這裡繼承了DefaultPropertySourceFactory，也可以直接實現PropertySourceFactory public class YamlPropertySourceFactory extends DefaultPropertySourceFactory { public YamlPropertySourceFactory () { super(); } @Override public PropertySource createPropertySource (String name, EncodedResource resource) throws IOException { // 這個判斷是有必要的，因為直接使用name是null，沒深究原因 String nameToUse = name != null ? name : resource.getResource().getFilename(); // yml檔案，使用YamlPropertiesFactoryBean來從yaml檔案Resource中構建一個Properties物件 // 然後使用PropertiesPropertySource封裝成PropertySource物件，就能加入到Environment if (nameToUse.endsWith(".yml")) { YamlPropertiesFactoryBean factoryBean = new YamlPropertiesFactoryBean(); factoryBean.setResources(resource.getResource()); factoryBean.afterPropertiesSet(); return new PropertiesPropertySource(nameToUse, factoryBean.getObject()); } // 如果不是yml配置檔案，使用預設實現 return super.createPropertySource(name, resource); } } ``` 使用時，`@PropertySource(factory=YamlPropertySourceFactory.class)`即可。 ## 使用`@Value` `@Value`是`Spring Framework`的註解，不屬於`SpringBoot`，其典型使用場景就是注入外部化配置屬性，官方文件[@Values](https://docs.spring.io/spring/docs/5.3.0-SNAPSHOT/spring-framework-reference/core.html#beans-value-annotations)介紹 `@Value`使用`Spring`內建的轉化器`SimpleTypeConverter`，這個支援`Integer`，`String`，和逗號分割的字串陣列。 如果覺得支援不夠，還是可以自定義轉換支援，自定義一個`Converter`，然後加入到`ConverterService`這個`Bean`中，因為後面的`BeanPostProcessor`依賴的就是`ConverterService`來處理轉換的 所以如果有一些複雜的配置，最好還是使用`SpringBoot`的方式。 `@Value`的優勢在於，它支援`SpEL`，而且可以使用在任意一個`Bean`的方法引數或者欄位上 所以這是兩種不同的使用場景，看情況自己選擇。 不過總體個人傾向於前面一種，因為如果在其他的`Bean`中直接使用`@Value`，萬一我們要改配置的名字了，結果因為使用了`@Value`，遍佈的到處都是，改起來很麻煩，所以從管理維護的角度來說，`@Value`太野了。 順便說一下對`@Value`的處理位置`org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory#populateBean`，當然這裡也是處理`@Inject` `@Autowired` `@Resource`的地方 ## 後記 從配置檔案到程式中使用到配置的值，一共經歷兩大步 1. 讀取配置內容到`Environment`中，無論任何形式的配置，最後都是一個Property `Source` 2. 通過`BeanPostProcessor`來進行配置值繫結注入 如果不滿足`properties`或者`yaml`格式的配置，可以自定義`PropertySourceLoader`，可以參考 `org.springframework.boot.env.YamlPropertySourceLoader` 和`org.springframework.boot.env.PropertiesPropertySourc