自定义 Spring Boot Starter

源码：https://github.com/pingfangushi/spring-learning/tree/master/spring-boot-starter

前言

  正值疫情爆发期，村子封了，路也封了，不用拜访亲戚朋友了，在家也不能老刷手机看电视啊，老老实实在家呆着不添乱为国家做贡献，静静心，补充补充知识，写写文章，帮助大家。

  做Java开发的现在那个不知道Spring Boot ，那个还没用过，比起传统Spring项目的一大堆配置，Spring Boot更简洁、灵活，提供了一系列 starters 简化开发， 开发人员只需要添加需要的starter，Spring Boot可以自动进行配置 ，但实际开发中我们需要开发自己的starter，来简化项目开发配置。开发自定义starter 首先就要了解自动配置的一些知识。

正文

了解Bean的自动配置

  首先从源码入手，可以通过浏览spring-boot-autoconfigure的源代码，查看带有@Configuration标注类并查看META-INF/spring.factories文件）。
  自动配置是通过标注有@Configuration注解的类来实现的。其他@Conditional*注解用于约束何时应应用自动配置。Spring Boot提供了一系列条件注解来灵活的根据条件来进行自动配置，如下图源码所示。

常用条件注解

Class 条件注解

@ConditionalOnClass 只有当指定的类在类路径相匹配
@ConditionalOnMissingClass 只有当指定的类不在类路径相匹配

Bean 条件注解

@ConditionalOnBean 当需要的Bean存在时，配置才会生效
@ConditionalOnMissingBean 当需要的Bean不存在时，配置才会生效

Property 条件注解

@ConditionalOnProperty 基于Spring的环境属性配置包括在内。使用prefix和name属性来指定应检查的属性。默认情况下，匹配任何存在且不等于false的属性。您还可以使用havingValue和matchIfMissing属性创建更高级的检查。

Resource 条件注解

@ConditionalOnResource 允许仅在存在特定资源时才包含配置。可以使用常见的Spring约定来指定资源。

Web 应用条件注解

@ConditionalOnWebApplication 匹配当应用程序是一个Web应用程序。 默认情况下，所有的Web应用将匹配，但它可以通过type()属性缩小范围。
@ConditionalOnNotWebApplication 只有当应用程序上下文不是一个Web应用程序才匹配

SpEL 表达式条件注解

@ConditionalOnExpression 允许根据SpEL表达式的结果包含配置

除了上述所说的比较常见的，SpringBoot 还提供了一些别的条件注解，有兴趣大家可直接看源码

定位自动配置

  Spring Boot在启动时检查发布的jar中是否存在META-INF/spring.factories文件。该文件应在EnableAutoConfiguration键下列出的配置类，Spring Boot启动时扫描并进行自动配置，如以下示例所示：

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.pingfangushi.learning.ExampleAutoConfigure

  如果需要按特定顺序应用配置，则可以使用@AutoConfigureAfter或@AutoConfigureBefore注释。例如，如果您提供特定于Web的配置，则可能需要在应用类WebMvcAutoConfiguration之后，则应该使用@AutoConfigureAfter(value = WebMvcAutoConfiguration.class)进行标注。
  如果想设置自动配置类加载顺序，可使用@AutoConfigureOrder进行处理，此注解只在外部jar中有效，当前项目内无效。

创建自定义Starter

  讲解完AutoConfiguration相关知识，现在我们开始来进行Starter的讲解。完整Spring Boot Starter 程序可能需要包含以下组件：

• 包含自动配置代码的autoconfigurer模块。
• 为autoconfigure模块提供依赖项的starter模块，以及通用的库和任何附加依赖项。简单地说，添加starter应该可以提供开始使用该库所需的一切。

如果不需要将自动配置代码和依赖项管理分离开来，则可以将它们合并到一个模块中。

  打开IDEA，新建一个Maven项目，这里就涉及到比较重要的一个点，命名，开发者应该提供正确的名称空间，即使使用不同的Maven groupId，也不要用Spring Boot启动模块名。因为在将来可能会提供官方支持。

官方规则如下：
xxx-spring-boot-autoconfigure
xxx-spring-boot-starter
将xxx替代为你的项目名

  假设我们正在为example创建一个启动程序，并将自动配置模块命名为example-spring-boot-autoconfigure，将启动程序命名为example-spring-boot-starter。我们也可以使用一个模块来合并这两个模块，将它命名为example-spring-boot-starter即可。

编写程序

  现在开始进行撸码了，写个简单的吧，实现简单的ID和IP地址的自动配置，并在测试项目获取配置内容。本文代码已经上传 https://github.com/pingfangushi/spring-learning/tree/master/spring-boot-starter ，大家可clone下来根据文章进行对照查看学习，首先我用IDEA建立了一个普通的SpringBoot 项目，不需要选择安装任何依赖，然后开始建立三个子项目、autoconfigure、starter、和test 项目，其中autoconfigure 和 starter 只需要创建普通maven项目即可，test 建立一个SpringBoot项目，为了方便测试。下面开始分别介绍每个模块。

