Metadata Format

QWen Max 中英对照 Metadata Format

配置元数据文件位于 jar 包内的 META-INF/spring-configuration-metadata.json 中。它们使用 JSON 格式，其中的条目被归类为 “groups” 或 “properties”，附加的值提示归类为 “hints”，而被忽略的条目则归类为 “ignored”，如下例所示：

{"groups": [
	{
		"name": "server",
		"type": "org.springframework.boot.web.server.autoconfigure.ServerProperties",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.ServerProperties"
	},
	{
		"name": "spring.jpa.hibernate",
		"type": "org.springframework.boot.jpa.autoconfigure.JpaProperties$Hibernate",
		"sourceType": "org.springframework.boot.jpa.autoconfigure.JpaProperties",
		"sourceMethod": "getHibernate()"
	}
	...
],"properties": [
	{
		"name": "server.port",
		"type": "java.lang.Integer",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.ServerProperties"
	},
	{
		"name": "server.address",
		"type": "java.net.InetAddress",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.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.jpa.autoconfigure.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

server.port=9090
server.address=127.0.0.1

YAML

server:
  port: 9090
  address: 127.0.0.1

“groups” 是更高层次的项目，它们本身并不指定值，而是为属性提供上下文分组。例如，server.port 和 server.address 属性属于 server 组。

备注

并非每个“property”都必须属于一个“group”。某些属性可能独立存在。

“hints” 是用于帮助用户配置给定属性的附加信息。例如，当开发者配置 spring.jpa.hibernate.ddl-auto 属性时，工具可以使用这些 hints 为 none、validate、update、create 和 create-drop 值提供一些自动补全的帮助。

最后，“ignored” 用于已被明确忽略的项目。此部分的内容通常来自 附加元数据。

组属性

groups 数组中包含的 JSON 对象可以包含下表所示的属性：

名称	类型	用途
name	String	组的完整名称。此属性为必填项。
type	String	组的数据类型的类名。例如，如果该组基于一个标注了 @ConfigurationProperties 的类，则该属性应包含该类的全限定名。如果它基于一个 @Bean 方法，则应为该方法的返回类型。如果类型未知，可以省略该属性。
description	String	可向用户显示的组的简短描述。如果没有可用描述，可以省略。建议描述使用简短段落，首行提供简洁摘要，最后一行以句号（.）结尾。
sourceType	String	贡献此组的源的类名。例如，如果该组基于一个标注了 @ConfigurationProperties 的 @Bean 方法，则此属性应包含包含该方法的 @Configuration 类的全限定名。如果源类型未知，可以省略该属性。
sourceMethod	String	贡献此组的方法的完整名称（包括括号和参数类型），例如标注了 @ConfigurationProperties 的 @Bean 方法的名称。如果源方法未知，可以省略。

属性特性

properties 数组中包含的 JSON 对象可以包含下表中描述的属性：

名称	类型	用途
name	String	属性的完整名称。名称采用小写、以点分隔的形式（例如 server.address）。此属性为必填项。
type	String	属性数据类型的完整签名（例如 String），也可以是完整的泛型类型（如 java.util.Map<java.lang.String,com.example.MyEnum>）。你可以使用此属性引导用户输入合适的值类型。为保持一致性，基本类型的类型应使用其对应的包装类（例如 boolean 应写作 Boolean）。注意，该类可能是一个复杂类型，在绑定时会从 String 转换而来。如果类型未知，可以省略。
description	String	属性的简短描述，可向用户展示。如果没有可用描述，可以省略。建议描述使用简短段落，首行提供简洁摘要，最后一行以句号（.）结尾。
sourceType	String	提供该属性的源类名。例如，如果属性来自一个标注了 @ConfigurationProperties 的类，则此属性应包含该类的全限定名。如果源类型未知，可以省略。
defaultValue	Object	默认值，在未指定属性时使用。如果属性类型为数组，可以是单个或多个值组成的数组。如果默认值未知，可以省略。
deprecation	Deprecation	指定属性是否已弃用。如果未弃用或相关信息未知，可以省略。下表提供了关于 deprecation 属性的更多细节。

每个 properties 元素的 deprecation 属性中包含的 JSON 对象可以包含以下属性：

名称	类型	用途
level	String	弃用级别，可以是 warning（默认值）或 error。当属性的弃用级别为 warning 时，它仍应在环境中进行绑定。但当其弃用级别为 error 时，该属性将不再被管理，也不会被绑定。
reason	String	属性被弃用的简短原因描述。若无可用原因，可省略。建议描述使用简短段落，首行提供简洁摘要，描述的最后一行应以句号（.）结尾。
replacement	String	替代 此弃用属性的完整属性名称。若无替代属性，可省略。
since	String	属性开始被弃用的版本。可省略。

备注

在 Spring Boot 1.3 之前，可以使用单个 deprecated 布尔属性来代替 deprecation 元素。这种方式目前仍以弃用的形式被支持，但不应再使用。如果没有可用的原因和替代方案，应设置一个空的 deprecation 对象。

也可以通过在暴露已弃用属性的 getter 方法上添加 @DeprecatedConfigurationProperty 注解，以声明式的方式在代码中指定弃用。例如，假设 my.app.target 属性容易引起混淆，已被重命名为 my.app.name。以下示例展示了如何处理这种情况：

Java

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;
	}

}

Kotlin

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 时，这样做尤其有用。

Hint 属性

hints 数组中包含的 JSON 对象可以包含下表所示的属性：

名称	类型	用途
name	String	此提示所引用的属性的完整名称。名称采用小写、以点分隔的形式（例如 spring.mvc.servlet.path）。如果属性引用的是一个 map（例如 system.contexts），则该提示适用于 map 的 键（system.contexts.keys）或 map 的 值（system.contexts.values）。此属性为必填项。
values	ValueHint[]	由 ValueHint 对象定义的有效值列表（在下表中描述）。每个条目定义了值，并可包含描述信息。
providers	ValueProvider[]	由 ValueProvider 对象定义的提供者列表（本文档后续部分描述）。每个条目定义了提供者的名称及其参数（如果有）。

每个 hint 元素的 values 属性中包含的 JSON 对象可以包含下表中描述的属性：

名称	类型	用途
value	Object	对 hint 所指向元素的有效值。如果该属性的类型是数组，它也可以是一个值的数组。此属性为必填项。
description	String	可向用户显示的值的简短描述。如果没有可用的描述，可以省略。建议描述为简短段落，第一行提供简洁的摘要。描述的最后一行应以句号（.）结尾。

每个 hint 元素的 providers 属性中包含的 JSON 对象可以包含下表中描述的属性：

名称	类型	用途
name	String	用于为提示所指向的元素提供额外内容辅助的 provider 的名称。
parameters	JSON object	provider 支持的任何额外参数（请查阅该 provider 的文档以获取更多详情）。

忽略的属性

ignored 对象可以包含下表所示的属性：

名称	类型	用途
properties	ItemIgnore[]	由 ItemIgnore 对象定义的忽略属性列表（在下表中描述）。每个条目定义了被忽略属性的名称。

每个 ignored 元素的 properties 属性中包含的 JSON 对象可以包含下表中描述的属性：

名称	类型	用途
name	String	要忽略的属性的完整名称。名称采用小写、以点分隔的形式（例如 spring.mvc.servlet.path）。此属性为必填项。

重复的元数据项

具有相同“property”和“group”名称的对象可以在元数据文件中多次出现。例如，你可以将两个独立的类绑定到相同的前缀，每个类可能具有重叠的属性名称。虽然相同的名称在元数据中多次出现的情况不应常见，但元数据的使用者应注意确保其支持这种情况。