|
此版本仍在开发中，尚未被视为稳定版本。对于最新的稳定版本，请使用 Spring Boot 3.4.3！ |
元数据格式
配置元数据文件位于 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"
}
...
]
}}每个 “property” 都是用户使用给定值指定的配置项。
例如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群。
| 不要求每个 “property” 都有一个 “group”。 某些属性可能本身就存在。 |
“提示”是用于帮助用户配置给定属性的附加信息。
例如，当开发人员配置spring.jpa.hibernate.ddl-auto属性中，工具可以使用提示为none,validate,update,create和create-drop值。
最后，“ignored” 用于被故意忽略的项目。 此部分的内容通常来自其他元数据。
组属性
包含在groups数组可以包含下表中显示的属性：
| 名字 | 类型 | 目的 |
|---|---|---|
|
字符串 |
组的全名。 此属性是必需的。 |
|
字符串 |
组数据类型的类名。
例如，如果组基于一个带有 |
|
字符串 |
可向用户显示的组的简短描述。
如果没有可用的描述，则可以省略它。
建议描述为简短的段落，第一行提供简明的摘要。
描述中的最后一行应以句点 （ |
|
字符串 |
提供此组的源的类名。
例如，如果组基于 |
|
字符串 |
提供此组的方法的全名（包括括号和参数类型）（例如，一个 |
属性属性
包含在properties数组可以包含下表中描述的属性：
| 名字 | 类型 | 目的 |
|---|---|---|
|
字符串 |
属性的全名。
名称采用小写句点分隔形式（例如 |
|
字符串 |
属性数据类型的完整签名（例如 |
|
字符串 |
可向用户显示的属性的简短说明。
如果没有可用的描述，则可以省略它。
建议描述为简短的段落，第一行提供简明的摘要。
描述中的最后一行应以句点 （ |
|
字符串 |
提供此属性的源的类名。
例如，如果属性来自一个带有 |
|
对象 |
默认值，如果未指定属性，则使用该值。 如果属性的类型是数组，它可以是值的数组。 如果默认值未知，则可以省略它。 |
|
折旧 |
指定是否弃用该属性。
如果该字段未弃用或该信息未知，则可以省略该字段。
下表提供了有关 |
包含在deprecation每个properties元素可以包含以下属性：
| 名字 | 类型 | 目的 |
|---|---|---|
|
字符串 |
弃用级别，可以是 |
|
字符串 |
弃用属性的原因的简短描述。
如果没有可用的原因，则可以省略。
建议描述为简短的段落，第一行提供简明的摘要。
描述中的最后一行应以句点 （ |
|
字符串 |
替换此已弃用属性的属性的全名。 如果此属性没有替代项，则可以省略它。 |
|
字符串 |
属性已弃用的版本。 可以省略。 |
在 Spring Boot 1.3 之前，单个deprecatedboolean 属性代替deprecation元素。
这仍然以已弃用的方式受支持，不应再使用。
如果没有可用的原因和替换项，则为空的deprecationobject 的 |
弃用也可以在代码中以声明方式指定，方法是将@DeprecatedConfigurationProperty注解传递给 getter 来公开已弃用的属性。
例如，假设my.app.targetproperty 令人困惑，并被重命名为my.app.name.
以下示例显示如何处理这种情况：
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")
public String getTarget() {
return this.name;
}
@Deprecated
public void setTarget(String target) {
this.name = target;
}
}
There is no way to set a level.
warning is always assumed, since code is still handling the property.
The preceding code makes sure that the deprecated property still works (delegating to the name property behind the scenes).
Once the getTarget and setTarget methods can be removed from your public API, the automatic deprecation hint in the metadata goes away as well.
If you want to keep a hint, adding manual metadata with an error deprecation level ensures that users are still informed about that property.
Doing so is particularly useful when a replacement is provided.
Hint Attributes
The JSON object contained in the hints array can contain the attributes shown in the following table:
Name
Type
Purpose
name
String
The full name of the property to which this hint refers.
Names are in lower-case period-separated form (such as spring.mvc.servlet.path).
If the property refers to a map (such as system.contexts), the hint either applies to the keys of the map (system.contexts.keys) or the values (system.contexts.values) of the map.
This attribute is mandatory.
values
ValueHint[]
A list of valid values as defined by the ValueHint object (described in the next table).
Each entry defines the value and may have a description.
providers
ValueProvider[]
A list of providers as defined by the ValueProvider object (described later in this document).
Each entry defines the name of the provider and its parameters, if any.
The JSON object contained in the values attribute of each hint element can contain the attributes described in the following table:
Name
Type
Purpose
value
Object
A valid value for the element to which the hint refers.
If the type of the property is an array, it can also be an array of value(s).
This attribute is mandatory.
description
String
A short description of the value that can be displayed to users.
If no description is available, it may be omitted.
It is recommended that descriptions be short paragraphs, with the first line providing a concise summary.
The last line in the description should end with a period (.).
The JSON object contained in the providers attribute of each hint element can contain the attributes described in the following table:
Name
Type
Purpose
name
String
The name of the provider to use to offer additional content assistance for the element to which the hint refers.
parameters
JSON object
Any additional parameter that the provider supports (check the documentation of the provider for more details).
Ignored Attributes
The ignored object can contain the attributes shown in the following table:
Name
Type
Purpose
properties
ItemIgnore[]
A list of ignored properties as defined by the ItemIgnore object (described in the next table). Each entry defines the name of the ignored property.
The JSON object contained in the properties attribute of each ignored element can contain the attributes described in the following table:
Name
Type
Purpose
name
String
The full name of the property to ignore.
Names are in lower-case period-separated form (such as spring.mvc.servlet.path).
This attribute is mandatory.
Repeated Metadata Items
Objects with the same “property” and “group” name can appear multiple times within a metadata file.
For example, you could bind two separate classes to the same prefix, with each having potentially overlapping property names.
While the same names appearing in the metadata multiple times should not be common, consumers of metadata should take care to ensure that they support it.