元数据格式

配置元数据文件位于 jar 包内的 META-INF/spring-configuration-metadata.json 下。它们使用 JSON 格式，项目分类为“组（groups）”或“属性（properties）”，额外的提示值分类为“hints”，如下例所示

{"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."
			}
		]
	}
]}

每个“属性（property）”都是用户指定一个给定值的配置项。例如，可以在 application.properties/application.yaml 中指定 server.port 和 server.address，如下所示

  • 属性

  • YAML

server.port=9090
server.address=127.0.0.1
server:
  port: 9090
  address: 127.0.0.1

“组（groups）”是更高级别的项，它们本身不指定值，而是为属性提供上下文分组。例如，server.port 和 server.address 属性是 server 组的一部分。

并非每个“属性（property）”都必须有一个“组（group）”。有些属性可以独立存在。

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

组属性

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

名称 类型 用途

name

String

组的完整名称。此属性是强制的。

type

String

组的数据类型的类名。例如，如果组基于用 @ConfigurationProperties 注解的类，则该属性将包含该类的完全限定名。如果它基于 @Bean 方法，则将是该方法的返回类型。如果类型未知，则可以省略该属性。

description

String

组的简短描述，可以显示给用户。如果没有描述，则可以省略。建议描述采用短段落，第一行提供简洁摘要。描述的最后一行应以句点 (.) 结尾。

sourceType

String

贡献此组的源的类名。例如，如果组基于用 @Bean 方法且用 @ConfigurationProperties 注解，则此属性将包含包含该方法的 @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 属性的更多细节。

每个 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。以下示例展示了如何处理这种情况

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

}
无法设置 level。总是假定为 warning，因为代码仍在处理该属性。

前面的代码确保弃用属性仍然有效（在幕后委托给 name 属性）。一旦 getTarget 和 setTarget 方法可以从你的公共 API 中移除，元数据中的自动弃用提示也会消失。如果想保留提示，添加具有 error 弃用级别的手动元数据可以确保用户仍然了解该属性。在提供了 replacement 时，这样做尤其有用。

提示属性

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

提示所引用的元素的有效值。如果属性类型是数组，它也可以是值数组。此属性是强制的。

description

String

值的简短描述，可以显示给用户。如果没有描述，则可以省略。建议描述采用短段落，第一行提供简洁摘要。描述的最后一行应以句点 (.) 结尾。

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

名称 类型 用途

name

String

用于为提示引用的元素提供额外内容辅助的提供者名称。

parameters

JSON 对象

提供者支持的任何附加参数（有关更多详细信息，请查看提供者的文档）。

重复的元数据项

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