编写 autoconfigure 模块

  autoconfigure 模块来编写项目自动配置，下面为autoconfigure模块的结构图。ExampleAutoConfigure.java 为自动配置类，ExampleProperties.java为配置属性，ConfigureInfo.java为配置信息类，ExampleService.java为相关业务接口，ExampleServiceImpl.java为业务逻辑实现类。

├── example-spring-boot-autoconfigure
│   ├── pom.xml
│   └── src
│       ├── main
│       │   ├── java
│       │   │   └── com
│       │   │       └── pingfangushi
│       │   │           └── learning
│       │   │               ├── ExampleAutoConfigure.java
│       │   │               ├── ExampleProperties.java
│       │   │               ├── ConfigureInfo.java
│       │   │               ├── ExampleService.java
│       │   │               └── ExampleServiceImpl.java
│       │   └── resources
│       │       └── META-INF
│       │           └── spring.factories
│       └── test
│           └── java

添加依赖

...
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-autoconfigure</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>
        <!--将被@ConfigurationProperties注解的类的属性注入到元数据-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
            <scope>provided</scope>
        </dependency>
    </dependencies>
...

编写ConfigureInfo.java 、ExampleService.java、 ExampleServiceImpl.java

ConfigureInfo 配置信息类，用于封装配置信息。

package com.pingfangushi.learning;

import lombok.Builder;

import java.io.Serializable;

/**
 * 配置信息
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/2/18 22:09
 */
@Data
@Builder
public class ConfigureInfo implements Serializable {
    /**
     * ID
     */
    private String id;
    /**
     * IP地址
     */
    private String ip;
}

ExampleService 示例业务接口，这里我们定义了一个configInfo接口，用于获取配置信息。

package com.pingfangushi.learning;

/**
 * ExampleService
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/1/29 18:22
 */
public interface ExampleService {
    /**
     * 获取配置信息
     *
     * @return {@link ConfigureInfo}
     */
    ConfigureInfo configInfo();
}

ExampleServiceImpl 业务逻辑实现类，用于实现功能。

package com.pingfangushi.learning;

/**
 * ExampleServiceImpl
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/1/29 18:22
 */
public class ExampleServiceImpl implements ExampleService {
    /**
     * ID
     */
    private String id;
    /**
     * ip
     */
    private String ip;

    /**
     * 构造函数
     *
     * @param id ID
     * @param ip IP
     */
    public ExampleServiceImpl(String id, String ip) {
        this.id = id;
        this.ip = ip;
    }

    /**
     * 获取配置信息
     *
     * @return {@link ConfigureInfo}
     */
    @Override
    public ConfigureInfo configInfo() {
        return ConfigureInfo.builder()
                .id(this.id)
                .ip(this.ip).build();
    }
}

编写ExampleProperties.java

  @ConfigurationProperties使开发人员可以轻松地将整个文件.properties和yml文件映射到一个对象中。编写Properties，应使用唯一的名称空间。不要使用Spring Boot的名称空间（如server，management，spring，等）。所以应在所有配置键前面加上自己的名称空间。如我们这里使用的是com.pingfangushi.example作为配置名称空间。

package com.pingfangushi.learning;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;

import static com.pingfangushi.learning.ExampleProperties.DEFAULT_PREFIX;

/**
 * 配置属性项
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/1/29 17:47
 */
@Data
@ConfigurationProperties(value = DEFAULT_PREFIX)
public class ExampleProperties {
    /**
     * PREFIX
     */
    public static final String DEFAULT_PREFIX = "com.pingfangushi.example";
    /**
     * ID标识
     */
    private String id;

    /**
     * IP地址
     */
    private String ip;

}

编写ExampleAutoConfigure.java

  编写带有@Configuration的配置类，并添加@EnableConfigurationProperties注解，@EnableConfigurationProperties作用是为了使@ConfigurationProperties 注解的类生效。

package com.pingfangushi.learning;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * 示例自动配置类
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/1/29 17:55
 */
@Configuration
@EnableConfigurationProperties(value = ExampleProperties.class)
public class ExampleAutoConfigure {

    private Logger logger = LoggerFactory.getLogger(ExampleAutoConfigure.class);

    /**
     * 配置ExampleService
     *
     * @return {@link ExampleService}
     */
    @Bean
    @ConditionalOnMissingBean
    public ExampleService exampleService() {
        logger.info("Config ExampleService Start...");
        ExampleServiceImpl service = new ExampleServiceImpl(properties.getId(), properties.getIp());
        logger.info("Config ExampleService End.");
        return service;
    }

