SpringBoot 配置提示功能(超详细)
目的
配置自动提示的辅助功能可以让配置写起来更快,准确率大大提高。
springbootjar包含提供所有支持的配置属性细节的元数据文件。文件的目的是为了让IDE开发者在用户使用application.properties或application.yml文件时提供上下文帮助和代码补全。
大多数元数据文件是在编译时通过处理用@ConfigurationProperties注释的所有项自动生成的。也可以手动编写部分元数据。
版本
参考SpringBoot2.2.0.RELEASE文档
文件
jar包中的META-INF/spring-configuration-metadata.json(自动生成)或META-INF/additional-spring-configuration-metadata.json(手动添加)
实战
@Configuration @ConfigurationProperties(prefix="file.upload") publicclassFileUploadConfig{ /**Maximumnumberofbytesperfile*/ privateStringmaxSize="1024M"; /**不允许的文件后缀*/ privateStringrejectSuffix; //注意:使用的时候必须要有getter/setter,否则不会自动生成该属性对应的提示 //此处因为篇幅原因省略getter/setter } @Configuration @ConfigurationProperties("map.test") publicclassMapTestConfig{ /**测试Map类型数据的提示*/ privateMap org.springframework.boot spring-boot-configuration-processor true data; //注意:使用的时候必须要有getter/setter,否则不会自动生成该属性对应的提示 //此处因为篇幅原因省略getter/setter }
中文注释会乱码,以上故意用中文注释的地方,会在下面文件中指定对应的描述,看是否会覆盖。
additional-spring-configuration-metadata.json { "properties":[ { "name":"file.upload.reject-suffix", "type":"java.lang.String", "defaultValue":"exe,jar", "description":"Thefilesuffixisnotallowed.", "sourceType":"com.lw.metadata.config.FileUploadConfig" }, { "name":"map.test.data", "type":"java.util.Map", "description":"TipsfortestingMaptypedata.", "sourceType":"com.lw.metadata.config.MapTestConfig" } ], "hints":[ { "name":"map.test.data.keys", "values":[ { "value":"name", "description":"Thenameoftheperson." }, { "value":"sex", "description":"Thesexoftheperson." } ] } ] }
mavencompile之后,生成的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":"Maximumnumberofbytesperfile", "sourceType":"com.lw.metadata.config.FileUploadConfig", "defaultValue":"1024M" }, { "name":"file.upload.reject-suffix", "type":"java.lang.String", "description":"Thefilesuffixisnotallowed.", "sourceType":"com.lw.metadata.config.FileUploadConfig", "defaultValue":"exe,jar" }, { "name":"map.test.data", "type":"java.util.Map", "description":"TipsfortestingMaptypedata.", "sourceType":"com.lw.metadata.config.MapTestConfig" } ], "hints":[ { "name":"map.test.data.keys", "values":[ { "value":"name", "description":"Thenameoftheperson." }, { "value":"sex", "description":"Thesexoftheperson." } ] } ] }
效果
由此可以看到以下现象:
- 代码中的默认值会自动生成到提示文件中,如: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":"DDLmode.Thisisactuallyashortcutforthe\"hibernate.hbm2ddl.auto\"property.", "sourceType":"org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate" } ], "hints":[ { "name":"spring.jpa.hibernate.ddl-auto", "values":[ { "value":"none", "description":"DisableDDLhandling." }, { "value":"validate", "description":"Validatetheschema,makenochangestothedatabase." }, { "value":"update", "description":"Updatetheschemaifnecessary." }, { "value":"create", "description":"Createtheschemaanddestroypreviousdata." }, { "value":"create-drop", "description":"Createandthendestroytheschemaattheendofthesession." } ] } ] }
groups
分组,将配置类分组。
可以按照文件来分组,即:将同一个配置文件的所有属性放在同一个组
属性 | 类型 | 是否必须 | 用途 |
---|---|---|---|
name | String | Y | 分组的完整名称 |
type | String | N | 分组数据类型的类名(如:使用@ConfigurationProperties注释的完整类名、使用@Bean注释的方法返回类型) |
description | String | N | 分组的简短描述。 |
sourceType | String | N | 提供分组来源的类名。 |
sourceMethod | String | N | 提供分组的方法,包含括号和参数类型。 |
properties
提示主体,必须
属性 | 类型 | 是否必须 | 用途 |
---|---|---|---|
name | String | Y | 属性的完整名称。名称采用小写句点分隔格式,如:server.address |
type | String | N | 属性数据类型的完整签名(如:java.lang.String)或完整的泛型类型(如:java.util.Map |
description | String | N | 分组的简短描述。 |
sourceType | String | N | 提供分组来源的类名。 |
defaultValue | Object | N | 默认值。当属性为指定时使用。 |
deprecation | Deprecation | N | 指定属性是否已弃用。 |
deprecation属性如下:
属性 | 类型 | 是否必须 | 用途 |
---|---|---|---|
level | String | N | 弃用级别,可以是 warning(默认值)或 error。warning:属性应该仍然可以使用;error:属性不保证可以使用 |
reason | String | N | 属性弃用的简短原因。 |
replacement | String | N | 替换此弃用属性的新属性全名。可为空 |
注意:SpringBoot1.3版本之前,是使用boolean类型的deprecated。
以下示例来源于官方文档,展示了如何处理这种场景:
@ConfigurationProperties("app.acme") publicclassAcmeProperties{ privateStringname; publicStringgetName(){...} publicvoidsetName(Stringname){...} @DeprecatedConfigurationProperty(replacement="app.acme.name") @Deprecated publicStringgetTarget(){ returngetName(); } @Deprecated publicvoidsetTarget(Stringtarget){ setName(target); } }
一旦getTarget和setTarget方法从公共API中删除,元数据中的自动弃用提示也会消失。如果要保留提示,则添加具有error弃用级别的手动元数据可以确保用户仍然了解该属性。在提供替代品时,这样做特别有用。
hints
辅助提示,非必须
属性 | 类型 | 是否必须 | 用途 |
---|---|---|---|
name | String | Y | 提示关联的属性的完整名称。名称是小写句点分隔格式(如:spring.mvc.servlet.path),如果属性关联map类型(如:system.contexts),提示可以关联map的键(system.contexts.keys)或者值(system.contexts.values)。 |
values | ValueHint[] | N | 有效值集合。(下表详述) |
providers | ValueProvider[] | N | 提供者集合。(下表详述) |
values属性如下:
@ConfigurationProperties("sample") publicclassSampleProperties{ privateMapcontexts; //gettersandsetters } {"hints":[ { "name":"sample.contexts.keys", "values":[ { "value":"sample1" }, { "value":"sample2" } ] } ]}
提示是对Map内每一对key-value的提示。
.keys和.values前缀必须分别关联Map的keys和values。
providers属性如下:
ValueProvider
一般用不到,建议跳过
下表总结了支持的providers列表:
属性 | 描述 |
---|---|
any | 允许提供任何附加值。 |
class-reference | 自动完成项目中可用的类。通常由目标参数指定的基类约束。 |
handle-as | 处理属性,就像它是由必须的target参数定义的类型定义的一样。 |
logger-name | 自动完成有效的记录器名称和记录器组。通常,当前项目中可用的包和类名可以自动完成,也可以定义组。 |
spring-bean-reference | 自动完成当前项目中可用的bean名称。通常由target参数指定的基类约束。 |
spring-profile-name | 自动完成项目中可用的spring配置文件名称。 |
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-nameprovider自动完成有效的记录器名称和记录器组。通常,当前项目中可用的包和类名可以自动完成。如果组已启用(默认),并且配置中标识了自定义记录器组,则应提供该组的自动完成。
支持以下参数:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
group | boolean | true | 指定是否应考虑已知组。 |
由于记录器名称可以是任意名称,此provider应允许任何值,但可以突出显示项目的类路径中不可用的有效包和类名。
以下是logging.level属性。keys是logger名,values关联标准的loglevels或自定义的level,
{"hints":[ { "name":"logging.level.keys", "values":[ { "value":"root", "description":"Rootloggerusedtoassignthedefaultlogginglevel." }, { "value":"sql", "description":"SQLlogginggroupincludingHibernateSQLlogger." }, { "value":"web", "description":"Weblogginggroupincludingcodecs." } ], "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。支持以下参数:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
target | String(Class) | 无 | 应该分配给候选对象的bean类的完全限定名。通常用于筛选非候选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-processorjar,您可以从用@ConfigurationProperties注释的类中轻松生成自己的配置元数据文件。jar包含一个java注释处理器,在编译项目时调用它。用此处理器,需要引入spring-boot-configuration-processor依赖。
org.springframework.boot spring-boot-configuration-processor true
处理器获取用@configurationproperties注释的类和方法。配置类中字段值的javadoc用于填充description属性。
注意:仅仅只应将简单文本与@configurationproperties字段javadoc一起使用,因为在将它们添加到json之前不会对它们进行处理。
如果类有一个“至少一个参数”的构造函数,则为每个构造函数参数创建一个属性。否则,通过标准getter和setter来发现属性,这些getter和setter对集合类型进行了特殊处理(即使只有getter存在,也会检测到)。
注解处理器还支持使用@data、@getter和@setter的lombok注解。
注解处理器无法自动检测Enum和Collections的默认值。在集合或枚举属性具有非空默认值的情况下,应提供手动元数据。
@ConfigurationProperties(prefix="acme.messaging") publicclassMessagingProperties{ privateListaddresses=newArrayList<>(Arrays.asList("a","b")); privateContainerType=ContainerType.SIMPLE; //...getterandsetters publicenumContainerType{ 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中禁用注解处理,如下:
org.apache.maven.plugins maven-compiler-plugin none
绑定属性
注解处理器自动将内部类视为嵌套属性。
@ConfigurationProperties(prefix="server") publicclassServerProperties{ privateStringname; privateHosthost; //...getterandsetters publicstaticclassHost{ privateStringip; privateintport; //...getterandsetters } }
上述示例生成server.name、server.host.ip和server.host.port属性的元数据信息。可以在字段上使用@NestedconfigurationProperty注解来指示应将常规(非内部)类视为嵌套类。
注意:这对集合和映射没有影响,因为这些类型是自动标识的,并且为每个类型生成一个元数据属性。
添加额外的元数据
SpringBoot的配置文件处理非常灵活,通常情况下,可能存在不绑定到@ConfigurationPropertiesbean的属性。您还可能需要调整现有key的某些属性,为了支持这种情况并让您提供自定义的“提示”,注解处理器会自动将META-INF/additional-spring-configuration-metadata.json中的提示项合并到主要元数据文件(spring-configuration-metadata.json)中。
如果引用已自动检测到的属性,则将覆盖描述、默认值和弃用信息(如果指定)。如果当前模块中没有标识手动属性中的声明,则将其作为新属性添加。
additional-spring-configuration-metadata.json文件的格式与spring-configuration-metadata.json文件一样。附加属性文件是可选的。如果没有任何其他属性,就不要添加文件。
总结
以上所述是小编给大家介绍的SpringBoot配置提示功能,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对毛票票网站的支持!
如果你觉得本文对你有帮助,欢迎转载,烦请注明出处,谢谢!
声明:本文内容来源于网络,版权归原作者所有,内容由互联网用户自发贡献自行上传,本网站不拥有所有权,未作人工编辑处理,也不承担相关法律责任。如果您发现有涉嫌版权的内容,欢迎发送邮件至:czq8825#qq.com(发邮件时,请将#更换为@)进行举报,并提供相关证据,一经查实,本站将立刻删除涉嫌侵权内容。