前言

在目前的Spring Boot框架中,不管是Spring Boot官方還是非官方,都提供了非常多的starter系列組件,助力開發(fā)者在企業(yè)應(yīng)用中的開發(fā),提升研發(fā)人員的工作效率,Spring Boot框架提出的約定大于配置的規(guī)則，確實幫助開發(fā)者簡化了以前Spring MVC時代的很多繁雜的配置。讓開發(fā)者用起來也是非常爽的。

盡管Spring Boot或者一些開源組件已經(jīng)幫助我們提供了非常多的starter組件，在滿足日常的開發(fā)中,已經(jīng)完全沒有問題了。但有時候因為需求的可變性，導(dǎo)致企業(yè)架構(gòu)也會隨著調(diào)整，那么在Spring Boot框架中，官方或開源的第三方starter肯定不能滿足企業(yè)內(nèi)部研發(fā)人員的要求，這時候就需要開發(fā)者自定義企業(yè)內(nèi)部的starter了。

企業(yè)或個人自定義Spring Boot的starter組件主要從哪些方面來入手呢，或者什么時候需要自定義starter組件？我個人認(rèn)為主要有以下幾個方面：

• 規(guī)范企業(yè)內(nèi)部編碼流程，統(tǒng)一各個技術(shù)中間件的代碼規(guī)范
• 減少不同類型中間件的使用成本，提升研發(fā)人員的研發(fā)工作效率
• 減少冗余代碼的使用，統(tǒng)一封裝，統(tǒng)一管理。
• 屏蔽中間件底層細節(jié)，暴露配置屬性及方法，減少學(xué)習(xí)使用成本
• 可能還有更多？

本篇博客結(jié)合自身的開發(fā)經(jīng)驗以及目前Spring Boot如何配置元數(shù)據(jù)的官方介紹文檔進行結(jié)合，進行綜合闡述。

Spring Boot官方元數(shù)據(jù)文檔地址：https://docs./spring-boot/docs/current/reference/html/appendix-configuration-metadata.html

封裝Spring Boot的starter范圍可以是一組規(guī)范的業(yè)務(wù)方法，也可以是通用的中間件底層。開發(fā)者通過封裝，一定程度上也能起到規(guī)范企業(yè)編碼的作用,同時也能組合復(fù)用公共業(yè)務(wù)邏輯。

那么我們在自定義Spring Boot框架的starter組件時,我們需要準(zhǔn)備什么呢？

我認(rèn)為主要包含以下幾個方面：

• 自定義starter的作用
• 命名規(guī)范
• 理解Maven或者Gradle依賴包管理的jar包引用傳遞機制
• 理解Spring Boot框架中基于Java代碼的Configuration配置
• 理解Spring Boot框架自動裝載的過程
• 學(xué)會利用Spring Boot提供的@Conditional系列條件注入充分發(fā)揮Spring Boot的優(yōu)點
• 學(xué)會如何配置自定義starter組件時對外的屬性注釋配置，可以參考官方文檔

自定義starter的作用

我們在自定義starter組件之前，開發(fā)者首先需要想清楚，這個starter組件能帶來什么，簡化開發(fā)？或者復(fù)用組件的封裝供其他同事使用，不寫重復(fù)代碼等等，這些都是需要思考清楚的。

自定義starter的場景很多，例如：

• 項目中發(fā)送短信對接了不同的云服務(wù)商，那么可以封裝一個短信的starter，屏蔽對接的細節(jié)，開發(fā)者只需要配置相應(yīng)的廠商配置信息就可以使用該服務(wù)商發(fā)送短信了
• OSS存儲對接不同的云服務(wù)商，例如阿里云、七牛云、騰訊云等等
• 企業(yè)內(nèi)部中間件封裝使用，簡化開發(fā)配置
• more...

根據(jù)筆者的經(jīng)驗,我認(rèn)為自定義的starter的作用無外乎以下幾個方面：