    /**
     * 注入ExampleProperties
     */
    private final ExampleProperties properties;

    public ExampleAutoConfigure(ExampleProperties properties) {
        this.properties = properties;
    }
}

编写spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.pingfangushi.learning.ExampleAutoConfigure

自动配置只能以这种方式加载。确保在特定的程序包空间中定义它们，并且决不要将它们作为组件扫描的目标。

IDE 提示

在使用官方starter的时候，我们可以发现IDE可以进行提示，原因是我们自己封装的starter如何实现呢？

  需要在pom文件中添加 spring-boot-configuration-processor 依赖，刚才我们已经在创建项目的时候添加过了，讲一下原理，Spring Boot使用一个注释处理器来收集元数据文件（META-INF/Spring autoconfigure metadata.properties）中自动配置的条件。如果该文件存在，它将用于急切地筛选不匹配的自动配置，这将提高启动时间。

编写 starter 模块

  starter是一个空jar。它的唯一目的是提供使用库所必需的依赖项。删除掉src文件夹，在pom文件中加入example-spring-boot-autoconfigure依赖。

...
<dependencies>
        <dependency>
            <groupId>com.pingfangushi.learning</groupId>
            <artifactId>example-spring-boot-autoconfigure</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
...

编写 test 模块

  test 模块就是普通的Spring Boot项目，在创建项目的时勾选添加spring-boot-starter-web、lombok、spring-boot-starter-tomcat 依赖即可。下面为目录结构。除ExampleController.java和Result.java外，都是创建项目是自动生成的。Result.java为通用返回类，ExampleController.java为测试Controller。

├── example-spring-boot-test
│   ├── pom.xml
│   └── src
│       ├── main
│       │   ├── java
│       │   │   └── com
│       │   │       └── pingfangushi
│       │   │           └── example
│       │   │               ├── ExampleController.java
│       │   │               ├── ExampleSpringBootTestApplication.java
│       │   │               ├── Result.java
│       │   │               └── ServletInitializer.java
│       │   └── resources
│       │       ├── application.properties
│       │       ├── static
│       │       └── templates
│       └── test
│           └── java
│               └── com
│                   └── pingfangushi
│                       └── example
│                           └── ExampleSpringBootTestApplicationTests.java

添加example-spring-boot-starter依赖

在项目的pom.xml中加入我们的自定义starter依赖

<dependency>
      <groupId>com.pingfangushi.learning</groupId>
      <artifactId>example-spring-boot-starter</artifactId>
      <version>1.0-SNAPSHOT</version>
 </dependency>

配置application.properties

# ip
com.pingfangushi.example.ip=192.168.0.1
# ID
com.pingfangushi.example.id=16c21a6b

编写 Result.java

Result 通用返回类，在这里我们使用了lombok的@Builder注解实现了一个构建这模式类。

package com.pingfangushi.example;

import lombok.Builder;

/**
 * Result 通用返回工具类
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/1/29 19:03
 */
@Data
@Builder
public class Result {
    /**
     * 成功CODE
     */
    public static final String SUCCESS_CODE = "0";
    /**
     * 成功MSG
     */
    public static final String SUCCESS_MSG = "SUCCESS!";
    /**
     * code
     */
    private String code;
    /**
     * msg
     */
    private String msg;
    /**
     * data
     */
    private Object data;
}

编写 ExampleController.java

package com.pingfangushi.example;

import com.pingfangushi.learning.ConfigureInfo;
import com.pingfangushi.learning.ExampleService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import static com.pingfangushi.example.Result.SUCCESS_CODE;
import static com.pingfangushi.example.Result.SUCCESS_MSG;

/**
 * 示例项目测试控制器
 *
 * @author SanLi
 * Created by qinggang.zuo@gmail.com / 2689170096@qq.com on 2020/1/29 19:02
 */
@RestController
@RequestMapping(value = "/example")
public class ExampleController {

    public ExampleController(ExampleService exampleService) {
        this.exampleService = exampleService;
    }

    /**
     * 获取配置的IP 和ID
     *
     * @return {@link Result}
     */
    @GetMapping(value = "config")
    public Result configInfo() {
        // 获取配置信息
        ConfigureInfo configureInfo = exampleService.configInfo();
        // 封装返回
        return Result.builder()
                .code(SUCCESS_CODE)
                .msg(SUCCESS_MSG)
                .data(configureInfo).build();
    }

    /**
     * 注入 ExampleService
     */
    private final ExampleService exampleService;
}

启动测试

打开浏览器，输入 http://127.0.0.1:8080/example/config ，你将会看到我们配置的内容。

参考

https://docs.spring.io/spring-boot/docs/2.2.4.RELEASE/reference/html/spring-boot-features.html#boot-features-developing-auto-configuration