Metadata Format

QWen Max 中英对照 Metadata Format

配置元数据文件位于 JAR 包内的 META-INF/spring-configuration-metadata.json 中。它们使用 JSON 格式，其中的条目被归类为 “groups” 或 “properties”，附加的值提示（hints）归类在 “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

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” 用于已被明确忽略的项。此部分的内容通常来自 附加元数据。

Group Attributes

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 Attributes

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

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

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

名称	类型	用途
value	Object	该提示所指向元素的一个有效值。如果该属性的类型是数组，它也可以是一个值（或多个值）组成的数组。此属性为必填项。
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” 名称的对象可以在元数据文件中多次出现。例如，你可以将两个独立的类绑定到相同的前缀，每个类可能具有重叠的属性名称。尽管相同的名称在元数据中多次出现的情况并不常见，但元数据的使用者应注意确保支持这种情况。