• 充分利用Spring的特性，容器/依賴注入特性，將核心的類組件注入容器中,方便開發(fā)者通過注入直接獲取拿來使用
• 通過屬性初始化中間件的流程，屏蔽具體的細節(jié)
• ....

starter命名規(guī)范

根據(jù)Spring Boot的官方要求，如果是開發(fā)者指定第三方的starter組件，那么命名規(guī)范是yourname-spring-boot-starter

拿Knife4j舉例說明如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用時請在maven中央倉庫搜索2.X最新版本號-->
    <version>2.0.8</version>
</dependency>

而Spring Boot官方維護發(fā)布的starter名稱規(guī)范則是：spring-boot-starter-name

例如我們引用最多的web組件，引用maven配置如下：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

jar包引用傳遞依賴機制

這是自定義封裝Spring Boot的starter的前提條件，Gradle筆者并未使用過，這里僅以Maven為例進行闡述說明！

通常我們在封裝一個SDK的jar包時，該jar包可能需要引用到第三方的jar包作為依賴包來輔助我們完成對該jar包的封裝，但是我們在引用的時候是有講究的。

針對Spring Boot的自定義starter說到底也是一個jar包，既然是jar包必然會用到第三方的jar(ps:全部都是你寫的代碼除外)，那么我們應(yīng)該如何明確在starter中的jar包的依賴傳遞，我認(rèn)為主要有以下方面：

• 作為第三方組件使用jar包時，明確第三方組件的版本
• 作為編譯期間的包，需要修改默認(rèn)的scope范圍值，僅僅在編譯期間生效，最終打包后引用不傳遞
• 自定義封裝starter必須引用Spring Boot官方提供的

在定義Spring Boot的第三方starter時，主要用到Maven管理jar包中的兩種依賴隔離方式(均可以使用)，分別如下：

• 明確使用<optional>true></optional>屬性來強指定jar包不傳遞
• 使用<scope>provided</scope>僅僅在編譯期間有效，jar包依賴性不傳遞

一般我們在自定義Spring Boot的starter組件時，都需要引用Spring Boot提供給開發(fā)者的依賴包，如下：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-autoconfigure</artifactId>
    <version>2.3.0.RELEASE</version>
    <scope>provided</scope>
</dependency>

當(dāng)然，你也可以使用optional模式，如下：

 <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-autoconfigure</artifactId>
     <version>2.3.0.RELEASE</version>
     <optional>true</optional>
</dependency>

Java代碼方式的Configuration

基于Java編碼的方式配置Spring的Bean已經(jīng)成了目前的主流，這主要也是得益于Spring Boot框架的流行！

在Spring MVC框架流行的時候，開發(fā)人員一般都是通過配置XML文件來注入實體Bean的

而通過java編碼的方式注入Bean的前提是@Configuration注解加在一個配置Java實體類上即可，示例如下：

@Configuration
public class MyAutoConfiguration{
    
    //do others...
    
}

Spring Boot框架的自動裝載

對于Spring Boot框架自定義的starter組件來說，提供的使用方式而言，我認(rèn)為目前主要有3種方式，這個主要看封裝starter組件的作者如何開放來定

手工@Import導(dǎo)入

第一種情況：使用者使用@Import注解將封裝的starter組件的Java編碼Configuration配置文件進行導(dǎo)入

假設(shè)目前封裝的一個簡單的Configuration配置如下：

@Configuration
public class DemoAuthConfiguration {

    @Bean
    public DemoClient demoClient(){
        return new DemoClient();
    }

}

開發(fā)者通過DemoAutoConfiguration.java向Spring的容器中注入了一個DemoClient的實體Bean,由于隸屬于不同的package包路徑，自定義的starter組件包路徑是：com.demo.spring

而開發(fā)者的項目主目錄包路徑是：com.test,所以Spring Boot框架默認(rèn)是不會加載該配置的，此時，如果開發(fā)者要在Spring的容器中獲取DemoClient的實體Bean應(yīng)該怎么辦呢？使用者應(yīng)該在自己的主配置中使用@Import注解將該配置導(dǎo)入進來交給Spring容器初始化時進行創(chuàng)建，示例如下：

