为SpringBoot项目中的自定义配置添加IDE支持

代码是写给人看的，不是写给机器看的，只是顺便计算机能够执行而已

——《计算机程序的构造和解释（SICP）》

导言

在咱们的项目里常常会出现须要添加自定义配置的应用场景，例如某个开关变量，在测试环境打开，在生产环境不打开，一般咱们都会使用下面的代码来实现，而后在Spring Boot配置文件中添加这个key和Value

Application.java:

application.properties

或者是没有使用@Value而直接在XML中使用咱们配置的属性值

application.xml

这样的代码和配置在Spring Boot项目中能够正常启动并读取配置，可是在咱们的IDE中却不会为咱们提示配置的类型和代码补全。当咱们有新同事到来，或者是须要为配置文件添加新的环境的支持的时候，咱们很容易会把配置文件的Key拼错，或者Value的值与咱们的变量类型并不兼容（实际上真的发生过这样的问题致使项目启动失败）。

可是在咱们使用Spring Boot提供的配置的时候，IDE老是能为咱们自动补全，告诉咱们这个配置的变量类型，甚至是给咱们把这个配置的描述显示出来。

咱们是否也能够为咱们本身写的配置添加这样的IDE支持呢？

配置项元数据（Configuration Metadata）

Spring Boot的Jar文件包含元数据文件，这些文件提供了咱们所须要的配置属性的详细信息。IDE经过读取这些元数据文件，而后在使用application.properties或application.yml的时候提供上下文信息和代码补全。那么只要知道如何编写并存放配置项元数据信息文件，咱们也可让IDE知道如何为咱们的自定义配置提供上下文信息。

元数据格式

Spring Boot项目的配置项元数据文件都放在META-INF/spring-configuration-metadata.json中。下图是当咱们配置好Spring Boot项目后默认使用的Spring Boot自动配置的配置项元数据存放的位置

配置项元数据文件按照groups, properties和hints组织。properties下的每一个property都是程序中须要使用的配置项的key值，好比server.port是服务启动后的端口号。而咱们能够将一些property按照某些规则组合起来，这个组合就是group（一般咱们并不须要为properties组织对应的group）。而hints是为咱们的配置项提供额外的信息，好比时区time.zone支持Asia/Shanghai，咱们能够为它提供"Asia/Shanghai"的hint。

properties的参数

名称	类型	描述
name	String	属性的全名。名称是小写字母以句点分割。此属性是必须的
type	String	属性的数据类型的完整签名（java.lang.String），若是是范型的话还应当包含完整的范型参数（java.util.List<java.lang.String>）。为了保证一致性，须要使用包装类型来替代基本类型。此属性不是必须的，可是没法获得类型诊断的支持。

hints的参数

名称	类型	描述
name	String	该提示所引用的属性的全称，和properties的name参数相同。此属性是必须的
values	ValueHint[]	ValueHint对象定义的有效值列表。每一个条目都定义该值，而且能够具备描述

ValueHint的参数

名称	类型	描述
value	Object	property给定的类型的有效值，若是property的类型是数组，那么它也能够是值的数组。此属性是必须的。若是是Map类型的属性，可使用.keys和.values来指定对应的有效值。
description	String	和properties的description相同，提示给用户的简短描述。此属性不是必须的。

这里只展现了咱们经常使用的参数，关于配置项元数据文件格式的详细信息能够看Spring Boot的官方文档（https://docs.spring.io/spring-boot/docs/current/reference/html/appendix-configuration-metadata.html#configuration-metadata-format）

为自定义配置编写配置项元数据

接下来咱们将对值、数组场景编写对应的配置项元数据，并为这些配置项添加提示（Talk is cheap，show me the code）

在IDE中实际使用的效果

不过这种方式虽然好，可是须要咱们写不少的JSON配置来告诉IDE该如何进行代码补全和附加上下文信息，配置和代码仍是处于分离的状态，若是能经过写一个配置类，直接经过这个类和它的注释就能为咱们作到IDE支持就行了——Spring Boot开发者也是这么想的。

为代码自动生成配置项元数据

首先咱们要改掉随处使用@Value的习惯，使用专门的数据类来存放咱们的配置项

接下来咱们建立一个Bean，让Spring Boot容器来接管这个类的实例

经过@ConfigurationProperties注解，Spring就会自动将配置注入到咱们的配置Bean中，可是此时IDE还没法识别咱们添加的自动配置，咱们须要添加Spring Boot的注解处理器（annotation processor，从Java 1.6开始支持的特性）

添加注解处理器后从新编译，咱们就会在target目录下看到自动生成的META-INF/spring-configuration-metadata.json

里面的内容基本就是咱们以前本身手动输入的内容，只是受于Java代码表达信息的局限性，没有办法生成hints信息。其中sourceType和sourceMethod属性还能够帮助IDE跳转到咱们声明这个配置的类和方法

若是咱们想要让咱们使用代码生成的配置类也能添加提示的话，能够在咱们的META-INF目录下添加additional-spring-configuration-metadata.json文件，将hints写到这个文件里面

这样Spring Boot在编译的时候就会将咱们的提示信息合并到配置信息元数据文件里面了

虽然这些工做不会增长代码的运行效率，可是让咱们的配置集中起来并有IDE的加成，会让咱们更改配置的时候更加有信心。正如开头所说的，代码是写给人看的，不是写给机器看的，只是顺便计算机能够执行而已。