1.文章前言
我们都知道可以使用 SpringBoot 快速的开发基于 Spring 框架的项目。由于围绕 SpringBoot 存在很多开箱即用的 Starter 依赖,使得我们在开发业务代码时能够非常方便的、不需要过多关注框架的配置,而只需要关注业务即可。
例如我想要在 SpringBoot 项目中集成 Redis,那么我只需要加入 spring-data-redis-starter 的依赖,并简单配置一下连接信息以及 Jedis 连接池配置就可以。这为我们省去了之前很多的配置操作。甚至有些功能的开启只需要在启动类或配置类上增加一个注解即可完成。
那么如果我们想要自己实现自己的 Starter 需要做些什么呢?下面就开始介绍如何实现自己的 spring-boot-starter-xxx。
2.原理浅谈
从总体上来看,无非就是将Jar包作为项目的依赖引入工程。而现在之所以增加了难度,是因为我们引入的是Spring Boot Starter,所以我们需要去了解Spring Boot对Spring Boot Starter的Jar包是如何加载的?下面我简单说一下。
SpringBoot 在启动时会去依赖的 starter 包中寻找 /META-INF/spring.factories 文件,然后根据文件中配置的路径去扫描项目所依赖的 Jar 包,这类似于 Java 的 SPI 机制。
细节上可以使用@Conditional 系列注解实现更加精确的配置加载Bean的条件。
JavaSPI 实际上是“基于接口的编程+策略模式+配置文件”组合实现的动态加载机制。
3.实现自动配置
接下来我会实现一个普通的Spring Boot Web工程,该工程有一个Service类,类的sayHello方法会返回一个字符串,字符串可以通过application配置文件进行配置。
1.新建一个Spring Boot工程,命名为spring-boot-starter-hello,pom.xml依赖:
工程命名规范
官方命名格式为: spring-boot-starter-{name}
非官方建议命名格式:{name}-spring-boot-starter
这里只是为了演示,个人项目建议跟随官方命名规范。
2.新建HelloProperties类,定义一个hello.msg参数(默认值World!)。
3.新建HelloService类,使用HelloProperties类的属性。
4.自动配置类,可以理解为实现自动配置功能的一个入口。
5.在resources目录下新建META-INF目录,并在META-INF下新建spring.factories文件,写入:
6.项目到这里就差不多了,不过作为依赖,最好还是再做一下收尾工作。
- 删除自动生成的启动类SpringBootStarterHelloApplication。
- 删除resources下的除META-INF目录之外的所有文件目录。
- 删除spring-boot-starter-test依赖并且删除test目录。
7.执行mvn install将spring-boot-starter-hello安装到本地。
当你直接执行时应该会报错,因为我们还需要在pom.xml去掉spring-boot-maven-plugin,也就是下面这段代码。
8.随便新建一个Spring Boot工程,引入spring-boot-starter-hello依赖。
9.在新工程中使用spring-boot-starter-hello的sayHello功能。
访问http://localhost:8080/sayHello?name=Mark
浏览器打印:Hello Mark World!
在application.properties文件中配置属性:hello.msg = 你好!
重启项目,再次刷新访问,浏览器响应:Hello Mark 你好!
如果你遇到中文乱码,可以参考
解决方案
在IDEA环境下:
File -> Settings -> Editor -> File Encodings
将Properties Files (*.properties)下的Default encoding for properties files设置为UTF-8,将Transparent native-to-ascii conversion前的勾选上。如图所示:
image
注意:做了上面操作后,一定要重新创建 application.properties 才有效!
4.元数据的配置
到目前为止,spring-boot-starter-hello的自动配置功能已实现,并且正确使用了,但还有一点不够完美,如果你也按上面步骤实现了自己的spring-boot-starter-hello自动配置,在application.properties中配置hello.msg属性时,你会发现并没有提示你有关该配置的信息,但是如果你想配置tomcat端口时,输入server.port是有提示的:
image
这种功能如何做呢?在Spring Boot官方文档中就已经给出了方法,新建META-INF/spring-configuration-metadata.json文件,进行配置。
image
那如何对spring-boot-starter-hello项目配置元数据呢?代码如下:
然后我们将spring-boot-starter-hello项目重新打包使用,如下图所示,就有了属性的提示:
下面我们就列出有关groups、properties、hints具体使用,不过我建议你可以先跳过这部分枯燥的内容。
4.1 Group属性
“groups”中包含的JSON对象可以包含下表中显示的属性:
4.2 Property属性
properties数组中包含的JSON对象可由以下属性构成:
4.3 hints属性
hints数组中包含的JSON对象可以包含以下属性:
每个"hints"元素的values属性中包含的JSON对象可以包含下表中描述的属性:
每个"hints"元素的providers属性中的JSON对象可以包含下表中描述的属性:
5.spring-boot-configuration-processor
配置上述数据是挺麻烦的,如果可以提供一种自动生成spring-configuration-metadata.json的依赖就好了。别说,还真有。spring-boot-configuration-processor依赖就可以做到,它的基本原理是在编译期使用注解处理器自动生成spring-configuration-metadata.json文件。文件中的数据来源于你是如何在类中定义hello.msg这个属性的,它会自动采集hello.msg的默认值和注释信息。不过我在测试时发现了中文乱码问题,而且网上有关spring-boot-configuration-processor的学习文档略少。
下面我贴出使用spring-boot-configuration-processor自动生成的spring-configuration-metadata.json文件内容:
可以看到properties里的description属性值来源于注释信息,defaultValue值来源于代码中书写的默认值。
这一步需要在idea设置中搜索Annotation Processors,勾住Enable annonation processing。
6.@Conditional 注解及作用
之前提到了在细节上可以使用@Conditional 系列注解实现更加精确的配置加载Bean的条件。下面列举 SpringBoot 中的所有 @Conditional 注解及作用
比如,注解@ConditionalOnProperty(prefix = "example.service