@Import(DemoAutoConfiguration.class)
@SpringBootApplication
public class DemoDemoApplication {
    
    public static void main(String[] args){
        SpringApplication.run(DemoDemoApplication.class, args);
    }
}

提供便于記憶的注解@EnableXXX

@Enablexxx系列注解相信開發(fā)者并不陌生，比如我們要使用Spring Boot的定時任務(wù)功能，我們會在啟動入口引入@EnableScheduling注解，我們使用Springfox的Swagger組件，我們會引入@EnableSwagger2注解

其實這種方式只是為了讓開發(fā)者能夠更加方便的記憶，一個@Enablexxx系列注解，其所代表的功能特點也基本符合該starter組件，是在上面手工通過@Import注解的升級版本。

畢竟Enable單詞所代表的含義是啟用,這有利于開發(fā)者記憶

繼續(xù)通過上面第一種的示例進行改在，此時，我們可以提供@EnableDemoClient注解，代碼示例如下：

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Import(DemoAutoConfiguration.class)
public @interface EnableDemoClient {

}

大家應(yīng)該也看到了，我們在該@EnableDemoClient注解中，使用了@Import注解的方式導(dǎo)入了DemoAutoConfiguration配置

此時，我們在項目中可以使用@EnableDemoClient注解了，代碼示例如下：

@EnableDemoClient
@SpringBootApplication
public class DemoDemoApplication {
    
    public static void main(String[] args){
        SpringApplication.run(DemoDemoApplication.class, args);
    }
}

當(dāng)然，@Enable這種注解作用不僅僅局限于此，還可以在該注解上定義外部的配置屬性，通過配置該注解的方式達到最終初始化的目的。

自動裝載

自動裝載是Spring Boot的一重大特點，開發(fā)者通過配置文件的方式即可默認(rèn)加載第三方的starter配置，非常的方便，是上面兩種方式的升級版

在之前的基礎(chǔ)上，如果開發(fā)者希望在Maven的pom.xml工程中引入了該組件，就可以使用DemoClient類，那么此時我們應(yīng)該怎么做呢？

我們需要在工程中創(chuàng)建spring.factories文件，文件目錄：src/resources/META-INF/spring.factories

在spring.factories文件中,配置開發(fā)者自定義的configuration類，如下：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.demo.spring.DemoAutoConfiguration

配置好后，此時再打包我們自定義的starter組件，Spring Boot框架默認(rèn)會自動裝載該配置類，我們在業(yè)務(wù)代碼中也就可以直接使用了

我們可以在SpringApplication.java源碼中看到Spring Boot初始化獲取該類列表的過程

private <T> Collection<T> getSpringFactoriesInstances(Class<T> type, Class<?>[] parameterTypes, Object... args) {
ClassLoader classLoader = getClassLoader();
// Use names and ensure unique to protect against duplicates
Set<String> names = new LinkedHashSet<>(SpringFactoriesLoader.loadFactoryNames(type, classLoader));
List<T> instances = createSpringFactoriesInstances(type, parameterTypes, classLoader, args, names);
AnnotationAwareOrderComparator.sort(instances);
return instances;
}

上述方法中的SpringFactoriesLoader.loadFactoryNames方法如下：

public static List<String> loadFactoryNames(Class<?> factoryType, @Nullable ClassLoader classLoader) {
String factoryTypeName = factoryType.getName();
return loadSpringFactories(classLoader).getOrDefault(factoryTypeName, Collections.emptyList());
}

