自定义 Spring Boot Starter

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

前言

  正值疫情爆发期,村子封了,路也封了,不用拜访亲戚朋友了,在家也不能老刷手机看电视啊,老老实实在家呆着不添乱为国家做贡献,静静心,补充补充知识,写写文章,帮助大家。
  做Java开发的现在那个不知道Spring Boot ,那个还没用过,比起传统Spring项目的一大堆配置,Spring Boot更简洁、灵活,提供了一系列 starters 简化开发, 开发人员只需要添加需要的starterSpring 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的环境属性配置包括在内。使用prefixname属性来指定应检查的属性。默认情况下,匹配任何存在且不等于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项目,不需要选择安装任何依赖,然后开始建立三个子项目、autoconfigurestarter、和test 项目,其中autoconfigurestarter 只需要创建普通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使开发人员可以轻松地将整个文件.propertiesyml文件映射到一个对象中。编写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如何实现呢?

IDE提示

  需要在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-weblombokspring-boot-starter-tomcat 依赖即可。下面为目录结构。除ExampleController.javaResult.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 ,你将会看到我们配置的内容。

config info

参考

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

推荐阅读更多精彩内容