Spring Boot 配置檔案中的花樣，看這一篇足矣

作者：程式猿DD

原文：https://my.oschina.net/didispace/blog/3060464

前言：

在快速入門一節中，我們輕鬆的實現了一個簡單的RESTful API應用，體驗了一下Spring Boot給我們帶來的諸多優點，我們用非常少的程式碼量就成功的實現了一個Web應用，這是傳統的Spring應用無法辦到的，雖然我們在實現Controller時用到的程式碼是一樣的，但是在配置方面，相信大家也注意到了，在上面的例子中，除了Maven的配置之後，就沒有引入任何的配置。

這就是之前我們所提到的，Spring Boot針對我們常用的開發場景提供了一系列自動化配置來減少原本複雜而又幾乎很少改動的模板化配置內容。但是，我們還是需要去了解如何在Spring Boot中修改這些自動化的配置內容，以應對一些特殊的場景需求，比如：我們在同一臺主機上需要啟動多個基於Spring Boot的web應用，若我們不為每個應用指定特別的埠號，那麼預設的8080埠必將導致衝突。

如果您還有在讀我的Spring Cloud系列教程，其實有大量的工作都會是針對配置檔案的。所以我們有必要深入的瞭解一些關於Spring Boot中的配置檔案的知識，比如：它的配置方式、如何實現多環境配置，配置資訊的載入順序等。

配置基礎

在快速入門示例中，我們介紹Spring Boot的工程結構時，有提到過 src/main/resources目錄是Spring Boot的配置目錄，所以我們要為應用建立配置個性化配置時，就是在該目錄之下。

Spring Boot的預設配置檔案位置為： src/main/resources/application.properties。關於Spring Boot應用的配置內容都可以集中在該檔案中了，根據我們引入的不同Starter模組，可以在這裡定義諸如：容器埠名、資料庫連結資訊、日誌級別等各種配置資訊。比如，我們需要自定義web模組的服務埠號，可以在application.properties中新增server.port=8888來指定服務埠為8888，也可以透過spring.application.name=hello來指定應用名（該名字在Spring Cloud應用中會被註冊為服務名）。

Spring Boot的配置檔案除了可以使用傳統的properties檔案之外，還支援現在被廣泛推薦使用的YAML檔案。

YAML（英語發音：/ˈjæməl/，尾音類似camel駱駝）是一個可讀性高，用來表達資料序列的格式。YAML參考了其他多種語言，包括：C語言、Python、Perl，並從XML、電子郵件的資料格式（RFC 2822）中獲得靈感。Clark Evans在2001年首次發表了這種語言，另外Ingy döt Net與Oren Ben-Kiki也是這語言的共同設計者。目前已經有數種程式語言或指令碼語言支援（或者說解析）這種語言。YAML是"YAML Ain't a Markup Language"（YAML不是一種標記語言）的遞迴縮寫。在開發的這種語言時，YAML 的意思其實是："Yet Another Markup Language"（仍是一種標記語言），但為了強調這種語言以資料做為中心，而不是以標記語言為重點，而用反向縮略語重新命名。AML的語法和其他高階語言類似，並且可以簡單表達清單、雜湊表，標量等資料形態。它使用空白符號縮排和大量依賴外觀的特色，特別適合用來表達或編輯資料結構、各種設定檔、傾印除錯內容、檔案大綱（例如：許多電子郵件標題格式和YAML非常接近）。儘管它比較適合用來表達階層式（hierarchical model）的資料結構，不過也有精緻的語法可以表示關聯性（relational model）的資料。由於YAML使用空白字元和分行來分隔資料，使得它特別適合用grep／Python／Perl／Ruby操作。其讓人最容易上手的特色是巧妙避開各種封閉符號，如：引號、各種括號等，這些符號在巢狀結構時會變得複雜而難以辨認。—— 維基百科

YAML採用的配置格式不像properties的配置那樣以單純的鍵值對形式來表示，而是以類似大綱的縮排形式來表示。比如：下面的一段YAML配置資訊