private static Map<String, List<String>> loadSpringFactories(@Nullable ClassLoader classLoader) {
    MultiValueMap<String, String> result = cache.get(classLoader);
    if (result != null) {
        return result;
    }

    try {
        //加載META-INF/spring.factories配置，創(chuàng)建MultiValueMap集合放到該集合中
        Enumeration<URL> urls = (classLoader != null ?
                                 classLoader.getResources(FACTORIES_RESOURCE_LOCATION) :
                                 ClassLoader.getSystemResources(FACTORIES_RESOURCE_LOCATION));
        result = new LinkedMultiValueMap<>();
        while (urls.hasMoreElements()) {
            URL url = urls.nextElement();
            UrlResource resource = new UrlResource(url);
            Properties properties = PropertiesLoaderUtils.loadProperties(resource);
            for (Map.Entry<?, ?> entry : properties.entrySet()) {
                String factoryTypeName = ((String) entry.getKey()).trim();
                for (String factoryImplementationName : StringUtils.commaDelimitedListToStringArray((String) entry.getValue())) {
                    result.add(factoryTypeName, factoryImplementationName.trim());
                }
            }
        }
        cache.put(classLoader, result);
        return result;
    }
    catch (IOException ex) {
        throw new IllegalArgumentException("Unable to load factories from location [" +
                                           FACTORIES_RESOURCE_LOCATION + "]", ex);
    }
}

充分利用Spring Boot提供的@Conditional條件注入組件

通過上面的文章介紹，為Spring Boot框架制定一個簡單的starter組件相信已經(jīng)不在話下。但是，這才僅僅開始而已。

在上面介紹的自動裝載過程中，開發(fā)者是否會存在疑問？

當(dāng)我們在pom.xml引入我們自定義的starter組件后,Spring Boot框架默認(rèn)會將該組件直接注入到Spring的容器中，這種方式雖然在使用上并沒有什么問題，但當(dāng)我們封裝給第三方使用時,這種方式往往會存在沖突，假設(shè)開發(fā)者自定義的starter組件中包含了向容器中注入Filter等過濾器,那么該過濾器直接生效,會全范圍影響整個應(yīng)用程序.這在實際開發(fā)中是不允許的！

那么應(yīng)該怎么辦呢?此時，我們就需要充分利用Spring Boot框架為開發(fā)者提供的@Conditional系列條件注入了

條件注入顧名思義,就是只有使用者滿足了組件規(guī)定的條件時，組件才會向Spring容器中進行注入Bean或者初始化的操作.這種方式也是將選擇權(quán)直接交給使用者進行選擇，減少非必要的組件沖突，是在Spring Boot自定義starter組件中必不可少的一環(huán)。

條件注入通常也配合屬性類一起來進行使用,提供配置屬性選項也是方便使用者在Spring Boot的配置文件application.yml或者application.properties進行配置開啟操作，例如我們常見的配置操作如下：

server:
  port: 18568
  servlet:
    context-path: /test

為Spring Boot的程序指定啟動端口號和context-path屬性.

我們繼續(xù)以上面示例中的DemoClient為例進行闡述

假設(shè)我們的DemoClient是對接外部API接口的封裝組件，該組件規(guī)定訪問外部API時需要提供appid和secret,根據(jù)appid及secret獲取token，最后根據(jù)token才能調(diào)用API獲取接口數(shù)據(jù)，

那么,此時，我們的DemoClient的部分模擬接口代碼可能會如下面示例：

public class DemoClient {
    private final String appid;
    private final String secret;

    public DemoClient(String appid, String secret) {
        this.appid = appid;
        this.secret = secret;
    }

    /**
     * 獲取資源
     * @return
     */
    public String listResources(){
        //獲取token
        String token=getToken();
        //根據(jù)Token請求數(shù)據(jù)
        return UUID.randomUUID().toString();
    }

    private String getToken() {
        //根據(jù)appid & secret獲取第三方API接口token
        return null;
    }
}

在上面的代碼示例中，如果開發(fā)者要使用DemoClient的方法調(diào)用第三方的接口資源，那么需要傳遞appid及secret參數(shù)才能構(gòu)造實體類，又考慮到我們需要利用Spring Boot的條件注入，只有開發(fā)者配置了開啟操作，才能在Spring容器中使用DemoClient的方法。

那么此時，我們可以給該starter組件抽象一個DemoProperties的外部配置類來交給使用者在配置文件中進行配置開啟操作，代碼示例如下：

