今天以实用角度切入,来示范自定义 springboot starter 在项目开发过程中的实际应用。

SpringBoot 相对于 Spring 最大的优点就是提供了相当数量的 starter,只需引入 starter 进行极少量的配置就可使用相应的功能,有效减少 Spring 冗余复杂的配置文件。但日常工作当中,我们自己也会封装一些比较通用的代码 jar 包,引入到新的项目中很难避免添加相应的配置,比如 Bean 的声明。借鉴 SpringBoot 官方做法,我们自己也可以自定义所需要的 Starter。

今天以统一项目日期格式化功能为例,从头到尾地介绍如何自定义一个 Starter。

引入 Starter 初衷

对于一个需要提供 HTTP 接口的服务来说,日期的格式化为友好的格式返回是一个无法避免的问题。实体类结构如下:

1
2
3
4
5
6
7
@Data
public class Example {
private LocalDateTime localDateTime;
private LocalDate localDate;
private Date date;
private LocalTime localTime;
}

做法有很多,第一种是比如数据库实体类字段使用的是 Date 类型,LocalDateTime 类型,返回给前端的 VO 中字段则使用 Long 类型或者 String 类型,在实体类进行转换的过程中转换时间类型。

第二种方式是可以使用@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")注解的方式,不过这种方式就需要在所有的 VO 上添加这个注解。

第三种方式是还可以在 application.yml 中配置如下

1
2
3
spring:
jackson:
date-format: yyyy-MM-dd HH:mm:ss

前两种方式都比较 low,暂且不谈,第三种方式可以实现统一全局 Date 类型的格式化,但是随着 Java8 的广泛应用,Java8 新的 Time 相关类使用更多,而第三种方式无法实现 LocalDateTime 等格式化。

访问接口 http://127.0.0.1:8083/learning-example/test

未添加配置前返回:

1
2
3
4
5
6
7
8
9
{
"data": {
"localDateTime": "2020-05-14T10:15:13.311",
"localDate": "2020-05-14",
"date": "2020-05-14T02:15:13.306+0000",
"localTime": "10:15:13.311"
},
"success": true
}

添加配置后返回:

1
2
3
4
5
6
7
8
9
{
"data": {
"localDateTime": "2020-05-14T10:17:37.437",
"localDate": "2020-05-14",
"date": "2020-05-14 02:17:37",
"localTime": "10:17:37.437"
},
"success": true
}

发现即便添加 spring.jackson.date-format 配置,也仅仅对 Date 类型的生效完成格式化,而 Java 8 新的时间对象均未起到作用。

下面通过解决以上问题过程,来示范如何自定义一个 SpringBoot Starter

自定义 Starter

创建一个 starter 工程

spring Boot starter 的工程官方给出了规范,如下

官方命名空间

  • 前缀:spring-boot-starter-
  • 模式:spring-boot-starter-模块名
  • 举例:spring-boot-starter-web、spring-boot-starter-jdbc

自定义命名空间

  • 后缀:-spring-boot-starter
  • 模式:模块-spring-boot-starter
  • 举例:mybatis-spring-boot-starter

新建工程命名为 common-spring-boot-starter,添加相关依赖

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-autoconfigure</artifactId>
</dependency>
<dependency>
<!--生成属性提示-->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<!--jackson -->
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-json</artifactId>
</dependency>
</dependencies>

定义自动配置类

为了使 starter 更灵活,便于自定义,比如是否启用全局格式化,格式化的格式等,提供 starter 配置开关来控制。

通过配合使用 @ConditionalOnProperty 注解,来达到自定义是否开启全局格式化开关的目的,只有当配置中存在 common.date-format.enabled ,且值为 true 时,才启用。