environments:

 dev:

 url: http://dev.bar.com

 name: Developer Setup

 prod:

 url:

 name: My Cool App

與其等價的properties配置如下。

environments.dev.url=http://dev.bar.com

environments.dev.name=Developer Setup

environments.prod.url=

environments.prod.name=My Cool App

透過YAML的配置方式，我們可以看到配置資訊利用階梯化縮排的方式，其結構顯得更為清晰易讀，同時配置內容的字元量也得到顯著的減少。除此之外，YAML還可以在一個單個檔案中透過使用spring.profiles屬性來定義多個不同的環境配置。例如下面的內容，在指定為test環境時，server.port將使用8882埠；而在prod環境，server.port將使用8883埠；如果沒有指定環境，server.port將使用8881埠。

server:

 port: 8881

---

spring:

 profiles: test

server:

 port: 8882

---

spring:

 profiles: prod

server:

 port: 8883

注意：YAML目前還有一些不足，它無法透過@PropertySource註解來載入配置。但是，YAML載入屬性到記憶體中儲存的時候是有序的，所以當配置檔案中的資訊需要具備順序含義時，YAML的配置方式比起properties配置檔案更有優勢。

自定義引數

我們除了可以在Spring Boot的配置檔案中設定各個Starter模組中預定義的配置屬性，也可以在配置檔案中定義一些我們需要的自定義屬性。比如在application.properties中新增：

book.name=SpringCloudInAction

book.author=ZhaiYongchao

然後，在應用中我們可以透過@Value註解來載入這些自定義的引數，比如：

@Component

public class Book {

 @Value("${book.name}")

 private String name;

 @Value("${book.author}")

 private String author;

 // 省略getter和setter

}

@Value註解載入屬性值的時候可以支援兩種表示式來進行配置：

一種是我們上面介紹的PlaceHolder方式，格式為 ${...} ，大括號內為PlaceHolder

另外還可以使用SpEL表示式（Spring Expression Language）， 格式為 #{...} ，大括號內為SpEL表示式

引數引用

在application.properties中的各個引數之間，我們也可以直接透過使用PlaceHolder的方式來進行引用，就像下面的設定：

book.name=SpringCloud

book.author=ZhaiYongchao

book.desc=${book.author} is writing《${book.name}》

book.desc引數引用了上文中定義的book.name和book.author屬性，最後該屬性的值就是ZhaiYongchao is writing《SpringCloud》。

使用隨機數

在一些特殊情況下，有些引數我們希望它每次載入的時候不是一個固定的值，比如：金鑰、服務埠等。在Spring Boot的屬性配置檔案中，我們可以透過使用${random}配置來產生隨機的int值、long值或者string字串，這樣我們就可以容易的透過配置來屬性的隨機生成，而不是在程式中透過編碼來實現這些邏輯。

${random}的配置方式主要有一下幾種，讀者可作為參考使用。

# 隨機字串

com.didispace.blog.value=${random.value}

# 隨機int

com.didispace.blog.number=${random.int}

# 隨機long

com.didispace.blog.bignumber=${random.long}

# 10以內的隨機數

com.didispace.blog.test1=${random.int(10)}

# 10-20的隨機數

com.didispace.blog.test2=${random.int[10,20]}

該配置方式可以用於設定應用埠等場景，避免在本地除錯時出現埠衝突的麻煩

命令列引數

回顧一下在本章的快速入門中，我們還介紹瞭如何啟動Spring Boot應用，其中提到了使用命令java -jar命令來啟動的方式。該命令除了啟動應用之外，還可以在命令列中來指定應用的引數，比如：java -jar xxx.jar --server.port=8888，直接以命令列的方式，來設定server.port屬性，另啟動應用的埠設為8888。

在命令列方式啟動Spring Boot應用時，連續的兩個減號--就是對application.properties中的屬性值進行賦值的標識。所以，java -jar xxx.jar --server.port=8888命令，等價於我們在application.properties中新增屬性server.port=8888。

