Spring Boot 2.0 配置圖文教程

本章內(nèi)容

1. 自定義屬性快速入門

2. 外化配置

3. 自動配置

4. 自定義創(chuàng)建 Starter 組件

圖 2 第二章目錄結(jié)構(gòu)圖

第 2 章 Spring Boot 配置

Spring Boot 配置，包括自動配置和外化配置。本章先實現(xiàn)自定義屬性工程，將屬性外化配置在 application.properties 應(yīng)用配置文件，然后在工程中獲取該屬性值。接著會詳細(xì)介紹屬性的獲取方式、外化配置和自動配置。最后會介紹利用自動配置自定義 Start 組件。

2.1 快速入門工程

第一章的 HelloBookController 控制層中，在代碼中以硬編碼的方式使用字符串表示書信息。下面把書的信息作為屬性，外化配置在 application.properties 。好處是將應(yīng)用參數(shù)、業(yè)務(wù)參數(shù)或第三方參數(shù)等統(tǒng)一配置在應(yīng)用配置文件中，避免配置侵入業(yè)務(wù)代碼，達(dá)到可配置的方式，方便及時調(diào)整修改。

2.1.1 配置屬性

新建工程命名為 chapter-2-spring-boot-config ，在 application.properties 中配置書名和作者，配置如下：

## 書信息demo.book.name=[Spring Boot 2.x Core Action]
demo.book.writer=BYSocket

.properties 文件的每行參數(shù)被存儲為一對字符串，即一個存儲參數(shù)名稱，被稱為鍵；另一個為值。一般稱為鍵值對配置。井號（#）或者英文狀態(tài)下的嘆號（!）作為第一行中第一個非空字符來表示該行的文本為注釋。另外，反斜杠（\）用于轉(zhuǎn)義字符。

Spring Boot 支持并推薦使用 YAML 格式的配置文件，將 application.properties 文件替換成 application.yml 文件，并配置相同的屬性，配置如下：

## 書信息demo:
    book:
        name: 《Spring Boot 2.x 核心技術(shù)實戰(zhàn) - 上 基礎(chǔ)篇》
        writer: 泥瓦匠BYSocket

YAML 是一個可讀性高，用來表達(dá)數(shù)據(jù)序列的格式。表示鍵值對格式時，注意鍵和值由冒號及空白字符分開。強調(diào)下，空白字符是必須的，IDE 一般也會提示。兩種配置方式都非常便捷，在開發(fā)中選擇 .properties 或 .yml 文件配置。但如果兩種配置文件同時存在的時候，默認(rèn)優(yōu)先使用 .properties 配置文件。YAML 與 .properties 配置文件對比如圖 2-1 所示：

圖 2-1 YAML 與 .properties 配置文件對比

注意：

在 application.properties 配置中文值，讀取時會出現(xiàn)中文亂碼問題。因為 Java .properties 文件默認(rèn)編碼方式是 iso-8859 ，Spring Boot 應(yīng)用以 UTF-8 的編碼方式讀取，就導(dǎo)致出現(xiàn)亂碼問題。

官方 Issue 中的解決方法是，將 .properties 文件中配置的中文值轉(zhuǎn)義成 Unicode 編碼形式。例如 demo.book.writer=泥瓦匠 應(yīng)該配置成 demo.book.writer=\u6ce5\u74e6\u5320 。利用 IDEA properties 插件 或利用 Java 文件轉(zhuǎn)碼工具 native2ascii 來快速地進(jìn)行轉(zhuǎn)義。該工具有在線版實現(xiàn)，地址如下：
https://javawind.net/tools/native2ascii.jsp

2.1.2 創(chuàng)建屬性類

在工程中新建包目錄 demo.springboot.config ，并在目錄中創(chuàng)建名為 BookProperties 的屬性類，代碼如下：

