元数据格式

配置元数据文件位于jar包内的 META-INF/spring-configuration-metadata.json 路径下。 它们采用JSON格式，条目被归类为“groups”或“properties”，额外的值提示归类为“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": "禁用DDL处理。"
			},
			{
				"value": "validate",
				"description": "验证schema，不对数据库做任何更改。"
			},
			{
				"value": "update",
				"description": "如有必要，更新schema。"
			},
			{
				"value": "create",
				"description": "创建schema并销毁原有数据。"
			},
			{
				"value": "create-drop",
				"description": "创建schema并在会话结束时销毁。"
			}
		]
	}
	...
],"ignored": {
	"properties": [
		{
			"name": "server.ignored"
		}
		...
	]
}}

每个“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 属性时，工具可以利用hints为 none、validate、update、create 和 create-drop 等值提供自动补全。

最后，“ignored”用于那些被有意忽略的条目。 本节内容通常来自 附加元数据。

分组属性（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 对象。

弃用也可通过在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 时尤为有用。

提示属性（Hint Attributes）

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

Name Type Purpose

name

String

此提示所指向属性的全名。 名称采用小写点分隔形式（如 spring.mvc.servlet.path）。 若属性为map（如 system.contexts），则提示可应用于map的 keys（system.contexts.keys）或 values（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

提供者支持的其他参数（详见提供者文档）。

忽略属性（Ignored Attributes）

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

Name Type Purpose

properties

ItemIgnore[]

忽略属性列表，由 ItemIgnore 对象定义（见下表）。每项定义被忽略属性的名称。

ignored 元素的 properties 属性中的JSON对象可包含如下属性：

Name Type Purpose

name

String

要忽略的属性全名。 名称采用小写点分隔形式（如 spring.mvc.servlet.path）。 此属性为必填项。

重复元数据项（Repeated Metadata Items）

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