透過命令列來修改屬性值是Spring Boot非常重要的一個特性，透過此特性，理論上已經使得我們應用的屬性在啟動前是可變的，所以其中埠號也好、資料庫連線也好，都是可以在應用啟動時發生改變，而不同於以往的Spring應用透過Maven的Profile在編譯器進行不同環境的構建。其最大的區別就是，Spring Boot的這種方式，可以讓應用程式的打包內容，貫穿開發、測試以及線上部署，而Maven不同Profile的方案每個環境所構建的包，其內容本質上是不同的。但是，如果每個引數都需要透過命令列來指定，這顯然也不是一個好的方案，所以下面我們看看如果在Spring Boot中實現多環境的配置。

多環境配置

我們在開發任何應用的時候，通常同一套程式會被應用和安裝到幾個不同的環境，比如：開發、測試、生產等。其中每個環境的資料庫地址、伺服器埠等等配置都會不同，如果在為不同環境打包時都要頻繁修改配置檔案的話，那必將是個非常繁瑣且容易發生錯誤的事。

對於多環境的配置，各種專案構建工具或是框架的基本思路是一致的，透過配置多份不同環境的配置檔案，再透過打包命令指定需要打包的內容之後進行區分打包，Spring Boot也不例外，或者說更加簡單。

在Spring Boot中多環境配置檔名需要滿足application-{profile}.properties的格式，其中{profile}對應你的環境標識，比如：

application-dev.properties：開發環境

application-test.properties：測試環境

application-prod.properties：生產環境

至於哪個具體的配置檔案會被載入，需要在application.properties檔案中透過spring.profiles.active屬性來設定，其值對應配置檔案中的{profile}值。如：spring.profiles.active=test就會載入application-test.properties配置檔案內容。

下面，以不同環境配置不同的服務埠為例，進行樣例實驗。

針對各環境新建不同的配置檔案application-dev.properties、application-test.properties、application-prod.properties

在這三個檔案均都設定不同的server.port屬性，如：dev環境設定為1111，test環境設定為2222，prod環境設定為3333

application.properties中設定spring.profiles.active=dev，就是說預設以dev環境設定

測試不同配置的載入

執行java -jar xxx.jar，可以觀察到服務埠被設定為1111，也就是預設的開發環境（dev）

執行java -jar xxx.jar --spring.profiles.active=test，可以觀察到服務埠被設定為2222，也就是測試環境的配置（test）

執行java -jar xxx.jar --spring.profiles.active=prod，可以觀察到服務埠被設定為3333，也就是生產環境的配置（prod）

按照上面的實驗，可以如下總結多環境的配置思路：

application.properties中配置通用內容，並設定spring.profiles.active=dev，以開發環境為預設配置

application-{profile}.properties中配置各個環境不同的內容

透過命令列方式去啟用不同環境的配置

載入順序

在上面的例子中，我們將Spring Boot應用需要的配置內容都放在了專案工程中，雖然我們已經能夠透過spring.profiles.active或是透過Maven來實現多環境的支援。但是，當我們的團隊逐漸壯大，分工越來越細緻之後，往往我們不需要讓開發人員知道測試或是生成環境的細節，而是希望由每個環境各自的負責人（QA或是運維）來集中維護這些資訊。那麼如果還是以這樣的方式儲存配置內容，對於不同環境配置的修改就不得不去獲取工程內容來修改這些配置內容，當應用非常多的時候就變得非常不方便。同時，配置內容都對開發人員可見，本身這也是一種安全隱患。對此，現在出現了很多將配置內容外部化的框架和工具，後續將要介紹的Spring Cloud Config就是其中之一，為了後續能更好的理解Spring Cloud Config的載入機制，我們需要對Spring Boot對資料檔案的載入機制有一定的瞭解。

Spring Boot為了能夠更合理的重寫各屬性的值，使用了下面這種較為特別的屬性載入順序：

命令列中傳入的引數。

SPRING_APPLICATION_JSON中的屬性。SPRING_APPLICATION_JSON是以JSON格式配置在系統環境變數中的內容。

