|
如需获取最新稳定版本，请使用 Spring Boot 4.0.4！ |
元数据格式
配置元数据文件位于 JAR 包内的 META-INF/spring-configuration-metadata.json 路径下。
这些文件采用 JSON 格式，其中各项按类别分别置于“groups”（分组）或“properties”（属性）下；附加的值提示信息置于“hints”（提示）下；被忽略的项则置于“ignored”（忽略）下，如下例所示：
{"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."
}
]
}
...
],"ignored": {
"properties": [
{
"name": "server.ignored"
}
...
]
}}每个“属性”都是用户以给定值指定的一项配置项。
例如，server.port 和 server.address 可能会在您的 application.properties/application.yaml 中如下所示进行指定：
-
Properties
-
YAML
server.port=9090
server.address=127.0.0.1server:
port: 9090
address: 127.0.0.1“分组”是更高级别的项，其本身并不指定具体值，而是为属性提供上下文相关的归类。
例如，server.port 和 server.address 属性属于 server 分组。
| 并非每个“属性”都必须拥有一个“组”。 某些属性可以独立存在。 |
“提示”是用于帮助用户配置特定属性的附加信息。
例如，当开发人员配置 spring.jpa.hibernate.ddl-auto 属性时，工具可利用这些提示为 none、validate、update、create 和 create-drop 的取值提供自动补全辅助。
最后，“已忽略”表示已被刻意忽略的项。 本节内容通常来自附加元数据。
分组属性
groups 数组中包含的 JSON 对象可包含下表所示的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
该组的全名。 此属性为必填项。 |
|
字符串 |
该分组所基于数据类型的类名。
例如，如果该分组基于一个使用 |
|
字符串 |
可向用户显示的组的简短描述。
如果没有可用的描述，则可以省略。
建议描述采用简短段落形式，首行提供简洁摘要。
描述的最后一行应以句号（ |
|
字符串 |
贡献此分组的源代码类的名称。
例如，如果该分组基于一个使用 |
|
字符串 |
对该分组有贡献的方法的完整名称（包括括号及参数类型）（例如，一个带有 |
属性特性
properties 数组中包含的 JSON 对象可包含下表所述的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
该属性的完整名称。
名称采用小写字母加英文句点分隔的形式（例如， |
|
字符串 |
该属性数据类型的完整签名（例如， |
|
字符串 |
该属性的简短描述，可向用户显示。
若无可用描述，则可省略。
建议描述采用简短段落形式，首行提供简洁摘要。
描述的最后一行应以句号（ |
|
字符串 |
贡献此属性的源类的类名。
例如，如果该属性来自一个使用 |
|
对象 |
默认值，即在未指定该属性时所使用的值。 如果该属性的类型为数组，则可以是一个值或多个值组成的数组。 如果默认值未知，则可将其省略。 |
|
弃用 |
指定该属性是否已弃用。
如果该字段未被弃用，或弃用状态未知，则可省略此项。
下表将更详细地介绍 |
每个 properties 元素的 deprecation 属性中包含的 JSON 对象可包含以下属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
弃用级别，其值可以是 |
|
字符串 |
该属性被弃用的原因简要说明。
若无可用原因，可省略此项。
建议说明文字为简短段落，首行提供简洁摘要。
说明文字的最后一行应以句号（ |
|
字符串 |
用于替代此已弃用属性的属性全名。 如果该属性没有替代项，则可省略此项。 |
|
字符串 |
该属性被标记为弃用的版本。 可省略。 |
在 Spring Boot 1.3 之前，可使用单个值为 deprecated 的布尔属性，以替代 deprecation 元素。
该用法目前仍受支持，但已被弃用，不应再使用。
若未提供原因（reason）和替代方案（replacement），则应设置一个空的 deprecation 对象。 |
弃用声明也可通过在暴露已弃用属性的 getter 方法上添加 @Deprecated 注解，在代码中以声明方式指定。
例如，假设 oldProperty 属性命名易引发混淆，现已重命名为 newProperty。
以下示例展示了如何处理该情况：
-
Java
-
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty;
@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", since = "1.2.0")
public String getTarget() {
return this.name;
}
@Deprecated
public void setTarget(String target) {
this.name = target;
}
}import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty
@ConfigurationProperties("my.app")
class MyProperties(val name: String?) {
var target: String? = null
@Deprecated("") @DeprecatedConfigurationProperty(replacement = "my.app.name", since = "1.2.0") get
@Deprecated("") set
}无法设置为 level。
由于代码仍在处理该属性，因此始终默认为 warning。 |
上述代码确保已弃用的属性仍可正常工作（在后台将其委托给 name 属性）。
一旦您能从公共 API 中移除 getTarget 和 setTarget 方法，元数据中的自动弃用提示也将随之消失。
如果您希望保留该提示，可通过添加带有 error 弃用级别的手动元数据，确保用户仍能获知该属性已被弃用。
当提供了 replacement 时，这种做法尤为有用。
提示属性
hints 数组中包含的 JSON 对象可包含下表所示的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
此提示所指向属性的完整名称。
名称采用小写字母加英文句点分隔的形式（例如 |
|
ValueHint[] |
由 |
|
ValueProvider[] |
由 |
每个 hint 元素的 values 属性中包含的 JSON 对象可包含下表所述的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
对象 |
提示所指向元素的有效值。 如果该属性的类型为数组，则此值也可以是值（或值列表）组成的数组。 此属性为必填项。 |
|
字符串 |
该值的简短描述，可向用户显示。
如果无可用描述，则可省略。
建议描述采用简短段落形式，首行提供简洁摘要。
描述的最后一行应以句号（ |
每个 hint 元素的 providers 属性中包含的 JSON 对象可包含下表所述的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
用于为提示所指向的元素提供额外内容辅助的提供程序名称。 |
|
JSON 对象 |
提供商支持的任何其他参数（有关更多详细信息，请参阅提供商的文档）。 |
被忽略的属性
ignored 对象可包含下表所示的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
ItemIgnore[] |
由 ItemIgnore 对象定义的被忽略属性列表（详见下表）。每个条目定义了被忽略属性的名称。 |
每个 ignored 元素的 properties 属性中包含的 JSON 对象可包含下表所述的属性：
| 名称 | 类型 | 目的 |
|---|---|---|
|
字符串 |
要忽略的属性的完整名称。
名称采用小写、以英文句点分隔的形式（例如 |
重复的元数据项
在同一元数据文件中，具有相同“property”和“group”名称的对象可出现多次。 例如，您可以将两个独立的类绑定到同一前缀，而每个类可能拥有重叠的属性名称。 尽管相同的名称在元数据中多次出现并不常见，但元数据的使用者仍需谨慎，确保自身能够支持该情况。