@ConfigurationProperties(prefix = "demo")
public class DemoProperties {
    /**
     * 是否啟用
     */
    private boolean enable=false;
    
    private String appid;
    private String secret;
    
    //getter and setter...
}

在配置類屬性中，我們使用到了@ConfigurationProperties注解，并配置了prefix前綴參數(shù),配置前綴也是自定義starter組件中所必須的，這約束了命名空間。一般是結(jié)合自身的業(yè)務(wù)以及starter組件所代表的功能含義進行命名prefix,有助于開發(fā)使用者記憶。

此時，我們的DemoAutoConfiguration.java配置類進行了調(diào)整，代碼如下：

@Configuration
@EnableConfigurationProperties(DemoProperties.class)
@ConditionalOnProperty(name = "demo.enable",havingValue = "true")
public class DemoAutoConfiguration {

    @Bean
    public DemoClient demoClient(DemoProperties demoProperties){
        return new DemoClient(demoProperties.getAppid(), demoProperties.getSecret());
    }

}

和上面的配置類進行比較不難發(fā)現(xiàn),此處我們又多用了兩個注解：

• @EnableConfigurationProperties:該注解是我們自定義指定Proerpty實體類時，必須啟用的注解，和實體類中的@ConfigurationProperties注解配合一起使用
• @ConditionalOnProperty:Spring Boot框架中條件注入的一種，代碼根據(jù)配置的屬性進行條件判斷注入，此處我們配置了只有當(dāng)demo.enable=true時，DemoAutoConfiguration配置類才會加載，向Spring容器中注入DemoClient的實體Bean

當(dāng)自定義starter組件封裝到這一步時，基本已經(jīng)快完結(jié)了，開發(fā)者可以通過在Spring Boot的配置文件中進行配置，來開啟是否使用DemoClient組件

demo:
  # 通過配置該屬性的true 或者false ，來開啟組件的使用
  enable: true
  appid: xxx
  secret: xxxx

屬性元數(shù)據(jù)配置

通過上面的配置，我們已經(jīng)能夠自定義一個Spring Boot框架的starter組件了，但是對于使用者來說，封裝該starter組件的開發(fā)者還尚有最后一步需要完成，那就是給屬性類提供元數(shù)據(jù)注釋，提供元數(shù)據(jù)注釋也是為了讓使用者在配置application.yml屬性時，通過IDEA等編輯器能夠給出提示，這對使用者而已是大有裨益的，因為每一個屬性都會有相應(yīng)的注釋供開發(fā)者進行參考。例如Knife4j組件提供的元數(shù)據(jù)注釋如下圖：

那么我們在制定starter組件時，如何給屬性類提供元數(shù)據(jù)注釋呢？目前主要有兩種方式：

引入spring-boot-configuration-processor自動注釋

我們可以在自定義是starter組件中引入該組件，依賴如下：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <version>2.3.0.RELEASE</version>
    <optional>true</optional>
</dependency>

引入該組件后，此時，我們只需要在我們的Java屬性類中給每一個屬性使用標(biāo)準(zhǔn)的javadoc進行注釋即可，如下：

@ConfigurationProperties(prefix = "demo")
public class DemoProperties {
    /**
     * 是否啟用
     */
    private boolean enable=false;

    /**
     * 第三方appid
     */
    private String appid;
    /**
     * 第三方secret
     */
    private String secret;
    
    //getter and setter...
}

最終在使用時，就會出現(xiàn)提示，如下圖：

這種方式如果屬性類不是太多的情況下，開發(fā)者可以使用，很方便

手工編寫spring-configuration-meatadata.json文件

spring-boot-configuration-processor組件最終在打包生成starter的jar包時，也是幫助我們自動生成了spring-configuration-metadata.json文件,該文件和上面提到的spring.factories是同級目錄

手工編寫spring-configuration-metadata.json也是我推薦的方式，因為不僅僅是每個屬性的注釋，有時候我們還可以用更多的屬性配置以便使用者使用。

結(jié)果如下：