java:comp/env中的JNDI屬性。

Java的系統屬性，可以透過System.getProperties()獲得的內容。

作業系統的環境變數

透過random.*配置的隨機屬性

位於當前應用jar包之外，針對不同{profile}環境的配置檔案內容，例如：application-{profile}.properties或是YAML定義的配置檔案

位於當前應用jar包之內，針對不同{profile}環境的配置檔案內容，例如：application-{profile}.properties或是YAML定義的配置檔案

位於當前應用jar包之外的application.properties和YAML配置內容

位於當前應用jar包之內的application.properties和YAML配置內容

在@Configuration註解修改的類中，透過@PropertySource註解定義的屬性

應用預設屬性，使用SpringApplication.setDefaultProperties定義的內容

優先順序按上面的順序有高到低，數字越小優先順序越高。

可以看到，其中第7項和第9項都是從應用jar包之外讀取配置檔案，所以，實現外部化配置的原理就是從此切入，為其指定外部配置檔案的載入位置來取代jar包之內的配置內容。透過這樣的實現，我們的工程在配置中就變的非常乾淨，我們只需要在本地放置開發需要的配置即可，而其他環境的配置就可以不用關心，由其對應環境的負責人去維護即可。

2.x 新特性

在Spring Boot 2.0中推出了Relaxed Binding 2.0，對原有的屬性繫結功能做了非常多的改進以幫助我們更容易的在Spring應用中載入和讀取配置資訊。下面本文就來說說Spring Boot 2.0中對配置的改進。

配置檔案繫結

簡單型別

在Spring Boot 2.0中對配置屬性載入的時候會除了像1.x版本時候那樣移除特殊字元外，還會將配置均以全小寫的方式進行匹配和載入。所以，下面的4種配置方式都是等價的：

properties格式：

spring.jpa.databaseplatform=mysql

spring.jpa.database-platform=mysql

spring.jpa.databasePlatform=mysql

spring.JPA.database_platform=mysql

yaml格式：

spring:

 jpa:

 databaseplatform: mysql

 database-platform: mysql

 databasePlatform: mysql

 database_platform: mysql

Tips：推薦使用全小寫配合-分隔符的方式來配置，比如：spring.jpa.database-platform=mysql

List型別

在properties檔案中使用[]來定位列表型別，比如：

spring.my-example.url[0]=

spring.my-example.url[1]=

也支援使用逗號分割的配置方式，上面與下面的配置是等價的：

spring.my-example.url=,

而在yaml檔案中使用可以使用如下配置：

spring:

 my-example:

 url:

 -

 -

也支援逗號分割的方式：

spring:

 my-example:

 url: ,

注意：在Spring Boot 2.0中對於List型別的配置必須是連續的，不然會丟擲UnboundConfigurationPropertiesException異常，所以如下配置是不允許的：

foo[0]=a

foo[2]=b

在Spring Boot 1.x中上述配置是可以的，foo[1]由於沒有配置，它的值會是null

Map型別

Map型別在properties和yaml中的標準配置方式如下：

properties格式：

spring.my-example.foo=bar

spring.my-example.hello=world

yaml格式：

spring:

 my-example:

 foo: bar

 hello: world

注意：如果Map型別的key包含非字母數字和-的字元，需要用[]括起來，比如：

spring:

 my-example:

 '[foo.baz]': bar

環境屬性繫結

簡單型別

在環境變數中透過小寫轉換與.替換_來對映配置檔案中的內容，比如：環境變數SPRING_JPA_DATABASEPLATFORM=mysql的配置會產生與在配置檔案中設定spring.jpa.databaseplatform=mysql一樣的效果。

List型別

由於環境變數中無法使用[和]符號，所以使用_來替代。任何由下劃線包圍的數字都會被認為是[]的陣列形式。比如：

MY_FOO_1_ = my.foo[1]

MY_FOO_1_BAR = my.foo[1].bar

MY_FOO_1_2_ = my.foo[1][2]

