目的
配置自动提示的辅助功能可以让配置写起来更快,准确率大大提高。
springboot jar 包含提供所有支持的配置属性细节的元数据文件。文件的目的是为了让 IDE 开发者在用户使用 application.properties 或 application.yml 文件时提供上下文帮助和代码补全。
大多数元数据文件是在编译时通过处理用 @ConfigurationProperties 注释的所有项自动生成的。也可以手动编写部分元数据。
版本
参考 SpringBoot 2.2.0.RELEASE 文档
文件
jar包中的 META-INF/spring-configuration-metadata.json (自动生成)或 META-INF/additional-spring-configuration-metadata.json (手动添加)
实战
<!-- 引入相关依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency> @Configuration @ConfigurationProperties(prefix = "file.upload") public class FileUploadConfig { /** Maximum number of bytes per file */ private String maxSize = "1024M"; /** 不允许的文件后缀 */ private String rejectSuffix; //注意:使用的时候必须要有getter/setter,否则不会自动生成该属性对应的提示 //此处因为篇幅原因省略 getter/setter } @Configuration @ConfigurationProperties("map.test") public class MapTestConfig { /** 测试Map类型数据的提示 */ private Map<String, Object> data; //注意:使用的时候必须要有getter/setter,否则不会自动生成该属性对应的提示 //此处因为篇幅原因省略 getter/setter }
中文注释会乱码,以上故意用中文注释的地方,会在下面文件中指定对应的描述,看是否会覆盖。
additional-spring-configuration-metadata.json { "properties": [ { "name": "file.upload.reject-suffix", "type": "java.lang.String", "defaultValue": "exe,jar", "description": "The file suffix is not allowed.", "sourceType": "com.lw.metadata.config.FileUploadConfig" }, { "name": "map.test.data", "type": "java.util.Map", "description": "Tips for testing Map type data.", "sourceType": "com.lw.metadata.config.MapTestConfig" } ], "hints": [ { "name": "map.test.data.keys", "values": [ { "value": "name", "description": "The name of the person." }, { "value": "sex", "description": "The sex of the person." } ] } ] }
maven compile 之后,生成的 additional-spring-configuration-metadata.json 与源码中的一样,生成的 spring-configuration-metadata.json 如下:
{ "groups": [ { "name": "file.upload", "type": "com.lw.metadata.config.FileUploadConfig", "sourceType": "com.lw.metadata.config.FileUploadConfig" }, { "name": "map.test", "type": "com.lw.metadata.config.MapTestConfig", "sourceType": "com.lw.metadata.config.MapTestConfig" } ], "properties": [ { "name": "file.upload.max-size", "type": "java.lang.String", "description": "Maximum number of bytes per file", "sourceType": "com.lw.metadata.config.FileUploadConfig", "defaultValue": "1024M" }, { "name": "file.upload.reject-suffix", "type": "java.lang.String", "description": "The file suffix is not allowed.", "sourceType": "com.lw.metadata.config.FileUploadConfig", "defaultValue": "exe,jar" }, { "name": "map.test.data", "type": "java.util.Map<java.lang.String,java.lang.Object>", "description": "Tips for testing Map type data.", "sourceType": "com.lw.metadata.config.MapTestConfig" } ], "hints": [ { "name": "map.test.data.keys", "values": [ { "value": "name", "description": "The name of the person." }, { "value": "sex", "description": "The sex of the person." } ] } ] }
效果
由此可以看到以下现象:
- 代码中的默认值会自动生成到提示文件中,如:FileUploadConfig#maxSize
- 代码中的注释会自动生成到提示文件中,如:FileUploadConfig#maxSize
additional-spring-configuration-metadata.json
文件中存在的提示会覆盖自动生成的对应属性,若自动生成的没有此属性则自动增加。
手动写提示文件
示例
{ "groups": [ { "name": "server", "type": "org.springframework.boot.autoconfigure.web.ServerProperties", "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties" }, { "name": "spring.jpa.hibernate", "type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate", "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties", "sourceMethod": "getHibernate()" } ], "properties": [ { "name": "server.port", "type": "java.lang.Integer", "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties" }, { "name": "server.address", "type": "java.net.InetAddress", "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties" }, { "name": "spring.jpa.hibernate.ddl-auto", "type": "java.lang.String", "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.", "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate" } ], "hints": [ { "name": "spring.jpa.hibernate.ddl-auto", "values": [ { "value": "none", "description": "Disable DDL handling." }, { "value": "validate", "description": "Validate the schema, make no changes to the database." }, { "value": "update", "description": "Update the schema if necessary." }, { "value": "create", "description": "Create the schema and destroy previous data." }, { "value": "create-drop", "description": "Create and then destroy the schema at the end of the session." } ] } ] }
groups
分组,将配置类分组。
可以按照文件来分组,即:将同一个配置文件的所有属性放在同一个组
属性
类型
是否必须
用途
properties
提示主体,必须
属性
类型
是否必须
用途
deprecation属性如下:
属性
类型
是否必须
用途
注意:Spring Boot 1.3 版本之前,是使用 boolean 类型的 deprecated。
以下示例来源于官方文档,展示了如何处理这种场景:
@ConfigurationProperties("app.acme") public class AcmeProperties { private String name; public String getName() { ... } public void setName(String name) { ... } @DeprecatedConfigurationProperty(replacement = "app.acme.name") @Deprecated public String getTarget() { return getName(); } @Deprecated public void setTarget(String target) { setName(target); } }
一旦 getTarget 和 setTarget 方法从公共 API 中删除,元数据中的自动弃用提示也会消失。 如果要保留提示,则添加具有 error 弃用级别的手动元数据可以确保用户仍然了解该属性。在提供替代品时,这样做特别有用。
hints
辅助提示,非必须
属性
类型
是否必须
用途
values 属性如下:
@ConfigurationProperties("sample") public class SampleProperties { private Map<String,Integer> contexts; // getters and setters } {"hints": [ { "name": "sample.contexts.keys", "values": [ { "value": "sample1" }, { "value": "sample2" } ] } ]}
提示是对Map内每一对 key-value 的提示。
.keys 和 .values 前缀必须分别关联 Map 的 keys 和 values。
providers 属性如下:
属性
类型
是否必须
用途
ValueProvider
一般用不到,建议跳过
下表总结了支持的 providers 列表:
属性
描述
any
符合属性类型的所有值。
{"hints": [ { "name": "system.state", "values": [ { "value": "on" }, { "value": "off" } ], "providers": [ { "name": "any" } ] } ]} class-reference
提供以下参数:
{"hints": [ { "name": "server.servlet.jsp.class-name", "providers": [ { "name": "class-reference", "parameters": { "target": "javax.servlet.http.HttpServlet" } } ] } ]}
handle-as
允许您将属性的类型替换为更高级的类型。
这通常在属性具有 java.lang.String 类型时发生,因为您不希望配置类依赖于不在类路径上的类。
参数
类型
默认值
描述
可用的值如下:
任何 java.lang.Enum: 列出属性的可能值。
java.nio.charset.Charset: 支持自动完成字符集/编码值(如 utf-8)
java.util.Locale:自动完成区域设置(如:en_US)
org.springframework.util.MimeType:支持自动完成 content-type 值(如:text/plain)
org.springframework.core.io.Resource: 支持自动完成spring的资源抽象以引用文件系统或类路径上的文件 (如:
classpath:/sample.properties)
注意:如果要提供多个值,用 Collection 或 数组类型
{"hints": [ { "name": "spring.liquibase.change-log", "providers": [ { "name": "handle-as", "parameters": { "target": "org.springframework.core.io.Resource" } } ] } ]}
logger-name
logger-name provider 自动完成有效的记录器名称和记录器组。 通常,当前项目中可用的包和类名可以自动完成。 如果组已启用(默认),并且配置中标识了自定义记录器组,则应提供该组的自动完成。
支持以下参数:
参数
类型
默认值
描述
由于记录器名称可以是任意名称,此 provider 应允许任何值,但可以突出显示项目的类路径中不可用的有效包和类名。
以下是 logging.level 属性。keys 是 logger 名,values 关联标准的 log levels 或 自定义的 level,
{"hints": [ { "name": "logging.level.keys", "values": [ { "value": "root", "description": "Root logger used to assign the default logging level." }, { "value": "sql", "description": "SQL logging group including Hibernate SQL logger." }, { "value": "web", "description": "Web logging group including codecs." } ], "providers": [ { "name": "logger-name" } ] }, { "name": "logging.level.values", "values": [ { "value": "trace" }, { "value": "debug" }, { "value": "info" }, { "value": "warn" }, { "value": "error" }, { "value": "fatal" }, { "value": "off" } ], "providers": [ { "name": "any" } ] } ]}
spring-bean-reference
此 provider 自动完成在当前项目的配置中定义的bean。 支持以下参数:
参数
类型
默认值
描述
以下示例表示:spring.jmx.server 属性定义了使用 MBeanServer
{"hints": [ { "name": "spring.jmx.server", "providers": [ { "name": "spring-bean-reference", "parameters": { "target": "javax.management.MBeanServer" } } ] } ]}
spring-profile-name
此 provider 自动完成在当前项目的配置中定义的spring配置文件。
以下示例表示:spring.profiles.active属性可启用的配置文件名称。
{"hints": [ { "name": "spring.profiles.active", "providers": [ { "name": "spring-profile-name" } ] } ]}
可重复的元数据项
具有相同“property”和“group”名称的对象可以在元数据文件中多次出现。 例如,可以将两个单独的类绑定到同一前缀,每个类都有可能重叠的属性名。 虽然多次出现在元数据中的相同名称不应是常见的,但元数据的使用者应注意确保他们支持该名称。
自动生成提示文件
通过使用 spring-boot-configuration-processor jar
,您可以从用 @ConfigurationProperties 注释的类中轻松生成自己的配置元数据文件。 jar包含一个java注释处理器,在编译项目时调用它。 用此处理器,需要引入 spring-boot-configuration-processor 依赖。
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency>
处理器获取用@configurationproperties
注释的类和方法。 配置类中字段值的 javadoc 用于填充 description 属性。
注意:仅仅只应将简单文本与@configurationproperties字段javadoc一起使用,因为在将它们添加到json之前不会对它们进行处理。
如果类有一个“至少一个参数”的构造函数,则为每个构造函数参数创建一个属性。 否则,通过标准getter和setter来发现属性,这些getter和setter对集合类型进行了特殊处理(即使只有getter存在,也会检测到)。
注解处理器还支持使用@data、@getter和@setter 的 lombok 注解。
注解处理器无法自动检测 Enum 和 Collections 的默认值。在集合或枚举属性具有非空默认值的情况下,应提供手动元数据。
@ConfigurationProperties(prefix="acme.messaging") public class MessagingProperties { private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b")) ; private ContainerType = ContainerType.SIMPLE; // ... getter and setters public enum ContainerType { SIMPLE, DIRECT } }
为了提示上述属性的默认值,应该手动添加如下元数据:
{"properties": [ { "name": "acme.messaging.addresses", "defaultValue": ["a", "b"] }, { "name": "acme.messaging.container-type", "defaultValue": "simple" } ]}
注意: 如果在项目中使用 AspectJ,则需要确保注解处理器只运行一次。 使用 Maven 时, 可以显式地配置 maven-apt-plugin插件,并仅在那里向注解处理器添加依赖项。 还可以让 AspectJ 插件运行于所有的处理且在 maven-compiler-plugin 的 configuration 中禁用注解处理,如下:
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <proc>none</proc> </configuration> </plugin>
绑定属性
注解处理器自动将内部类视为嵌套属性。
@ConfigurationProperties(prefix="server") public class ServerProperties { private String name; private Host host; // ... getter and setters public static class Host { private String ip; private int port; // ... getter and setters } }
上述示例生成 server.name、server.host.ip 和 server.host.port 属性的元数据信息。 可以在字段上使用@NestedconfigurationProperty
注解来指示应将常规(非内部)类视为嵌套类。
注意: 这对集合和映射没有影响,因为这些类型是自动标识的,并且为每个类型生成一个元数据属性。
添加额外的元数据
Spring Boot 的配置文件处理非常灵活,通常情况下,可能存在不绑定到 @ConfigurationProperties bean
的属性。 您还可能需要调整现有key的某些属性,为了支持这种情况并让您提供自定义的“提示”,注解处理器会自动将 META-INF/additional-spring-configuration-metadata.json
中的提示项合并到主要元数据文件(spring-configuration-metadata.json)中。
如果引用已自动检测到的属性,则将覆盖描述、默认值和弃用信息(如果指定)。 如果当前模块中没有标识手动属性中的声明,则将其作为新属性添加。
additional-spring-configuration-metadata.json
文件的格式与 spring-configuration-metadata.json
文件一样。 附加属性文件是可选的。如果没有任何其他属性,就不要添加文件。
总结
以上所述是小编给大家介绍的SpringBoot 配置提示功能,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对自由互联网站的支持!
如果你觉得本文对你有帮助,欢迎转载,烦请注明出处,谢谢!