SpringBoot 配置提示功能(超详细)

2023-08-10 02:53:05 296

目的

配置自动提示的辅助功能可以让配置写起来更快，准确率大大提高。

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（手动添加）

实战



org.springframework.boot
spring-boot-configuration-processor
true

@Configuration
@ConfigurationProperties(prefix="file.upload")
publicclassFileUploadConfig{
/**Maximumnumberofbytesperfile*/
privateStringmaxSize="1024M";

/**不允许的文件后缀*/
privateStringrejectSuffix;
//注意：使用的时候必须要有getter/setter，否则不会自动生成该属性对应的提示
//此处因为篇幅原因省略getter/setter
}
@Configuration
@ConfigurationProperties("map.test")
publicclassMapTestConfig{
/**测试Map类型数据的提示*/
privateMapdata;
//注意：使用的时候必须要有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）。此属性提示用户输入值得类型。原生类型在此处使用其包装类型（如：boolean使用java.lang.Boolean）。
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属性如下：

属性类型是否必须用途 name String N 用于为提示所引用的元素提供其他内容帮助的provider的名称。 parameters JSONobject N provider所支持的任何其他参数（有关详细信息，请查看provider的文档）。

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类型时发生，因为您不希望配置类依赖于不在类路径上的类。

参数类型默认值描述 target String（Class）无 Y 为属性考虑的类型的完全限定名。

可用的值如下：

任何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（发邮件时，请将#更换为@）进行举报，并提供相关证据，一经查实，本站将立刻删除涉嫌侵权内容。

SpringBoot 配置提示功能(超详细)

热门推荐

随机推荐