通过 @EnableConfigurationProperties 注解加载配置,可以自行定义格式化的格式,比如 LocalDate 默认格式为 yyyy-MM-dd,可以在配置文件中修改为 yyyy/MM/dd,可以做到相当灵活。

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
@Configuration
@EnableConfigurationProperties(DateFormatProperties.class)
@ConditionalOnProperty(prefix = "common.date-format", name = "enabled", matchIfMissing = false, havingValue = "true")
public class DateFormatAutoConfiguration {
private DateFormatProperties dateFormatProperties;
public DateFormatAutoConfiguration(DateFormatProperties dateFormatProperties) {
this.dateFormatProperties = dateFormatProperties;
}

@Bean
public Jackson2ObjectMapperBuilderCustomizer customizer() {
return builder -> {
builder.locale(Locale.CHINA);
builder.timeZone(TimeZone.getTimeZone(ZoneId.systemDefault()));
builder.simpleDateFormat(dateFormatProperties.getDatePattern());
builder.modules(new JavaTimeModule());
};
}

class JavaTimeModule extends SimpleModule {
JavaTimeModule() {
super(PackageVersion.VERSION);
DateTimeFormatter localDateTimeFormatter = DateTimeFormatter.ofPattern(dateFormatProperties.getLocalDateTimePattern());
DateTimeFormatter localDateFormatter = DateTimeFormatter.ofPattern(dateFormatProperties.getLocalDatePattern());
DateTimeFormatter localTimeFormatter = DateTimeFormatter.ofPattern(dateFormatProperties.getLocalTimePattern());

this.addSerializer(LocalDateTime.class, new LocalDateTimeSerializer(localDateTimeFormatter));
this.addSerializer(LocalDate.class, new LocalDateSerializer(localDateFormatter));
this.addSerializer(LocalTime.class, new LocalTimeSerializer(localTimeFormatter));
this.addDeserializer(LocalDateTime.class, new LocalDateTimeDeserializer(localDateTimeFormatter));
this.addDeserializer(LocalDate.class, new LocalDateDeserializer(localDateFormatter));
this.addDeserializer(LocalTime.class, new LocalTimeDeserializer(localTimeFormatter));
}
}
}
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
/**
* @author WeJan
* @since 2020-05-14
*/
@ConfigurationProperties("common.date-format")
public class DateFormatProperties {

/**
* Date Format Pattern
*/
private String datePattern = "yyyy-MM-dd HH:mm:ss";

/**
* LocalDateTime Format Pattern
*/
private String localDateTimePattern = "yyyy-MM-dd HH:mm:ss";

/**
* LocalDate Format Pattern
*/
private String localDatePattern = "yyyy-MM-dd";

/**
* LocalTime Format Pattern
*/
private String localTimePattern = "HH:mm:ss";

// TODO 篇幅限制,此处省略 getter/setter 方法
}

让配置类生效

上文仅定义了自动配置类,但是想要让 Spring 加载这个配置类,还需要在 starter 工程中添加 spring.factories

resources 目录下建立 META-INF 文件夹,再创建 spring.factories 文件,再指定自动配置类的全限定类名。

1
2
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
pw.nullpointer.boot.autoconfigure.date.DateFormatAutoConfiguration

Install 本地 maven 仓库

执行 mvn install,安装到本地 maven 仓库

测试 starter

引入自定义的 starter

创建 example 工程,引入刚才 install 到 maven 仓库的 starter

1
2
3
4
5
<dependency>
<groupId>pw.nullpointer.tp</groupId>
<artifactId>common-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>

开启 starter 时间格式化功能

上文中自定义的 starter 默认设置的是不启用,因此需要在配置文件application.yml中启用一下格式化功能。

1
2
3
common:
date-format:
enabled: true # 开启时间格式化功能

启动项目测试

访问接口:http://127.0.0.1:8083/learning-example/test,返回如下:

1
2
3
4
5
6
7
8
9
{
"data": {
"localDateTime": "2020-05-14 11:22:29",
"localDate": "2020-05-14",
"date": "2020-05-14 11:22:29",
"localTime": "11:22:29"
},
"success": true
}

可以看到格式化已经生效了,顺便测试一下自定义格式化,修改 application.yml 文件

1
2
3
4
common:
date-format:
enabled: true
local-date-pattern: yyyy/MM/dd

再次测试,接口返回:

1
2
3
4
5
6
7
8
9
{
"data": {
"localDateTime": "2020-05-14 11:27:16",
"localDate": "2020/05/14",
"date": "2020-05-14 11:27:16",
"localTime": "11:27:16"
},
"success": true
}

优化 starter 属性提示

在使用 springboot 官方 starter 过程中,在编写 application.yml 的过程中,有哪些属性,IDEA 会自动提示出来,为了达到这种效果,需要引入依赖 spring-boot-configuration-processor,引入后,starter 在打包的过程中,会自动生成 spring-configuration-metadata.json 文件,使用 starter 过程中便有相应的提示了。前文初始化 starter 的过程中,我们已经引入过这个依赖了,所以就不用再重复引入了。

1
2
3
4
5
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>

但只根据这个依赖生成的spring-configuration-metadata.json 文件,使用过程中可以发现 common.date-format.enabled 这个属性开关是没有提示出来的,可以猜测到 spring-boot-configuration-processor是根据属性生成的,但是 enabled 这个非属性,所以无法生成。为了方便使用 starter 的人,我们可以追加一个 additional-spring-configuration-metadata.json 文件,手动添加相应的提示,文件内容:

1
2
3
4
5
6
7
8
9
10
{
"properties": [
{
"name": "common.date-format.enabled",
"type": "java.lang.Boolean",
"description": "是否开启时间格式化",
"defaultValue": false
}
]
}

使用效果:

image-20200516184327486
image-20200516184327486

测试完毕,为了方便使用,可以将自定义的 starter 发布到公司的私服。mvn deploy

总结

本文通过讲解实现一个项目时间全局格式化功能,如何自定义一个 springboot starter,当然 starter 功能不仅限如此,可以自行触类旁通扩展,比如项目的登录拦截器、通用日志、全局异常处理等工程都可以作为 starter 的一部分来实现,读者若看完有帮助并实践应用,可以评论留言应用的场景。

代码下载