元数据格式

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

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

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

  • 属性

  • YAML

server.port=9090
server.address=127.0.0.1
server:
  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 对象可以包含下表所示的属性

名称 类型 用途

name

字符串

组的完整名称。此属性是必需的。

type

字符串

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

description

字符串

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

sourceType

字符串

贡献此分组的源代码的类名。例如，如果该分组基于用@ConfigurationProperties注释的@Bean方法，则此属性将包含包含该方法的@Configuration类的完全限定名称。如果源类型未知，则可以省略此属性。

sourceMethod

字符串

贡献此分组的方法的全名（包括括号和参数类型）（例如，@ConfigurationProperties注释的@Bean方法的名称）。如果源方法未知，则可以省略。

属性属性

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

名称 类型 用途

name

字符串

属性的全名。名称采用小写字母点分隔的形式（例如，server.address）。此属性是必需的。

type

字符串

属性的数据类型的完整签名（例如，java.lang.String），但也包括完整的泛型类型（例如，java.util.Map<java.lang.String,com.example.MyEnum>）。您可以使用此属性指导用户可以输入的值的类型。为了保持一致性，使用其包装器对应物指定基本类型的类型（例如，boolean变为java.lang.Boolean）。请注意，此类可能是从String转换的复杂类型，因为值是绑定的。如果类型未知，则可以省略。

description

字符串

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

sourceType

字符串

贡献此属性的源代码的类名。例如，如果该属性来自用@ConfigurationProperties注释的类，则此属性将包含该类的完全限定名称。如果源类型未知，则可以省略。

defaultValue

对象

默认值，如果未指定属性，则使用该值。如果属性的类型是数组，则它可以是值数组。如果默认值未知，则可以省略。

deprecation

弃用

指定属性是否已弃用。如果字段未弃用或如果该信息未知，则可以省略。下表提供了有关deprecation属性的更多详细信息。

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

名称 类型 用途

level

字符串

弃用级别，可以是warning（默认值）或error。当属性具有warning弃用级别时，它仍应在环境中绑定。但是，当它具有error弃用级别时，该属性不再被管理并且不会被绑定。

reason

字符串

属性弃用的简短原因描述。如果没有可用的原因，则可以省略。建议描述为简短的段落，第一行提供简洁的摘要。描述的最后一行应以句点（.）结尾。

replacement

字符串

替换此弃用属性的属性的全名。如果此属性没有替换项，则可以省略。

since

字符串

属性被弃用的版本。可以省略。
在 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属性）。一旦可以从公共 API 中删除getTarget和setTarget方法，元数据中的自动弃用提示也将消失。如果要保留提示，则添加具有error弃用级别的手动元数据可确保用户仍然了解该属性。当提供replacement时，这样做特别有用。

提示属性

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

名称 类型 用途

name

字符串

此提示引用的属性的全名。名称采用小写字母点分隔的形式（例如，spring.mvc.servlet.path）。如果属性引用映射（例如，system.contexts），则提示要么应用于映射的键（system.contexts.keys），要么应用于映射的值（system.contexts.values）。此属性是必需的。

values

ValueHint[]

根据ValueHint对象定义的有效值列表（在下表中描述）。每个条目定义值，并且可能具有描述。

providers

ValueProvider[]

根据ValueProvider对象定义的提供程序列表（在本文档后面描述）。每个条目定义提供程序的名称及其参数（如果有）。

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

名称 类型 用途

value

对象

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

description

字符串

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

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

名称 类型 用途

name

字符串

提供程序的名称，用于为提示引用的元素提供其他内容帮助。

parameters

JSON对象

提供程序支持的任何其他参数（有关更多详细信息，请查看提供程序的文档）。

重复的元数据项

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