配置元数据
1. 元数据格式
配置元数据文件位于元步兵/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属性是服务器群。
| 并非要求每个“财产”都有“群体”。 有些房产可能本身就存在。 |
最后,“提示”是用于帮助用户配置特定属性的额外信息。
例如,当开发者配置spring.jpa.hibernate.ddl-auto属性,一个工具可以利用提示为没有,驗證,更新,创造和创作-丢弃值。
1.1. 组属性
包含在组数组可以包含下表中显示的属性:
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
这是该团体的全名。 这一属性是必须的。 |
|
字符串 |
该组数据类型的类名称。
例如,如果该群基于一个注释为 |
|
字符串 |
可以向用户展示的小组简短描述。
如果没有描述,可以省略。
建议描述简短,第一行提供简明的总结。
描述的最后一行应以句号结尾( |
|
字符串 |
贡献该组的来源类别名称。
例如,如果该群基于 |
|
字符串 |
贡献该组的方法的全名(包括括号和参数类型)(例如,一个 |
1.2. 属性
包含在性能array 可以包含下表中描述的属性:
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
房产的全名。
名称采用小写的句点分隔形式(例如, |
|
字符串 |
属性数据类型的完整签名(例如, |
|
字符串 |
可以向用户展示的房产简短描述。
如果没有描述,可以省略。
建议描述简短,第一行提供简明的总结。
描述的最后一行应以句号结尾( |
|
字符串 |
贡献该属性的源的类名。
例如,如果该属性来自一个注释为 |
|
对象 |
默认值,如果未指定属性,则使用默认值。 如果属性类型是数组,则可以是值数组。 如果默认值未知,则可以省略。 |
|
折旧 |
请明确该属性是否已被弃用。
如果该字段未被弃用或该信息未知,则可省略。
下表提供了更多关于 |
包含在折旧每个属性性能元素可以包含以下属性:
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
弃用级别可以是以下两种 |
|
字符串 |
简要说明该房产被废弃的原因。
如果没有理由,可以省略。
建议描述简短,第一行提供简明的总结。
描述的最后一行应以句号结尾( |
|
字符串 |
替换该弃用财产的财产的全名。 如果该房产没有替代品,可能会被省略。 |
在 Spring Boot 1.3 之前,一首单曲荒废的可以使用布尔属性代替折旧元素。
该功能仍以被弃用的方式支持,不应再使用。
如果没有理由和替代,则空折旧对象应该被设置。 |
废弃也可以在代码中声明式地指定,通过添加@DeprecatedConfigurationProperty对获取器进行注释,暴露弃用性质。
例如,假设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;
}
}
没有办法设置水平.警告总是假设,因为代码仍在处理该属性。 |
上述代码确保被弃用属性仍然有效(委托给名称幕后财产)。
一旦获取目标和setTarget方法可以从你的公共API中移除,元数据中的自动弃用提示也会消失。
如果你想保持提示,可以手动添加带有错误弃用级别确保用户仍能了解该属性。
当更换提供。
1.3. 提示属性
包含在提示数组可以包含下表中显示的属性:
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
这是该暗示所指物业的全名。
名称采用小写的句号分隔形式(例如 |
|
价值提示[] |
由 |
|
ValueProvider[] |
由 |
包含在值每个属性提示元素可以包含下表中描述的属性:
| 名称 | 类型 | 目的 |
|---|---|---|
|
对象 |
提示所指元素的有效值。 如果属性的类型是数组,也可以是数组。 这一属性是必须的。 |
|
字符串 |
简要描述可以向用户展示的价值。
如果没有描述,可以省略。
建议描述简短,第一行提供简明的总结。
描述的最后一行应以句号结尾( |
包含在提供商每个属性提示元素可以包含下表中描述的属性:
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
提供额外内容支持的服务提供者名称。 |
|
JSON 对象 |
任何提供者支持的额外参数(详情请查阅提供者文档)。 |
2. 提供手动提示
为了提升用户体验并进一步协助用户配置特定属性,您可以提供额外的元数据,包括:
-
描述某一房产可能价值的列表。
-
关联提供者,将明确定义的语义附加到属性上,使工具能够根据项目上下文发现潜在值列表。
2.1. 价值提示
这名称每个提示的属性指代名称一处房产的。
在前面展示的初始示例中,我们给出了五个spring.jpa.hibernate.ddl-auto财产:没有,驗證,更新,创造和创作-丢弃.
每个值也可能带有描述。
如果你的财产属于类型地图你可以为键和数值提供提示(但不能为映射本身提供提示)。
特别节目。钥匙和。值后缀必须分别指代键和值。
假设我的.contexts地图魔法字符串将值映射到整数,如下例所示:
@ConfigurationProperties("my")
public class MyProperties {
private Map<String, Integer> contexts;
}
魔法值(在本例中)为样本1和样本2.
为了为密钥提供额外的内容辅助,你可以在模块的手动元数据中添加以下 JSON:
{"hints": [
{
"name": "my.contexts.keys",
"values": [
{
"value": "sample1"
},
{
"value": "sample2"
}
]
}
]}
我们建议您使用枚举而是针对这两个数值。
如果你的IDE支持,这无疑是最有效的自动补全方法。 |
2.2. 价值提供者
服务提供者是赋予属性语义的强大方式。 在本节中,我们将定义你可以用来获取提示的官方服务。 不过,你喜欢的IDE可能会实现其中一些,也可能一个都不实现。 此外,它最终也可能提供自己的产品。
| 由于这是一个新功能,IDE厂商必须跟上其工作原理。 收养时间自然不同。 |
下表总结了支持的提供者列表:
| 名称 | 描述 |
|---|---|
|
允许提供任何额外价值。 |
|
自动完成项目中可用的课程。
通常由 |
|
处理该属性的过程就像由强制性定义的类型一样 |
|
自动补全有效的日志器名称和日志组。 通常,当前项目中可用的包和类名称可以自动完成,也可以自定义组。 |
|
自动补全当前项目中可用的Beans名称。
通常由 |
|
自动补全项目中可用的 Spring 配置文件名称。 |
| 同一物业只能有一个提供商活跃,但如果他们都能以某种方式管理该物业,你可以指定多个提供者。 确保将最强大的提供者放在最前面,因为IDE必须使用它能处理的JSON部分中第一个提供者。 如果某一房产没有提供任何服务提供者,也不会提供特别的内容协助。 |
2.2.1. 任何
特别的“任意提供者”值允许提供任何额外值。 如果支持,应基于属性类型进行定期的价值验证。
通常用于你有数值列表且多余值仍应被视为有效。
以下示例提供了上和不对劲作为 的自动补全值system.state:
{"hints": [
{
"name": "system.state",
"values": [
{
"value": "on"
},
{
"value": "off"
}
],
"providers": [
{
"name": "any"
}
]
}
]}
注意,在上述例子中,任何其他值也被允许。
2.2.2. 类类参考
类引用提供者自动补全项目中可用的类。 该提供者支持以下参数:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
|
|
没有 |
应被赋值为所选值的类别的完全限定名称。 通常用来筛选非候选职业。 注意,这些信息可以通过类型本身提供,通过暴露具有适当上界的类来实现。 |
|
|
true |
明确是否仅将具体类视为有效候选。 |
以下元数据片段对应标准server.servlet.jsp.类名定义JspServlet使用类别名称:
{"hints": [
{
"name": "server.servlet.jsp.class-name",
"providers": [
{
"name": "class-reference",
"parameters": {
"target": "javax.servlet.http.HttpServlet"
}
}
]
}
]}
2.2.3. handle As
作为handle-provider可以让你将属性类型替换为更高级的类型。
这通常发生在房产拥有java.lang.字符串类型,因为你不希望配置类依赖可能不在类路径上的类。
该提供者支持以下参数:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
|
|
没有 |
该类型应考虑的完全合格名称。 这个参数是必须的。 |
可以使用以下类型:
-
任何
java.lang.Enum: 列出该属性的可能取值。 (我们建议用枚举类型,因为开发环境集成环境自动补全时无需额外提示) -
java.nio.charset.Charset:支持字符集/编码值的自动补全(例如UTF-8) -
java.util.Locale: 地点的自动补全(例如en_US) -
org.springframework.util.MimeType:支持内容类型值的自动补全(例如文本/纯文字) -
org.springframework.core.io.Resource: 支持Spring资源抽象的自动补全,以指代文件系统或类路径上的文件(例如:classpath:/sample.properties)
如果能提供多个值,可以使用收集或者数组类型来教IDE相关信息。 |
以下元数据片段对应标准spring.liquibase.change-log定义了使用变更日志路径的属性。
它实际上在内部被用作org.springframework.core.io.Resource但不能以 Strit 的身份暴露,因为我们需要保留原始的 String 值才能传递给 Liquibase API。
{"hints": [
{
"name": "spring.liquibase.change-log",
"providers": [
{
"name": "handle-as",
"parameters": {
"target": "org.springframework.core.io.Resource"
}
}
]
}
]}
2.2.4. Logging器名称
日志器名称提供者会自动补全有效的日志器名称和日志组。 通常,当前项目中可用的包和类名称可以自动完成。 如果组已启用(默认),并且配置中识别了自定义日志组,应为其提供自动补全功能。 某些框架可能还会支持额外的魔法日志名称。
该提供者支持以下参数:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
|
|
|
明确是否应考虑已知的群组。 |
由于日志器名称可以是任意名称,该提供者应允许任意值,但可以突出显示项目类路径中不存在的有效包和类名称。
以下元数据片段对应标准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-reference 提供者自动补全当前项目配置中定义的 beans。 该提供者支持以下参数:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
|
|
没有 |
应分配给候选人的Beans名称。 通常用于过滤非候选豆子。 |
以下元数据片段对应标准spring.jmx.server定义了MBeanServer使用豆子:
{"hints": [
{
"name": "spring.jmx.server",
"providers": [
{
"name": "spring-bean-reference",
"parameters": {
"target": "javax.management.MBeanServer"
}
}
]
}
]}
装订器并不知道元数据。
如果你提供了这个提示,你仍然需要将豆子名称转换成真正的豆子引用,使用应用上下文. |
3. 使用注释处理器生成自己的元数据
你可以轻松地从标注为@ConfigurationProperties通过使用Spring Boot配置处理器罐。
jar 包含一个 Java 注释处理器,在你的项目编译过程中调用它。
3.1. 配置注释处理器
使用处理器时,包含依赖于Spring Boot配置处理器.
在Maven中,依赖应被声明为可选,如下示例所示:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
使用 Gradle,依赖应在注释处理处理器配置,如下示例所示:
dependencies {
annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}
如果你正在使用additional-spring-configuration-metadata.json文件,该compileJava任务应配置为依赖于process资源任务,如下例所示:
tasks.named('compileJava') {
inputs.files(tasks.named('processResources'))
}
这种依赖确保在注释处理器编译过程中运行时,额外的元数据依然可用。
|
如果你在项目中使用 AspectJ,需要确保注释处理器只运行一次。
有几种方法可以做到这一点。
通过 Maven,你可以配置
|
|
如果你在项目中使用 Lombok,你需要确保它的注释处理器先运行 |
3.2. 自动元数据生成
处理器会接收被注释为@ConfigurationProperties.
如果该类也被注释为@ConstructorBinding,期望有一个构造子,每个构造子参数创建一个属性。
否则,性质是通过标准采集器和具有特殊收集和映射类型处理的集合者和定位器来发现的(即使只有一个采集器存在也能检测到)。
注释处理器还支持使用@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没有默认值,且我的服务器.ip和my.server.port默认为"127.0.0.1"和9797分别。
字段上的 Javadoc 用于填充描述属性。例如,描述我的服务器.ip是“可监听的IP地址”。
你应该只使用纯文本,且@ConfigurationProperties字段 Javadoc,因为它们在添加到 JSON 之前不会被处理。 |
注释处理器应用多种启发式方法从源模型中提取默认值。
默认值必须静态提供。特别地,不要引用其他类中定义的常量。
此外,注释处理器无法自动检测 的默认值枚举s 和收集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"
}
]}
只有名称该属性需要为现有属性记录额外的元数据。 |
3.2.1. 嵌套属性
注释处理器会自动将内部类视为嵌套属性。
而不是记录知识产权和端口在命名空间的根节点,我们可以为它创建一个子命名空间。
请考虑更新后的例子:
@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豆。
你还可能需要调整现有密钥的一些属性。
为了支持此类情况并允许你提供自定义“提示”,注释处理器会自动合并以下物品元步兵/additional-spring-configuration-metadata.json进入主元数据文件。
如果你提到的属性已被自动检测,描述、默认值和弃用信息(如有指定)会被覆盖。 如果当前模块中未识别手动属性声明,则作为新属性添加。
格式additional-spring-configuration-metadata.json锉刀与常规锉刀完全相同spring-configuration-metadata.json.
附加属性文件是可选的。
如果你没有其他属性,就不要添加该文件。