元数据格式

配置元数据文件位于 jars 中的 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” 是用户用给定值指定的配置项。 例如，server.port 和 server.address 可能在你的 application.properties/application.yaml 中指定，如下所示：

  • Properties

  • 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 值提供一些自动完成帮助。

Group Attributes

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

Name Type Purpose

name

String

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

type

String

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

description

String

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

sourceType

String

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

sourceMethod

String

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

Property Attributes

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

Name Type Purpose

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 对象可以包含以下属性：

Name Type Purpose

level

String

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

reason

String

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

replacement

String

替换此弃用属性的属性的完整名称。 如果此属性没有替换，可以省略。

since

String

属性被弃用的版本。 可以省略。

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

弃用也可以在代码中通过将 @DeprecatedConfigurationProperty 注解添加到暴露弃用属性的 getter 来声明性地指定。 例如，假设 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 时，这特别有用。

Hint Attributes

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

Name Type Purpose

name

String

此提示引用的属性的完整名称。 名称采用小写点分隔形式（如 spring.mvc.servlet.path）。 如果属性引用映射（如 system.contexts），提示可以应用于映射的键（system.contexts.keys）或映射的值（system.contexts.values）。 此属性是必需的。

values

ValueHint[]

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

providers

ValueProvider[]

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

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

Name Type Purpose

value

Object

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

description

String

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

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

Name Type Purpose

name

String

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

parameters

JSON object

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

Repeated Metadata Items

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