另外，最後環境變數最後是以數字和下劃線結尾的話，最後的下劃線可以省略，比如上面例子中的第一條和第三條等價於下面的配置：

MY_FOO_1 = my.foo[1]

MY_FOO_1_2 = my.foo[1][2]

系統屬性繫結

簡單型別

系統屬性與檔案配置中的類似，都以移除特殊字元並轉化小寫後實現繫結，比如下面的命令列引數都會實現配置spring.jpa.databaseplatform=mysql的效果：

-Dspring.jpa.database-platform=mysql

-Dspring.jpa.databasePlatform=mysql

-Dspring.JPA.database_platform=mysql

List型別

系統屬性的繫結也與檔案屬性的繫結類似，透過[]來標示，比如：

-D"spring.my-example.url[0]="

-D"spring.my-example.url[1]="

同樣的，他也支援逗號分割的方式，比如：

-Dspring.my-example.url=,

屬性的讀取

上文介紹了Spring Boot 2.0中對屬性繫結的內容，可以看到對於一個屬性我們可以有多種不同的表達，但是如果我們要在Spring應用程式的environment中讀取屬性的時候，每個屬性的唯一名稱符合如下規則：

透過.分離各個元素

最後一個.將字首與屬性名稱分開

必須是字母（a-z）和數字(0-9)

必須是小寫字母

用連字元-來分隔單詞

唯一允許的其他字元是[和]，用於List的索引

不能以數字開頭

所以，如果我們要讀取配置檔案中spring.jpa.database-platform的配置，可以這樣寫：

this.environment.containsProperty("spring.jpa.database-platform")

而下面的方式是無法獲取到spring.jpa.database-platform配置內容的：

this.environment.containsProperty("spring.jpa.databasePlatform")

注意：使用@Value獲取配置內容的時候也需要這樣的特點

全新的繫結API

在Spring Boot 2.0中增加了新的繫結API來幫助我們更容易的獲取配置資訊。下面舉個例子來幫助大家更容易的理解：

例子一：簡單型別

假設在propertes配置中有這樣一個配置：com.didispace.foo=bar

我們為它建立對應的配置類：

@Data

@ConfigurationProperties(prefix = "com.didispace")

public class FooProperties {

 private String foo;

}

接下來，透過最新的Binder就可以這樣來拿配置資訊了：

@SpringBootApplication

public class Application {

 public static void main(String[] args) {

 ApplicationContext context = SpringApplication.run(Application.class, args);

 Binder binder = Binder.get(context.getEnvironment());

 // 繫結簡單配置

 FooProperties foo = binder.bind("com.didispace", Bindable.of(FooProperties.class)).get();

 System.out.println(foo.getFoo());

 }

}

例子二：List型別

如果配置內容是List型別呢？比如：

com.didispace.post[0]=Why Spring Boot

com.didispace.post[1]=Why Spring Cloud

com.didispace.posts[0].title=Why Spring Boot

com.didispace.posts[0].content=It is perfect!

com.didispace.posts[1].title=Why Spring Cloud

com.didispace.posts[1].content=It is perfect too!

要獲取這些配置依然很簡單，可以這樣實現：

ApplicationContext context = SpringApplication.run(Application.class, args);

Binder binder = Binder.get(context.getEnvironment());

// 繫結List配置

List<String> post = binder.bind("com.didispace.post", Bindable.listOf(String.class)).get();

System.out.println(post);

List<PostInfo> posts = binder.bind("com.didispace.posts", Bindable.listOf(PostInfo.class)).get();

System.out.println(posts);

程式碼示例

順便在此給大家推薦一個 Java架構方面的交流學習群： 834962734 ，裡面會分享一些資深架構師錄製的影片資料：有 Spring，MyBatis，Netty原始碼分析，高併發、高效能、分散式、微服務架構的原理，JVM效能最佳化這些成為架構師必備的知識體系，主要針對Java開發人員提升自己，突破瓶頸，相信你來交流學習，會有提升和收穫。

本教程配套倉庫：

Github：

Gitee：

---------------------