import org.springframework.beans.factory.annotation.Value;import org.springframework.stereotype.Component;/**
 * 書屬性
 */@Componentpublic class BookProperties {    /**
     * 書名
     */
    @Value("${demo.book.name}")    private String name;    /**
     * 作者
     */
    @Value("${demo.book.writer}")    private String writer;    // ... 省略 getter / setter 方法}

利用 @Component 注解定義了書的屬性 Bean，并通過 @Value 注解為該 Bean 的成員變量（或者方法參數(shù)）自動注入 application.properties 文件的屬性值。@Value 注解是通過 “${propName}” 的形式引用屬性，propName 表示屬性名稱。

核心注解的知識點：

• @Component 注解：
  @Component 對類進(jìn)行標(biāo)注，職責(zé)是泛指組件 Bean ，應(yīng)用啟動時會被容器加載并加入容器管理。常見的 @Controller、@Service 、@Repository 是 @Component 的分類細(xì)化組件，分別對應(yīng)控制層、服務(wù)層、持久層的 Bean。

   

• @Value 注解：
  @Value 對 Bean 的字段或者方法參數(shù)進(jìn)行標(biāo)注，職責(zé)是基于表達(dá)式給字段或方法參數(shù)設(shè)置默認(rèn)屬性值。通常格式是注解 + SpEL 表達(dá)式，如 @Value("SpEL 表達(dá)式")。

使用 @Vlaue 注解來引用屬性值時，確保所引用的屬性值在 application.properties 文件存在并且相對應(yīng)匹配，否則會造成 Bean 的創(chuàng)建錯誤，引發(fā) java.lang.IllegalArgumentException 非法參數(shù)異常。

2.1.3 獲取屬性

修改原有的 HelloBookController 類，通過注入的方式獲取書屬性 Bean 并返回。代碼如下：

import demo.springboot.config.BookProperties;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.web.bind.annotation.GetMapping;import org.springframework.web.bind.annotation.RestController;

@RestControllerpublic class HelloBookController {

    @Autowired
    BookProperties bookProperties;

    @GetMapping("/book/hello")
    public String sayHello() {        return "Hello， " + bookProperties.getWriter() + " is writing "
                + bookProperties.getName() + " ！";
    }
}

通過 @Autowired 注解標(biāo)記在 BookProperties 字段，控制層自動裝配屬性 Bean 并使用。默認(rèn)情況下要求被注解的 Bean 必須存在，需要允許 NULL 值，可以設(shè)置其 required 屬性為 false： @Autowired(required = false)。

2.1.4 運行工程

執(zhí)行 ConfigApplication 類啟動，在控制臺看到成功運行的輸出后，打開瀏覽器訪問 /book/hello 地址，可以看到如圖 2-2 所示的返回結(jié)果：

圖 2-2 Hello Book 頁面

也可以通過單元測試的方式驗證屬性獲取是否成功，單元測試具體相關(guān)的會在第 9 章節(jié)介紹。單元測試代碼如下：

import demo.springboot.config.BookProperties;import org.junit.Assert;import org.junit.Test;import org.junit.runner.RunWith;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.test.context.SpringBootTest;import org.springframework.test.context.junit4.SpringRunner;@RunWith(SpringRunner.class)@SpringBootTestpublic class ConfigApplicationTests {    @Autowired
    BookProperties bookProperties;    @Test
    public void testBookProperties() {
        Assert.assertEquals(bookProperties.getName(),"'Spring Boot 2.x Core Action'");
        Assert.assertEquals(bookProperties.getWriter(),"BYSocket");
    }
}

2.2 配置屬性的獲取方式

配置屬性的常用獲取方式有基于 @Value 和 @ConfigurationProperties 注解兩種方式。兩種方式適合的場景不同，下面具體介紹其使用方法和場景。

2.2.1 @Value 注解

@Value 注解對 Bean 的變量或者方法參數(shù)進(jìn)行標(biāo)注，職責(zé)是基于表達(dá)式給字段或方法參數(shù)設(shè)置默認(rèn)屬性值。通常格式是注解 + SpEL 表達(dá)式，如 @Value("SpEL 表達(dá)式")，并標(biāo)注在對應(yīng)的字段或者方法上方，且必須對變量一一標(biāo)注。這種方式適用于小而不復(fù)雜的屬性結(jié)構(gòu)。屬性結(jié)構(gòu)復(fù)雜，字段很多的情況下，這種方式會比較繁瑣，應(yīng)該考慮使用 @ConfigurationProperties 注解。

另外通過 @PropertySource 注解引入對應(yīng)路徑的其他 .properties 文件。將書信息重新配置在 classpath 下新的 book.properties 配置文件后，讀取新配置文件的代碼如下：

import org.springframework.beans.factory.annotation.Value;import org.springframework.context.annotation.PropertySource;import org.springframework.stereotype.Component;/**
 * 書屬性
 */@Component@PropertySource("classpath:book.properties")public class BookProperties {    /**
     * 書名
     */
    @Value("${demo.book.name}")    private String name;    /**
     * 作者
     */
    @Value("${demo.book.writer}")    private String writer;    // ... 省略 getters / setters 方法}

2.2.2 @ConfigurationProperties 注解

在包目錄 demo.springboot.config 中創(chuàng)建名為 BookComponent 的屬性類，并使用 @ConfigurationProperties 注解獲取屬性，代碼如下：

import org.springframework.boot.context.properties.ConfigurationProperties;import org.springframework.stereotype.Component;/**
 * 書屬性
 *
 */@Component
@ConfigurationProperties(prefix = "demo.book")public class BookComponent {

    /**
     * 書名
     */
    private String name;    /**
     * 作者
     */
    private String writer;    // ... 省略 getters / setters 方法}

類似 @Value 注解方式，使用 @ConfigurationProperties(prefix = "demo.book") 注解標(biāo)注在類上方可以達(dá)到相同的效果。 @ConfigurationProperties 注解的 prefix 是指定屬性的參數(shù)名稱。會匹配到配置文件中 “ demo.book.* ” 結(jié)構(gòu)的屬性，星號 “ * ” 是指會一一對應(yīng)匹配 BookComponent 類的字段名。例如，字段 name 表示書名，會匹配到 demo.book.name 屬性值。

@Value 注解方式強制字段必須對應(yīng)在配置文件， @ConfigurationProperties 注解方式則不是必須的。一般情況下，所有字段應(yīng)該保證一一對應(yīng)在配置文件。如果沒有屬性值對應(yīng)的話，該字段默認(rèn)為空， @ConfigurationProperties 注解方式也不會引發(fā)任何異常，Spring Boot 推薦使用 @ConfigurationProperties 注解方式獲取屬性。

同樣使用單元測試驗證獲取屬性是否成功。單元測試代碼如下：

@AutowiredBookComponent bookComponent;@Testpublic void testBookComponent() {
    Assert.assertEquals(bookComponent.getName(),"'Spring Boot 2.x Core Action'");
    Assert.assertEquals(bookComponent.getWriter(),"BYSocket");
}

API org.springframework.boot.context.properties.ConfigurationProperties 注解參數(shù)

• prefix
  字符串值，綁定該名稱前綴的屬性對象。

• value
  字符串值，功能同 prefix 參數(shù)。

• ignoreInvalidFields
  布爾值，默認(rèn) false。綁定對象時，忽略無效字段。

• ignoreUnknownFields
  布爾值，默認(rèn) true。綁定對象時，忽略未知字段。

2.2.3 @ConfigurationProperties 數(shù)據(jù)驗證

@ConfigurationProperties 注解方式支持驗證功能，即當(dāng)屬性類被 @Validated 注解標(biāo)注時，Spring Boot 初始化時會驗證類的字段。在類的字段上添加 JSR-303 約束注解，進(jìn)行數(shù)據(jù)驗證。下面為書屬性字段添加非 NULL 和字符串非空約束，代碼如下：

import org.springframework.boot.context.properties.ConfigurationProperties;import org.springframework.stereotype.Component;import org.springframework.validation.annotation.Validated;import javax.validation.constraints.NotEmpty;import javax.validation.constraints.NotNull;/**
 * 書屬性
 *
 */@Component@ConfigurationProperties(prefix = "demo.book")@Validatedpublic class BookComponent {    /**
     * 書名
     */
    @NotEmpty
    private String name;    /**
     * 作者
     */
    @NotNull
    private String writer;    // ... 省略 getters / setters 方法}

通過 @Validated 注解開啟對 BookComponent 類字段的數(shù)據(jù)驗證，如果 name 字段為 NULL 或者為空字符串時，會引發(fā) BindValidationException 綁定數(shù)據(jù)驗證異常。數(shù)據(jù)驗證常用在郵箱格式或者有長度限制的屬性字段。另外，驗證嵌套屬性的值，必須在嵌套對象字段上方標(biāo)注 @Valid 注解，用來觸發(fā)其驗證。例如，在書屬性中新增嵌套對象出版社 Publishing，就需要在該對象上方標(biāo)注 @Valid 注解，來開啟對 Publishing 對象的數(shù)據(jù)驗證。綜上，兩種屬性獲取方式各有優(yōu)缺點，對比如圖 2-3 所示：

圖 2-3 @ConfigurationPropertiesd vs @Value

2.3 外化配置

Spring Boot 可以將配置外部化，即分離存儲在 classpath 之外，這種模式叫做 “外化配置”。常用在不同環(huán)境中，將配置從代碼中分離外置，只要簡單地修改下外化配置，可以依舊運行相同的應(yīng)用代碼。外化配置表現(xiàn)形式不單單是 .properties 和 .yml 屬性文件，還可以使用環(huán)境變量和命令行參數(shù)等來實現(xiàn)。那么，多處配置了相同屬性時，Spring Boot 是通過什么方式來控制外化配置的沖突呢？答案是外化配置優(yōu)先級。

2.3.1 外化配置優(yōu)先級

用命令行配置去覆蓋 .properties 文件配置方法很簡單。正常情況下利用 Java 命令運行工程，代碼如下：

// chapter-2-spring-boot-config 目錄下運行java -jar target/chapter-2-spring-boot-config-1.0.jar

下面將書的作者信息 BYSocket 改成 Jeff ， 通過命令行配置覆蓋屬性，代碼如下：

java -jar target/chapter-2-spring-boot-config-1.0.jar --demo.book.writer=Jeff

在命令行配置中，設(shè)置屬性值的格式是用兩個連續(xù)的減號 “--”標(biāo)志屬性。在控制臺看到成功運行的輸出后，打開瀏覽器，訪問 /book/hello 地址，可以看到如圖 2-4 所示的返回結(jié)果：

圖 2-4 書信息被覆蓋頁面

通過命令行配置覆蓋屬性提供了非常大的作用與便利性，常見于使用 shell 腳本運行工程時，可以方便地修改工程運行的配置。

但是這就引發(fā)了一個問題，豈不讓工程很有侵入性，如果開放這個功能，導(dǎo)致未知的安全問題。所以 Spring Boot 提供了屏蔽命令行屬性值設(shè)置，在應(yīng)用啟動類中設(shè)置 setAddCommandLineProperties 方法為 false ，用于關(guān)閉命令行配置功能，代碼如下：

SpringApplication.setAddCommandLineProperties(false);

命令行配置屬性的優(yōu)先級是第四。外化配置獲取屬性時，會按優(yōu)先級從高到低獲取。如果高優(yōu)先級存在屬性，則返回屬性，并忽略優(yōu)先級低的屬性。優(yōu)先級如下：

1. 本地 Devtools 全局配置

2. 測試時 @TestPropertySource 注解配置

3. 測試時 @SpringBootTest 注解的 properties 配置

4. 命令行配置

5. SPRING_APPLICATION_JSON 配置

6. ServletConfig 初始化參數(shù)配置

7. ServletContext 初始化參數(shù)配置

8. Java 環(huán)境的 JNDI 參數(shù)配置

9. Java 系統(tǒng)的屬性配置

10. OS 環(huán)境變量配置

11. 只能隨機(jī)屬性的 RandomValuePropertySource 配置

12. 工程 jar 之外的多環(huán)境配置文件（application- {profile}.properties 或 YAML）

13. 工程 jar 之內(nèi)的多環(huán)境配置文件（application- {profile}.properties 或 YAML）

14. 工程 jar 之外的應(yīng)用配置文件（application.properties 或 YAML）

15. 工程 jar 之內(nèi)的應(yīng)用配置文件（application.properties 或 YAML）

16. @Configuration 類中的 @PropertySource 注解配置

17. 默認(rèn)屬性配置（SpringApplication.setDefaultProperties 指定）

2.3.2 屬性引用

在 application.properties 中配置屬性時，屬性之間可以直接通過 “${propName}” 的形式引用其他屬性。比如新增書的描述 description 屬性，代碼如下：

## 書信息demo.book.name=[Spring Boot 2.x Core Action]demo.book.writer=BYSocketdemo.book.description=${demo.book.writer}'s${demo.book.name}

demo.book.description 屬性引用了前面定義的 demo.book.name 和 demo.book.writer 屬性，其值為 BYSocket's[Spring Boot 2.x Core Action] 。一方面可以使相同配置可以復(fù)用，另一方面增強了配置的閱讀性。

2.3.3 使用隨機(jī)數(shù)

在 application.properties 中配置屬性時，可以使用隨機(jī)數(shù)配置，例如注入某些密鑰、UUID 或者測試用例，需要每次不是一個固定的值。RandomValuePropertySource 類隨機(jī)提供×××、長×××數(shù)、UUID 或者字符串。使用代碼如下：

my.secret=${random.value}
my.number=${random.int}
my.bignumber=${random.long}
my.uuid=${random.uuid}
my.number.less.than.ten=${random.int(10)}
my.number.in.range=${random.int[1024,65536]}

2.3.4 多環(huán)境配置

多環(huán)境是指不同配置的生產(chǎn)服務(wù)器使用同一工程代碼部署，比如：開發(fā)環(huán)境、測試環(huán)境、預(yù)發(fā)環(huán)境、生產(chǎn)環(huán)境等。各個環(huán)境的工程端口、數(shù)據(jù)庫配置、Redis 配置、日志配置等都會不同，傳統(tǒng)模式下需要修改配置，工程重新編譯打包，并部署到指定環(huán)境服務(wù)器。結(jié)果是容易發(fā)生配置錯誤，導(dǎo)致開發(fā)部署效率低下。Spring Boot 使用多環(huán)境配置去解決這個問題。

多環(huán)境配置，類似 Maven 構(gòu)建配置文件的思路，即配置多個不同環(huán)境的配置文件，再通過 spring.profiles.active 命令去指定讀取特定配置文件的屬性。多環(huán)境配置文件是不同于 application.properties 應(yīng)用配置文件。多環(huán)境配置文件的約定命名格式為 application-{profile}.properties。多環(huán)境配置功能默認(rèn)為激活狀態(tài)，如果其他配置未被激活，則 {profile} 默認(rèn)為 default，會加載 application-default.properties 默認(rèn)配置文件，沒有該文件就會加載 application.properties 應(yīng)用配置文件。

多環(huán)境配置文件的屬性讀取方式和從 application.properties 應(yīng)用配置文件讀取方式一致。不管多環(huán)境配置文件在工程 jar 包內(nèi)還是包外，按照配置優(yōu)先級覆蓋其他配置文件。在微服務(wù)實踐開發(fā)中，經(jīng)常會使用一個類似 deploy 工程去管理配置文件和打包其他業(yè)務(wù)工程。

在 application.properties 同級目錄中，新建 application-dev.properties 作為開發(fā)環(huán)境配置文件，配置如下：

## 書信息demo.book.name=[Spring Boot 2.x Core Action]  From Dev
demo.book.writer=BYSocket

新建 application-prod.properties 作為生產(chǎn)環(huán)境配置文件，代碼如下：

## 書信息demo.book.name=<Spring Boot 2.x Core Action Dev> From Prod
demo.book.writer=BYSocket

通過命令行指定讀取 dev 環(huán)境配置文件并運行工程，代碼如下：

java -jar target/chapter-2-spring-boot-config-1.0.jar --spring.profiles.active=dev

在多個環(huán)境配置中，通過命令 --spring.profiles.active=dev 指定讀取某個配置文件，將 dev 更改成 prod ，輕松切換讀取生產(chǎn)環(huán)境配置。也可以在控制臺的日志中確定配置讀取來自 dev ：

2017-11-09 12:10:52.978  INFO 72450 --- [           main] demo.springboot.ConfigApplication        : The following profiles are active: dev

最后打開瀏覽器，訪問 /book/hello 地址，可以看到如圖 2-5 所示的返回結(jié)果：

圖 2-5 dev 環(huán)境書信息頁面

2.4 自動配置

Spring Boot spring-boot-autoconfigure 依賴實現(xiàn)了默認(rèn)的配置項，即應(yīng)用默認(rèn)值。這種模式叫做 “自動配置”。Spring Boot 自動配置會根據(jù)添加的依賴，自動加載依賴相關(guān)的配置屬性并啟動依賴。例如默認(rèn)用的內(nèi)嵌式容器是 Tomcat ，端口默認(rèn)設(shè)置為 8080。

為什么需要自動配置？顧名思義，自動配置的意義是利用這種模式代替了配置 XML 繁瑣模式。以前使用 Spring MVC ，需要進(jìn)行配置組件掃描、調(diào)度器、視圖解析器等，使用 Spring Boot 自動配置后，只需要添加 MVC 組件即可自動配置所需要的 Bean。所有自動配置的實現(xiàn)都在 spring-boot-autoconfigure 依賴中，包括 Spring MVC 、Data 和其它框架的自動配置。

2.4.1 spring-boot-autoconfigure 依賴

spring-boot-autoconfigure 依賴，是 Spring Boot 實現(xiàn)自動配置的核心 Starter 組件。其實現(xiàn)源碼包結(jié)構(gòu)如圖 2-6 所示：

圖 2-6 spring-boot-autoconfigure 依賴包目錄

從圖中可以看出，其中常見核心的包如下：

org.springframework.boot.autoconfigureorg.springframework.boot.autoconfigure.data.jpaorg.springframework.boot.autoconfigure.thymeleaforg.springframework.boot.autoconfigure.web.servletorg.springframework.boot.autoconfigure.web.reactive... 省略

在各自包目錄下有對應(yīng)的自動配置類，代碼如下：

JpaRepositoriesAutoConfiguration ThymeleafAutoConfiguration
WebMvcAutoConfiguration
WebFluxAutoConfiguration
... 省略

上面自動配置類依次是 Jpa 自動配置類、Thymeleaf 自動配置類、Web MVC 自動配置類和 WebFlux 自動配置類。WebFlux 響應(yīng)式框架會在第 3 章 詳細(xì)介紹使用。

spring-boot-autoconfigure 職責(zé)是通過 @EnableAutoConfiguration 核心注解，掃描 ClassPath 目錄中自動配置類對應(yīng)依賴，并按一定規(guī)則獲取默認(rèn)配置并自動初始化所需要的 Bean。在 application.properties 配置文件也可以修改默認(rèn)配置項，常用配置清單地址如下：

https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html

2.4.2 @EnableAutoConfiguration 注解

自動配置工作機(jī)制是通過 @EnableAutoConfiguration 注解中 @Import 的 AutoConfigurationImportSelector 自動配置導(dǎo)入選擇器類實現(xiàn)的。查閱源碼可得具體流程如下：

• AutoConfigurationImportSelector 通過 SpringFactoriesLoader.loadFactoryNames() 核心方法讀取 ClassPath 目錄下面的 META-INF/spring.factories 文件。

• spring.factories 文件中配置的 Spring Boot 自動配置類，例如常見的 WebMvcAutoConfiguration Web MVC 自動配置類和ServletWebServerFactoryAutoConfiguration 容器自動配置類 。

• spring.factories 文件和 application.properties 文件都屬于配置文件，配置的格式均為鍵值對。里面配置的每個自動配置類都會定義相關(guān) Bean 的實例配置，也會定義什么條件下自動配置和哪些 Bean 被實例化。

• 當(dāng) pom.xml 添加某 Starter 依賴組件的時候，就會自動觸發(fā)該依賴的默認(rèn)配置。

例如添加 spring-boot-starter-web 依賴后，啟動應(yīng)用會觸發(fā)容器自動配置類。容器自動配置類 ServletWebServerFactoryAutoConfiguration 的部分代碼如下：

package org.springframework.boot.autoconfigure.web.servlet;

@Configuration
@ConditionalOnClass({ServletRequest.class})
@ConditionalOnWebApplication(
    type = Type.SERVLET
)
@EnableConfigurationProperties({ServerProperties.class})
@Import({ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class})
public class ServletWebServerFactoryAutoConfiguration {... 省略
}

上面代碼中，@ConditionalOnClass 注解表示對應(yīng)的 ServletRequest 類在 ClassPath 目錄下面存在，并且 @ConditionalOnWebApplication 注解表示該應(yīng)用是 Servlet Web 應(yīng)用時，才會去啟動容器自動配置，并通過 ServerProperties 類默認(rèn)設(shè)置了端口為 8080。Type.SERVLET 枚舉代表 Servlet Web 應(yīng)用，Type.REACTIVE 枚舉代表響應(yīng)式 WebFlux 應(yīng)用。

自動配置，是一把雙刃劍。用好了就像天下武功唯快不破一樣。但要注意一些自動化配置造成的問題。常見的問題有：

• Spring Boot 工程添加某些 Starter 組件依賴，又不需要觸發(fā)組件自動配置

• Spring Boot 配置多個不同數(shù)據(jù)源配置時，使用 XML 配置多數(shù)據(jù)源，但其默認(rèn)數(shù)據(jù)源配置會觸發(fā)自動配置出現(xiàn)問題。

類似場景下，解決方式是通過 exclude 屬性指定并排除自動配置類，代碼如下：

@SpringBootApplication(exclude = {DataSourceAutoConfiguration.class})

也等價于配置 @EnableAutoConfiguration 注解，代碼如下：

@SpringBootApplication
@EnableAutoConfiguration(exclude = {DataSourceAutoConfiguration.class})

自動配置會最大的智能化，只有配置了 exclude 屬性時，Spring Boot 優(yōu)先初始化用戶定義的 Bean ，然后再進(jìn)行自動配置。

2.4.3 利用自動配置自定義 Starter 組件

當(dāng)公司需要共享或者開源 Spring Boot Starter 組件依賴包，就可以利用自動配置自定義 Starter 組件。一個完整的 Starter 組件包括以下兩點：

• 提供自動配置功能的自動配置模塊。

• 提供依賴關(guān)系管理功能的組件模塊，即封裝了組件所有功能，開箱即用。

實現(xiàn)自定義 Starter 組件，并不會將這兩點嚴(yán)格區(qū)分，可以將自動配置功能和依賴管理結(jié)合在一起實現(xiàn)。下面利用自動配置實現(xiàn)自定義 Starter 組件：spring-boot-starter-swagger 組件是用來快速生成 API 文檔，簡化原生使用 Swagger2 。

spring-boot-starter-swagger 組件為 Spring For All 社區(qū)（spring4all.com）開源項目，源代碼地址是 https://github.com/SpringForAll/spring-boot-starter-swagger。

什么是 Swagger2

Swagger2 是 API 最大的開發(fā)框架，基于 OpenAPI 規(guī)范（OAS），管理了 API 整個生命周期，即從 API 設(shè)計到文檔，從測試到部署。具體更多了解見其官網(wǎng)，https://swagger.io。

spring-boot-starter-swagger 組件依賴

創(chuàng)建一個新的 Spring Boot 工程，命名為 spring-boot-starter-swagger。在 pom.xml 配置相關(guān)

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${version.swagger}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${version.swagger}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>${version.swagger}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.12</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

配置中添加了 spring-boot-starter 組件依賴用于自動配置特性，springfox-swagger2 依賴是 Swagger2 框架。

Swagger2 屬性配置類 SwaggerProperties

新建名為 SwaggerProperties Swagger2 屬性配置類，包含了所有默認(rèn)屬性值。使用該組件時，可以在 application.properties 配置文件配置對應(yīng)屬性項，進(jìn)行覆蓋默認(rèn)配置。代碼如下：

import lombok.Data;import lombok.NoArgsConstructor;import org.springframework.boot.context.properties.ConfigurationProperties;import springfox.documentation.schema.ModelRef;import java.util.ArrayList;import java.util.LinkedHashMap;import java.util.List;import java.util.Map;

@Data
@ConfigurationProperties("swagger")public class SwaggerProperties {

    /**是否開啟swagger**/
    private Boolean enabled;    /**標(biāo)題**/
    private String title = "";    /**描述**/
    private String description = "";    /**版本**/
    private String version = "";    /**許可證**/
    private String license = "";    /**許可證URL**/
    private String licenseUrl = "";    /**服務(wù)條款URL**/
    private String termsOfServiceUrl = "";    private Contact contact = new Contact();    /**swagger會解析的包路徑**/
    private String basePackage = "";    /**swagger會解析的url規(guī)則**/
    private List<String> basePath = new ArrayList<>();    /**在basePath基礎(chǔ)上需要排除的url規(guī)則**/
    private List<String> excludePath = new ArrayList<>();    /**分組文檔**/
    private Map<String, DocketInfo> docket = new LinkedHashMap<>();    /**host信息**/
    private String host = "";    /**全局參數(shù)配置**/
    private List<GlobalOperationParameter> globalOperationParameters;

     ... 省略，具體代碼見 GitHub
}

用 @ConfigurationProperties(prefix = "swagger") 標(biāo)注在類上方是指定屬性的參數(shù)名稱為 swagger。會對應(yīng)匹配到配置文件中 “ swagger.* ” 結(jié)構(gòu)的屬性，例如，字段標(biāo)題 title 表示標(biāo)題，會匹配到 swagger.title 屬性值。

Swagger2 自動配置類 SwaggerAutoConfiguration

新建名為 SwaggerAutoConfiguration Swagger2 自動配置類，提供 Swagger2 依賴關(guān)系管理功能和自動配置功能。代碼如下：

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Import;import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;@Configuration@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)@Import({
        Swagger2DocumentationConfiguration.class,
        BeanValidatorPluginsConfiguration.class
})public class SwaggerAutoConfiguration implements BeanFactoryAware {    private BeanFactory beanFactory;    @Bean
    @ConditionalOnMissingBean
    public SwaggerProperties swaggerProperties() {        return new SwaggerProperties();
    }    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)    public List<Docket> createRestApi(SwaggerProperties swaggerProperties) {
        ... 省略，具體代碼見 GitHub
    }    @Override
    public void setBeanFactory(BeanFactory beanFactory) throws BeansException {        this.beanFactory = beanFactory;
    }
}

上面代碼實現(xiàn)流程如下：

1. @Configuration 注解標(biāo)注在類上方，表明該類為配置類。

2. @Import 注解引入 Swagger2 提供的配置類 Swagger2DocumentationConfiguration 和 Bean 數(shù)據(jù)驗證插件配置類 BeanValidatorPluginsConfiguration。

3. @ConditionalOnMissingBean 注解標(biāo)注了兩處方法，當(dāng) Bean 沒有被創(chuàng)建時會執(zhí)行被標(biāo)注的初始化方法。第一處被標(biāo)記方法是 swaggerProperties() ，用來實例化屬性配置類 SwaggerProperties;第二處被標(biāo)記方法是 createRestApi()， 用來實例化 Swagger2 API 映射的 Docket 列表對象。

4. @ConditionalOnProperty 注解標(biāo)注在 createRestApi() 方法，name 屬性會去檢查環(huán)境配置項 swagger.enabled 。默認(rèn)情況下，屬性存在且不是 false 的情況下，會觸發(fā)該初始化方法。matchIfMissing 屬性默認(rèn)值為 false ，這里設(shè)置為 true，表示如果環(huán)境配置項沒被設(shè)置，也會觸發(fā)。

Swagger2 啟動注解類 EnableSwagger2Doc

新建名為 EnableSwagger2Doc Swagger2 啟動注解類，用于開關(guān) spring-boot-starter-swagger 組件依賴。代碼如下：

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@Import({SwaggerAutoConfiguration.class})public @interface EnableSwagger2Doc {


}

上面代碼 @Import 注解引入 Swagger2 自動配置類 SwaggerAutoConfiguration。當(dāng)將該注解配置在應(yīng)用啟動類上方，即可開啟 Swagger2 自動配置及其功能。

使用 spring-boot-starter-swagger 組件依賴

上面簡單介紹了spring-boot-starter-swagger 組件的核心代碼實現(xiàn)，同樣使用方式也很簡單。在 chapter-2-spring-boot-config 工程的 Maven 配置中添加對應(yīng)的依賴配置，目前支持 1.5.0.RELEASE 以上版本，配置如下：

<!-- 自定義 swagger2 Starter 組件依賴 --><dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>spring-boot-starter-swagger</artifactId>
    <version>2.0</version></dependency>

另外，需要在 ConfigApplication 應(yīng)用啟動類上方配置啟動注解類 EnableSwagger2Doc，代碼如下：

import com.spring4all.swagger.EnableSwagger2Doc;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;@EnableSwagger2Doc // 開啟 Swagger@SpringBootApplicationpublic class ConfigApplication {    public static void main(String[] args) {
        SpringApplication.run(ConfigApplication.class, args);
    }
}

