配置元数据
1. 元数据格式
配置元数据文件位于 jar 中,位于META-INF/spring-configuration-metadata.json
.
它们使用 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."
}
]
}
]}
每个“属性”都是用户使用给定值指定的配置项。
例如server.port
和server.address
可能会在application.properties
/application.yaml
如下:
server.port=9090
server.address=127.0.0.1
server:
port: 9090
address: 127.0.0.1
“组”是更高级别的项,它们本身不指定值,而是为属性提供上下文分组。
例如,server.port
和server.address
属性是server
群。
不要求每个“属性”都有一个“组”。 某些属性可能本身存在。 |
最后,“提示”是用于帮助用户配置给定属性的附加信息。
例如,当开发人员配置spring.jpa.hibernate.ddl-auto
属性,工具可以使用提示为none
,validate
,update
,create
和create-drop
值。
1.1. 组属性
包含在groups
array 可以包含下表所示的属性:
名称 | 类型 | 目的 |
---|---|---|
|
字符串 |
组的全名。 此属性是强制性的。 |
|
字符串 |
组数据类型的类名。
例如,如果该组基于一个类,则 |
|
字符串 |
可向用户显示的组的简短描述。
如果没有可用的描述,则可以省略。
建议描述为简短段落,第一行提供简洁的摘要。
描述中的最后一行应以句点 ( |
|
字符串 |
提供此组的源的类名。
例如,如果该组基于 |
|
字符串 |
提供此组的方法的全名(包括括号和参数类型)(例如,一个 |
1.2. 属性属性
包含在properties
array 可以包含下表中描述的属性:
名称 | 类型 | 目的 |
---|---|---|
|
字符串 |
属性的全名。
名称采用小写句点分隔的形式(例如, |
|
字符串 |
属性数据类型的完整签名(例如 |
|
字符串 |
可向用户显示的属性的简短说明。
如果没有可用的描述,则可以省略。
建议描述为简短段落,第一行提供简洁的摘要。
描述中的最后一行应以句点 ( |
|
字符串 |
提供此属性的源的类名。
例如,如果该属性来自用 |
|
对象 |
默认值,如果未指定属性,则使用该值。 如果属性的类型是数组,则它可以是值数组。 如果默认值未知,则可以省略它。 |
|
折旧 |
指定该属性是否已弃用。如果该字段未被弃用或该信息未知,则可以省略该字段。下表提供了有关 |
包含在deprecation
每个属性properties
元素可以包含以下属性:
名称 | 类型 | 目的 |
---|---|---|
|
字符串 |
弃用级别,可以是 |
|
字符串 |
弃用该属性的原因的简短说明。
如果没有原因,可以省略。
建议描述为简短段落,第一行提供简洁的摘要。
描述中的最后一行应以句点 ( |
|
字符串 |
替换此已弃用属性的属性的全名。 如果此属性没有替代品,则可以省略。 |
在 Spring Boot 1.3 之前,单个deprecated boolean 属性可以代替deprecation 元素。
这仍然以已弃用的方式受支持,不应再使用。
如果没有原因和替换可用,则空deprecation 对象。 |
弃用也可以在代码中声明式指定,方法是将@DeprecatedConfigurationProperty
注释给 getter 公开已弃用的属性。
例如,假设my.app.target
属性令人困惑,并被重命名为my.app.name
.
以下示例演示如何处理这种情况:
@ConfigurationProperties("my.app")
public class MyProperties {
private String name;
public String getName() {
return this.name;
}
public void setName(String name) {
this.name = name;
}
@Deprecated
@DeprecatedConfigurationProperty(replacement = "my.app.name")
public String getTarget() {
return this.name;
}
@Deprecated
public void setTarget(String target) {
this.name = target;
}
}
没有办法设置一个level .warning 始终被假定,因为代码仍在处理该属性。 |
前面的代码确保已弃用的属性仍然有效(委托给name
幕后房产)。
一旦getTarget
和setTarget
可以从公共 API 中删除方法,元数据中的自动弃用提示也会消失。
如果您想保留提示,请使用error
弃用级别可确保用户仍了解该属性。
当replacement
被提供。
1.3. 提示属性
包含在hints
array 可以包含下表所示的属性:
名称 | 类型 | 目的 |
---|---|---|
|
字符串 |
此提示所引用的属性的全名。
名称采用小写句点分隔的形式(例如 |
|
价值提示[] |
由 |
|
价值提供者[] |
由 |
包含在values
每个属性hint
元素可以包含下表中描述的属性:
名称 | 类型 | 目的 |
---|---|---|
|
对象 |
提示引用的元素的有效值。 如果属性的类型是数组,它也可以是值数组。 此属性是强制性的。 |
|
字符串 |
可向用户显示的值的简短描述。
如果没有可用的描述,则可以省略。
建议描述为简短段落,第一行提供简洁的摘要。
描述中的最后一行应以句点 ( |
包含在providers
每个属性hint
元素可以包含下表中描述的属性:
名称 | 类型 | 目的 |
---|---|---|
|
字符串 |
用于为提示所引用的元素提供其他内容帮助的提供程序的名称。 |
|
JSON 对象 |
提供程序支持的任何其他参数(有关更多详细信息,请查看提供程序的文档)。 |
2. 提供手动提示
为了改善用户体验并进一步帮助用户配置给定属性,您可以提供其他元数据,这些元数据:
-
描述属性的潜在值列表。
-
关联提供程序,将定义明确的语义附加到属性,以便工具可以根据项目的上下文发现潜在值的列表。
2.1. 价值提示
这name
每个提示的属性引用name
财产的。
在前面显示的初始示例中,我们为spring.jpa.hibernate.ddl-auto
财产:none
,validate
,update
,create
和create-drop
.
每个值也可能有一个描述。
如果您的属性类型为Map
,您可以为键和值提供提示(但不能为映射本身提供提示)。
特别的.keys
和.values
后缀必须分别引用键和值。
假设一个my.contexts
地图魔法String
值设置为整数,如以下示例所示:
@ConfigurationProperties("my")
public class MyProperties {
private Map<String, Integer> contexts;
}
魔术值(在本例中)是sample1
和sample2
.
为了为密钥提供额外的内容帮助,您可以将以下 JSON 添加到模块的手动元数据中:
{"hints": [
{
"name": "my.contexts.keys",
"values": [
{
"value": "sample1"
},
{
"value": "sample2"
}
]
}
]}
我们建议您使用Enum 相反,对于这两个值。
如果您的 IDE 支持它,这是迄今为止最有效的自动完成方法。 |
2.2. 价值提供者
提供程序是将语义附加到属性的强大方法。 在本节中,我们将定义可用于自己的提示的官方提供程序。 但是,您最喜欢的 IDE 可能会实现其中的一些,或者没有实现其中的一部分。 此外,它最终可以提供自己的。
由于这是一项新功能,IDE 提供商必须赶上它的工作原理。采用时间自然会有所不同。 |
下表汇总了受支持的提供程序列表:
名称 | 描述 |
---|---|
|
允许提供任何附加值。 |
|
自动完成项目中可用的类。通常受 |
|
处理属性,就像它是由必需的 |
|
自动完成有效的记录器名称和记录器组。通常,当前项目中可用的包和类名称以及定义的组都可以自动完成。 |
|
自动完成当前项目中的可用 bean 名称。通常受 |
|
自动完成项目中可用的 Spring 配置文件名称。 |
对于给定属性,只能有一个提供程序处于活动状态,但如果多个提供程序都可以以某种方式管理该属性,则可以指定它们。 确保将功能最强大的提供程序放在第一位,因为 IDE 必须使用 JSON 部分中它可以处理的第一个提供程序。 如果不支持给定属性的提供程序,则也不会提供特殊的内容帮助。 |
2.2.1. 任何
特殊的 any provider 值允许提供任何其他值。 如果支持,则应应用基于属性类型的常规值验证。
如果您有值列表,并且任何额外的值仍应被视为有效,则通常使用此提供程序。
以下示例提供on
和off
作为自动完成值system.state
:
{"hints": [
{
"name": "system.state",
"values": [
{
"value": "on"
},
{
"value": "off"
}
],
"providers": [
{
"name": "any"
}
]
}
]}
请注意,在前面的示例中,还允许使用任何其他值。
2.2.2. 类引用
类引用提供程序自动完成项目中可用的类。 此提供程序支持以下参数:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
|
|
没有 |
应分配给所选值的类的完全限定名称。 通常用于过滤掉非候选类。 请注意,此信息可以由类型本身通过公开具有适当上限的类来提供。 |
|
|
true |
指定是否仅将具体类视为有效候选类。 |
以下元数据片段对应于标准server.servlet.jsp.class-name
定义JspServlet
要使用的类名:
{"hints": [
{
"name": "server.servlet.jsp.class-name",
"providers": [
{
"name": "class-reference",
"parameters": {
"target": "javax.servlet.http.HttpServlet"
}
}
]
}
]}
2.2.3. 处理为
handle-as 提供程序允许您将属性的类型替换为更高级的类型。
当属性具有java.lang.String
类型,因为您不希望配置类依赖于可能不在类路径上的类。
此提供程序支持以下参数:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
|
|
没有 |
要为属性考虑的类型的完全限定名称。 此参数是必填的。 |
可以使用以下类型:
-
任何
java.lang.Enum
:列出属性的可能值。 (我们建议使用Enum
类型,因为 IDE 不需要进一步的提示来自动完成值) -
java.nio.charset.Charset
:支持字符集/编码值的自动完成(例如UTF-8
) -
java.util.Locale
:自动完成区域设置(例如en_US
) -
org.springframework.util.MimeType
:支持自动完成内容类型值(例如text/plain
) -
org.springframework.core.io.Resource
:支持自动完成 Spring 的资源抽象以引用文件系统或类路径上的文件(例如classpath:/sample.properties
)
如果可以提供多个值,请使用Collection 或数组类型来向 IDE 传授它。 |
以下元数据片段对应于标准spring.liquibase.change-log
定义要使用的变更日志路径的属性。
它实际上在内部用作org.springframework.core.io.Resource
但不能这样公开,因为我们需要保留原始的 String 值才能将其传递给 Liquibase API。
{"hints": [
{
"name": "spring.liquibase.change-log",
"providers": [
{
"name": "handle-as",
"parameters": {
"target": "org.springframework.core.io.Resource"
}
}
]
}
]}
2.2.4. 记录器名称
logger-name 提供程序会自动完成有效的记录器名称和记录器组。 通常,当前项目中可用的包和类名称可以自动完成。 如果启用了组(默认),并且在配置中标识了自定义记录器组,则应为其提供自动完成功能。 特定框架可能也有额外的魔术记录器名称,也可以支持。
此提供程序支持以下参数:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
|
|
|
指定是否应考虑已知组。 |
由于记录器名称可以是任何任意名称,因此此提供程序应允许任何值,但可以突出显示项目类路径中不可用的有效包和类名称。
以下元数据片段对应于标准logging.level
财产。
键是记录器名称,值对应于标准日志级别或任何自定义级别。
由于 Spring Boot 定义了一些开箱即用的记录器组,因此为这些记录器组添加了专用的值提示。
{"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"
}
]
}
]}
2.2.5. Spring Bean 参考
spring-bean-reference 提供程序自动完成在当前项目的配置中定义的 bean。 此提供程序支持以下参数:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
|
|
没有 |
应分配给候选人的 bean 类的完全限定名称。 通常用于过滤掉非候选 Bean。 |
以下元数据片段对应于标准spring.jmx.server
定义MBeanServer
要使用的 bean:
{"hints": [
{
"name": "spring.jmx.server",
"providers": [
{
"name": "spring-bean-reference",
"parameters": {
"target": "javax.management.MBeanServer"
}
}
]
}
]}
活页夹不知道元数据。
如果您提供该提示,您仍然需要使用ApplicationContext . |
3. 使用注释处理器生成您自己的元数据
您可以轻松地从注释为@ConfigurationProperties
通过使用spring-boot-configuration-processor
罐。
jar 包括一个 Java 注释处理器,该处理器在编译项目时调用。
3.1. 配置注释处理器
要使用处理器,请包含对spring-boot-configuration-processor
.
对于 Maven,依赖项应声明为可选,如以下示例所示:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
对于 Gradle,依赖项应在annotationProcessor
配置,如以下示例所示:
dependencies {
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}
如果您正在使用additional-spring-configuration-metadata.json
文件,则compileJava
任务应配置为依赖于processResources
任务,如以下示例所示:
tasks.named('compileJava') {
inputs.files(tasks.named('processResources'))
}
此依赖关系可确保在编译期间运行注释处理器时,其他元数据可用。
如果您在项目中使用 AspectJ,则需要确保注释处理器仅运行一次。
有几种方法可以做到这一点。
使用 Maven,您可以配置
|
如果您在项目中使用 Lombok,则需要确保其注释处理器在 |
3.2. 自动元数据生成
处理器选取带有注释的类和方法@ConfigurationProperties
.
如果类还用@ConstructorBinding
,则需要一个构造函数,并且每个构造函数参数创建一个属性。
否则,通过标准 getter 和 setter 的存在来发现属性,这些 getter 和 setter 对集合和映射类型进行了特殊处理(即使仅存在 getter,也会检测到)。
注释处理器还支持使用@Data
,@Value
,@Getter
和@Setter
龙目岛注释。
请考虑以下示例:
@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {
/**
* Name of the server.
*/
private String name;
/**
* IP address to listen to.
*/
private String ip = "127.0.0.1";
/**
* Port to listener to.
*/
private int port = 9797;
这公开了三个属性,其中my.server.name
没有默认值,并且my.server.ip
和my.server.port
默认为"127.0.0.1"
和9797
分别。
Javadoc on 字段用于填充description
属性。例如,描述my.server.ip
是“要监听的 IP 地址”。
您应该仅将纯文本与@ConfigurationProperties 字段 Javadoc,因为它们在添加到 JSON 之前不会被处理。 |
注释处理器应用许多启发式方法从源模型中提取默认值。
默认值必须静态提供。特别是,不要引用在另一个类中定义的常量。
此外,注释处理器无法自动检测Enum
s 和Collections
s.
对于无法检测到默认值的情况,应提供手动元数据。 请考虑以下示例:
@ConfigurationProperties(prefix = "my.messaging")
public class MyMessagingProperties {
private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));
private ContainerType containerType = ContainerType.SIMPLE;
public enum ContainerType {
SIMPLE, DIRECT
}
}
为了记录上述类中属性的默认值,您可以将以下内容添加到模块的手动元数据中:
{"properties": [
{
"name": "my.messaging.addresses",
"defaultValue": ["a", "b"]
},
{
"name": "my.messaging.container-type",
"defaultValue": "simple"
}
]}
只有name 需要记录现有属性的其他元数据。 |
3.2.1. 嵌套属性
注释处理器会自动将内部类视为嵌套属性。
而不是记录ip
和port
在命名空间的根目录下,我们可以为其创建一个子命名空间。
考虑更新后的示例:
@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {
private String name;
private Host host;
public static class Host {
private String ip;
private int port;
}
}
前面的示例生成my.server.name
,my.server.host.ip
和my.server.host.port
性能。
您可以使用@NestedConfigurationProperty
注释,以指示应将常规(非内部)类视为嵌套类。
这对集合和映射没有影响,因为这些类型会自动识别,并且会为每个类型生成一个元数据属性。 |
3.3. 添加其他元数据
Spring Boot 的配置文件处理非常灵活,通常存在未绑定到@ConfigurationProperties
豆。
您可能还需要调整现有键的某些属性。
为了支持此类情况并让您提供自定义“提示”,注释处理器会自动合并来自META-INF/additional-spring-configuration-metadata.json
到主元数据文件中。
如果引用已自动检测到的属性,则描述、默认值和弃用信息(如果已指定)将被覆盖。 如果在当前模块中未标识手动属性声明,则将其添加为新属性。
的格式additional-spring-configuration-metadata.json
文件与常规文件完全相同spring-configuration-metadata.json
.
附加属性文件是可选的。
如果没有任何其他属性,请不要添加该文件。