{
  "groups": [
    {
      "name": "demo",
      "type": "com.demo.spring.DemoProperties",
      "sourceType": "com.demo.spring.DemoProperties"
    }
  ],
  "properties": [
    {
      "name": "demo.appid",
      "type": "java.lang.String",
      "description": "第三方appid",
      "sourceType": "com.demo.spring.DemoProperties"
    },
    {
      "name": "demo.enable",
      "type": "java.lang.Boolean",
      "description": "是否啟用",
      "sourceType": "com.demo.spring.DemoProperties",
      "defaultValue": false
    },
    {
      "name": "demo.secret",
      "type": "java.lang.String",
      "description": "第三方secret",
      "sourceType": "com.demo.spring.DemoProperties"
    }
  ],
  "hints": []
}

我們主要使用到的屬性有3個：groups、properties、hints

groups

字面意思分組，按我的理解即當(dāng)我們使用的實體時，配置的prefix即代表該group，例如上面我們?yōu)?code>DemoProperties配置了prefix的前綴是demo,那么分組這里可以設(shè)置為demo,當(dāng)然如果DemoProperties類中包含的屬性是一個第三方類，假設(shè)如下：

public class DemoProperties{
    
    private OtherProperties other;
}

那么我們可以在groups屬性中配置一個名為demo.other的分組名稱

其包含的屬性如下：

properties

顧名思義，就是我們實體類每個屬性的配置，有多少屬性需要添加元數(shù)據(jù)注釋說明，就需要在該數(shù)組下全部添加，需要注意的是配置name時需要配置全路徑，例如：demo.enable等

其包含的屬性如下：

過時選項Deprecation包含以下幾個屬性：

hints

針對該屬性，我的理解是類似于Java中的枚舉，只不過是給每一個屬性的值配置一個說明，方便使用者在配置的時候能夠按照規(guī)定的值進行正確配置

例如上面我們的示例：demo.enable屬性，該屬性類型為Boolean類型，要配置也只有兩種值(true或者false)

那么我們可以給該值配置一個hints進行說明，示例如下：

"hints": [
    {
      "name": "demo.enable",
      "values":[
        {
          "value": true,
          "description": "啟用DemoClient組件"
        },
        {
          "value": false,
          "description": "禁用DemoClient組件"
        }
      ]
    }
]

當(dāng)我們進行這樣的配置后，最終使用者在使用時就會出現(xiàn)如下圖所示的提示:

這對使用該starter組件的開發(fā)者來說，每個屬性都有相應(yīng)的說明，是非常方便的

hints主要包含的屬性如下：

ValueHint是對其提供的值進行注釋說明，其屬性如下:

ValueProvider包含屬性：

在上面我提過，hints類似于枚舉，這映射到ValueHint屬性，當(dāng)我們配置了hints屬性中的values時而不提供providers屬性時，如果開發(fā)者最終在使用時，只能配置ValueHint中定義的值，否則配置其他值時會在IDEA編輯器中就會爆紅出錯

還是以上面的示例，假設(shè)我們給appid配置hint值，如下：

"hints": [
    {
      "name": "demo.appid",
      "values":[
        {
          "value": "test1",
          "description": "測試appid1"
        },
        {
          "value": "test2",
          "description": "測試appid2"
        }
      ]
    }
]

那么我們在使用組件時，在application.yml配置文件中配置其他值時，idea會提示錯誤，如下圖：

此時，providers屬性就可以排上用場了

修改上面的配置如下：

"hints": [
    {
      "name": "demo.appid",
      "values":[
        {
          "value": "test1",
          "description": "測試appid1"
        },
        {
          "value": "test2",
          "description": "測試appid2"
        }
      ],
      "providers":[
        {
          "name":"any"
        }
      ]
    }
]

我們可以配置providers為any,這樣說明開發(fā)者除了可以配置test1、test2外，當(dāng)配置其他值時，也是允許的

針對providers中的name屬性，主要有以下類別供選擇：

附錄

• Spring Boot框架中如何優(yōu)雅的注入實體Bean
• Spring Boot Configuration Metadata Document