執(zhí)行 ConfigApplication 類啟動，在控制臺看到成功運行的輸出后，打開瀏覽器訪問 localhost:8080/swagger-ui.html 地址，可以看到自動生成的 Swagger API 文檔，如圖 2-7 所示：

圖 2-7 Swagger API 文檔

API org.springframework.boot.autoconfigure.EnableAutoConfiguration 注解參數(shù)

• exclude：
  Class 數(shù)組，排除特定的自動配置類。

• excludeName：
  字符串?dāng)?shù)組，排除特定名稱的自動配置類。

API org.springframework.boot.autoconfigure.ConditionalOnProperty 注解參數(shù)

• havingValue：
  字符串，屬性期望值是否匹配。

• matchIfMissing：
  布爾值，如果該屬性值未設(shè)置，則匹配。

• name：
  字符串?dāng)?shù)組，要測試的屬性名。

• prefix：
  字符串，屬性前綴名。

• value：
  字符串，功能同 name。

API org.springframework.boot.autoconfigure.ConditionalOnClass 注解參數(shù)

• name：
  字符串?dāng)?shù)組，類名必須存在。

• value：
  Class 數(shù)組，類必須存在。

API org.springframework.boot.autoconfigure.ConditionalOnMissingBean 注解參數(shù)

• annotation：
  注解 Class 數(shù)組，匹配注解裝飾的 Bean。

• ignored：
  Class 數(shù)組，匹配時，忽略該類型的 Bean。

• ignoredType：
  字符串?dāng)?shù)組，匹配時，忽略該類型名稱的 Bean。

• name：
  字符串?dāng)?shù)組，匹配要檢查的 Bean 名稱。

• search：
  SearchStrategy 對象，通過 SearchStrategy 來決定程序的上下文策略。

• type：
  字符串史胡族，匹配要檢查的 Bean 類型名稱。

• value：
  Class 數(shù)組，匹配要檢查的 Bean 類型。

API org.springframework.boot.autoconfigure.ConditionalOnWebApplication 注解參數(shù)

• type：
  ConditionalOnWebApplication.Type 對象，匹配對應(yīng)的 Web 應(yīng)用程序類型。

2.5 本章小結(jié)

本章從自定義屬性快速入門工程出發(fā)，介紹了兩種配置文件以及屬性的獲取方式，然后講解了外化配置的優(yōu)先級、屬性引用、隨機(jī)式使用和多環(huán)境配置，最后講解了自動配置的原理、核心注解以及利用自動配置實現(xiàn)了自定義 Starter 組件。