自定义 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启动时扫描并进行自动配置,如以下示例所示:

1
2
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 项目,其中autoconfigure starter 只需要创建普通maven项目即可,test 建立一个SpringBoot项目,为了方便测试。下面开始分别介绍每个模块。

编写 autoconfigure 模块

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
├── 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
添加依赖
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
...
<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 配置信息类,用于封装配置信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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接口,用于获取配置信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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 业务逻辑实现类,用于实现功能。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
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作为配置名称空间。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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 注解的类生效。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
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
1
2
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依赖。

1
2
3
4
5
6
7
8
9
...
<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。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
├── 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依赖

1
2
3
4
5
<dependency>
<groupId>com.pingfangushi.learning</groupId>
<artifactId>example-spring-boot-starter</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
配置application.properties
1
2
3
4
# ip
com.pingfangushi.example.ip=192.168.0.1
# ID
com.pingfangushi.example.id=16c21a6b
编写 Result.java

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
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

自定义 Spring Boot Starter

http://pingfangushi.com/posts/334/

作者

SanLi

发布于

2020-02-23

更新于

2020-12-01

许可协议