元数据格式

配置元数据文件位于 JAR 包中 META-INF/spring-configuration-metadata.json 路径下。它们使用 JSON 格式，其中包含按“组”或“属性”分类的项，按“提示”分类的附加值提示，以及按“忽略”分类的被忽略项，如下例所示

{"groups": [
	{
		"name": "server",
		"type": "org.springframework.boot.web.server.autoconfigure.ServerProperties",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.ServerProperties"
	},
	{
		"name": "spring.jpa.hibernate",
		"type": "org.springframework.boot.jpa.autoconfigure.JpaProperties$Hibernate",
		"sourceType": "org.springframework.boot.jpa.autoconfigure.JpaProperties",
		"sourceMethod": "getHibernate()"
	}
	...
],"properties": [
	{
		"name": "server.port",
		"type": "java.lang.Integer",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.ServerProperties"
	},
	{
		"name": "server.address",
		"type": "java.net.InetAddress",
		"sourceType": "org.springframework.boot.web.server.autoconfigure.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.jpa.autoconfigure.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"
		}
		...
	]
}}

每个“属性”是用户指定值的配置项。例如，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

字符串

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

类型

字符串

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

描述

字符串

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

sourceType

字符串

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

sourceMethod

字符串

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

属性属性

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

名称 类型 目的

name

字符串

属性的完整名称。名称采用小写句点分隔形式（例如，server.address）。此属性是强制性的。

类型

字符串

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

描述

字符串

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

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

  • Java

  • Kotlin

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

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

提示属性

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

名称 类型 目的

name

字符串

此提示所指属性的完整名称。名称采用小写句点分隔形式（例如 spring.mvc.servlet.path）。如果属性指的是映射（例如 system.contexts），则提示要么应用于映射的 键（system.contexts.keys），要么应用于映射的 值（system.contexts.values）。此属性是强制性的。

值

ValueHint[]

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

提供者

ValueProvider[]

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

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

名称 类型 目的

价值

对象

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

描述

字符串

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

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

名称 类型 目的

name

字符串

用于为提示所指元素提供附加内容辅助的提供者名称。

parameters

JSON 对象

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

忽略的属性

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

名称 类型 目的

属性

ItemIgnore[]

由 ItemIgnore 对象（在下表中描述）定义的一系列被忽略的属性。每个条目定义被忽略属性的名称。

每个 ignored 元素的 properties 属性中包含的 JSON 对象可以包含下表所示的属性

名称 类型 目的

name

字符串

要忽略的属性的完整名称。名称采用小写句点分隔形式（例如 spring.mvc.servlet.path）。此属性是强制性的。

重复的元数据项

具有相同“属性”和“组”名称的对象可以在元数据文件中多次出现。例如，您可以将两个独立的类绑定到相同的前缀，每个类可能具有重叠的属性名称。尽管元数据中多次出现相同的名称不常见，但元数据的使用者应注意确保它们支持此情况。

© . This site is unofficial and not affiliated with VMware.