Spring Boot 配置元数据
Posted
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了Spring Boot 配置元数据相关的知识，希望对你有一定的参考价值。
Spring Boot jar 包含元数据文件，这些文件提供了所有受支持的配置属性的详细信息。这些文件旨在让 IDE 开发人员在用户使用文件时提供上下文帮助和“代码完成application.properties” application.yml。
大多数元数据文件是在编译时通过处理所有带有注释的项目自动生成的@ConfigurationProperties。但是，可以为极端情况或更高级的用例手动编写部分元数据。
配置元数据文件位于 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和server.address属性是server组的一部分。
最后，“提示”是用于帮助用户配置给定属性的附加信息。例如，当开发人员配置spring.jpa.hibernate.ddl-auto属性时，工具可以使用提示为none、validate、update、create和create-drop值提供一些自动完成帮助。
数组中包含的 JSON 对象groups可以包含下表所示的属性：
姓名 | 类型 | 目的 |
| 细绳 | 组的全名。该属性是强制性的。 |
| 细绳 | 组的数据类型的类名。例如，如果组基于用 注释的类 |
| 细绳 | 可以向用户显示的组的简短描述。如果没有可用的描述，则可以省略。建议描述是简短的段落，第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
| 细绳 | 贡献此组的源的类名。例如，如果组基于用 |
| 细绳 | 贡献该组的方法的全名（包括括号和参数类型）（例如，带 |
数组中包含的 JSON 对象properties可以包含下表中描述的属性：
姓名 | 类型 | 目的 |
| 细绳 | 财产的全名。名称采用小写的句点分隔形式（例如， |
| 细绳 | 属性数据类型的完整签名（例如 |
| 细绳 | 可以向用户显示的属性的简短描述。如果没有可用的描述，则可以省略。建议描述是简短的段落，第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
| 细绳 | 提供此属性的源的类名。例如，如果属性来自用 注释的类 |
| 目的 | 未指定属性时使用的默认值。如果属性的类型是数组，则它可以是值数组。如果默认值未知，则可以省略。 |
| 弃用 | 指定该属性是否已弃用。如果该字段未弃用或该信息未知，则可以省略。下表提供了有关该 |
deprecation每个元素的属性中包含的 JSON 对象properties可以包含以下属性：
姓名 | 类型 | 目的 |
| 细绳 | 弃用级别，可以是 |
| 细绳 | 属性被弃用的原因的简短描述。如果没有可用的原因，则可以省略。建议描述是简短的段落，第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
| 细绳 | 替换此已弃用属性的属性的全名。如果没有替代此属性，则可以省略。 |
也可以通过将@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;
前面的代码确保不推荐使用的属性仍然有效（委托给name幕后的属性）。一旦可以从公共 API 中删除getTargetandsetTarget方法，元数据中的自动弃用提示也会消失。如果您想保留提示，添加具有error弃用级别的手动元数据可确保用户仍了解该属性。当提供 a 时，这样做特别有用replacement。
数组中包含的 JSON 对象hints可以包含下表所示的属性：
姓名 | 类型 | 目的 |
| 细绳 | 此提示所指的属性的全名。名称采用小写句点分隔形式（例如 |
| 值提示[] | 由对象定义的有效值列表 |
| 价值提供者[] | 对象定义的提供者列表 |
values每个hint元素的属性中包含的 JSON 对象可以包含下表中描述的属性：
姓名 | 类型 | 目的 |
| 目的 | 提示所指元素的有效值。如果属性的类型是一个数组，它也可以是一个值数组。该属性是强制性的。 |
| 细绳 | 可以向用户显示的值的简短描述。如果没有可用的描述，则可以省略。建议描述是简短的段落，第一行提供简洁的摘要。说明中的最后一行应以句点 ( |
providers每个hint元素的属性中包含的 JSON 对象可以包含下表中描述的属性：
姓名 | 类型 | 目的 |
| 细绳 | 提供者的名称，用于为提示所指的元素提供额外的内容帮助。 |
| JSON 对象 | 提供程序支持的任何附加参数（查看提供程序的文档以获取更多详细信息）。 |
具有相同“属性”和“组”名称的对象可以在元数据文件中出现多次。例如，您可以将两个单独的类绑定到相同的前缀，每个类都有可能重叠的属性名称。虽然元数据中多次出现的相同名称不应该是常见的，但元数据的消费者应该注意确保他们支持它。
为了改善用户体验并进一步帮助用户配置给定的属性，您可以提供额外的元数据：
描述属性的潜在值列表。
关联一个提供者，将定义明确的语义附加到属性，以便工具可以根据项目的上下文发现潜在值列表。
2.1. 值提示
每个提示的name属性是指name一个属性的。在前面显示的初始示例中，我们为spring.jpa.hibernate.ddl-auto属性提供了五个值：none、validate、update、create和create-drop。每个值也可能有描述。
如果您的属性是 类型Map，您可以为键和值提供提示（但不能为地图本身提供提示）。特殊.keys和.values后缀必须分别引用键和值。
假设 amy.contexts将魔法String值映射到整数，如以下示例所示：
@ConfigurationProperties("my")
public class MyProperties
private Map<String, Integer> contexts;
// getters/setters ...
神奇的值是（在这个例子中）是sample1和sample2。为了为密钥提供额外的内容帮助，您可以将以下 JSON 添加到模块的手动元数据中：
"hints": [
"name": "my.contexts.keys",
"values": [
"value": "sample1"
,
"value": "sample2"
]
]
2.2. 价值提供者
提供程序是一种将语义附加到属性的强大方法。在本节中，我们定义了可用于您自己的提示的官方提供程序。但是，您最喜欢的 IDE 可能实现了其中的一些，也可能没有实现。此外，它最终可以提供自己的。
下表总结了支持的提供商列表：
姓名 | 描述 |
| 允许提供任何附加值。 |
| 自动完成项目中可用的类。通常受 |
| 处理属性，就好像它是由强制 |
| 自动完成有效的记录器名称和记录器组。通常，当前项目中可用的包和类名称可以自动完成以及定义的组。 |
| 自动完成当前项目中可用的 bean 名称。通常受 |
| 自动完成项目中可用的 Spring 配置文件名称。 |
2.2.1. 任何
特殊的any provider 值允许提供任何附加值。如果支持，则应应用基于属性类型的常规值验证。
如果您有值列表并且任何额外值仍应被视为有效，则通常使用此提供程序。
以下示例提供on和off作为 的自动完成值system.state：
"hints": [
"name": "system.state",
"values": [
"value": "on"
,
"value": "off"
],
"providers": [
"name": "any"
]
]
请注意，在前面的示例中，也允许使用任何其他值。
2.2.2类参考
类引用提供程序自动完成项目中可用的类。此提供程序支持以下参数：
范围 | 类型 | 默认值 | 描述 |
| | 没有任何 | 应分配给所选值的类的完全限定名称。通常用于过滤掉非候选类。请注意，此信息可以由类型本身通过公开具有适当上限的类来提供。 |
| | 真的 | 指定是否只有具体类被视为有效候选者。 |
以下元数据片段对应于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类型时，因为您不希望配置类依赖于可能不在类路径中的类。此提供程序支持以下参数：
范围 | 类型 | 默认值 | 描述 |
| | 没有任何 | 要为属性考虑的类型的完全限定名称。此参数是必需的。 |
可以使用以下类型：
- Any
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）
以下元数据片段对应于spring.liquibase.change-log定义要使用的更改日志路径的标准属性。它实际上在内部用作 aorg.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. 记录器名称
记录器名称提供程序自动完成有效的记录器名称和记录器组。通常，可以自动完成当前项目中可用的包和类名称。如果启用了组（默认）并且在配置中标识了自定义记录器组，则应为其提供自动完成功能。特定的框架可能有额外的魔法记录器名称，这些名称也可以被支持。
此提供程序支持以下参数：
范围 | 类型 | 默认值 | 以上是关于Spring Boot 配置元数据的主要内容，如果未能解决你的问题，请参考以下文章
重新运行 Spring Boot 配置注释处理器以更新生成的元数据 配置没有元表和数据源的 Spring Batch Job 用于在 Spring Boot 中存储真实信息 |