今天以实用角度切入,来示范自定义 springboot starter 在项目开发过程中的实际应用。
SpringBoot 相对于 Spring 最大的优点就是提供了相当数量的 starter,只需引入 starter 进行极少量的配置就可使用相应的功能,有效减少 Spring 冗余复杂的配置文件。但日常工作当中,我们自己也会封装一些比较通用的代码 jar 包,引入到新的项目中很难避免添加相应的配置,比如 Bean 的声明。借鉴 SpringBoot 官方做法,我们自己也可以自定义所需要的 Starter。
今天以统一项目日期格式化功能为例,从头到尾地介绍如何自定义一个 Starter。
对于一个需要提供 HTTP 接口的服务来说,日期的格式化为友好的格式返回是一个无法避免的问题。实体类结构如下:
@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 中配置如下
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
未添加配置前返回:
{ "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 }
添加配置后返回:
{ "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
spring Boot starter 的工程官方给出了规范,如下
新建工程命名为 common-spring-boot-starter
,添加相关依赖
<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
,可以做到相当灵活。
@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)); } } }
/** * @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 文件,再指定自动配置类的全限定类名。
org.springframework.boot.autoconfigure.EnableAutoConfiguration=/ pw.nullpointer.boot.autoconfigure.date.DateFormatAutoConfiguration
执行 mvn install,安装到本地 maven 仓库
创建 example 工程,引入刚才 install 到 maven 仓库的 starter
<dependency> <groupId>pw.nullpointer.tp</groupId> <artifactId>common-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency>
上文中自定义的 starter 默认设置的是不启用,因此需要在配置文件 application.yml
中启用一下格式化功能。
common: date-format: enabled: true # 开启时间格式化功能
访问接口: http://127.0.0.1:8083/learning-example/test,返回如下:
{ "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 文件
common: date-format: enabled: true local-date-pattern: yyyy/MM/dd
再次测试,接口返回:
{ "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 }
在使用 springboot 官方 starter 过程中,在编写 application.yml 的过程中,有哪些属性,IDEA 会自动提示出来,为了达到这种效果,需要引入依赖 spring-boot-configuration-processor
,引入后,starter 在打包的过程中,会自动生成 spring-configuration-metadata.json
文件,使用 starter 过程中便有相应的提示了。前文初始化 starter 的过程中,我们已经引入过这个依赖了,所以就不用再重复引入了。
<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
文件,手动添加相应的提示,文件内容:
{ "properties": [ { "name": "common.date-format.enabled", "type": "java.lang.Boolean", "description": "是否开启时间格式化", "defaultValue": false } ] }
使用效果:
测试完毕,为了方便使用,可以将自定义的 starter 发布到公司的私服。 mvn deploy