附录 B.配置元数据

Spring Boot jar 包含元数据文件，这些文件提供了所有受支持的配置属性的详细信息。这些文件旨在让 IDE 开发人员在用户处理application.properties或application.yml文件时提供上下文帮助和“代码完成”。

元数据文件的大部分是在编译时通过处理带有@ConfigurationPropertiesComments 的所有项目自动生成的。但是，对于极端情况或更高级的用例，可以手动编写部分元数据。

B.1 元数据格式

配置元数据文件位于META-INF/spring-configuration-metadata.json下的 jar 内，它们使用简单的 JSON 格式，将项目归类为“组”或“属性”，并将其他 Value hint 归类为“提示”，如以下示例所示：

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

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

server.port=9090
server.address=127.0.0.1

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

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

B.1.1 组属性

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

B.1.2 属性属性

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

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

通过将@DeprecatedConfigurationProperty注解添加到暴露不推荐使用的属性的 getter 中，也可以在代码中以声明方式指定不推荐使用。例如，假设app.acme.target属性令人困惑，并将其重命名为app.acme.name。以下示例显示了如何处理这种情况：

@ConfigurationProperties("app.acme")
public class AcmeProperties {

	private String name;

	public String getName() { ... }

	public void setName(String name) { ... }

	@DeprecatedConfigurationProperty(replacement = "app.acme.name")
	@Deprecated
	public String getTarget() {
		return getName();
	}

	@Deprecated
	public void setTarget(String target) {
		setName(target);
	}
}

前面的代码确保不推荐使用的属性仍然有效(将其委托给幕后的name属性)。一旦可以从您的公共 API 中删除getTarget和setTarget方法，元数据中的自动弃用提示也会消失。如果要保留提示，请添加具有error弃用级别的手动元数据，以确保仍然向用户通知该属性。当提供replacement时，这样做特别有用。

B.1.3 提示属性

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

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

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

B.1.4 重复的元数据项

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

B.2 提供手动提示

为了改善用户体验并进一步帮助用户配置给定属性，您可以提供其他元数据，这些元数据可以：

• 描述属性的潜在值列表。

• 关联提供程序，以将定义良好的语义附加到属性，以便工具可以根据项目的上下文发现潜在值的列表。

B.2.1 Value hint

每个提示的name属性引用属性的name。在前面显示的初始示例中，我们为spring.jpa.hibernate.ddl-auto属性提供了五个值：none，validate，update，create和create-drop。每个值也可以具有描述。

如果您的属性类型为Map，则可以提供键和值的提示(但不提供 Map 本身的提示)。特殊的.keys和.values后缀必须分别指代键和值。

假定sample.contexts将魔术String值 Map 为整数，如以下示例所示：

@ConfigurationProperties("sample")
public class SampleProperties {

	private Map<String,Integer> contexts;
	// getters and setters
}

魔术值(在此示例中)是sample1和sample2。为了提供有关键的其他内容帮助，您可以将以下 JSON 添加到模块的手动元数据：

{"hints": [
	{
		"name": "sample.contexts.keys",
		"values": [
			{
				"value": "sample1"
			},
			{
				"value": "sample2"
			}
		]
	}
]}

B.2.2 Value provider

提供程序是将语义附加到属性的有效方法。在本节中，我们定义了可用于您自己的提示的官方提供程序。但是，您最喜欢的 IDE 可能只实现其中一些，也可能不实现。而且，它最终可以提供自己的。

下表总结了受支持的提供程序的列表：

Any

特殊的“ any **”提供者值允许提供任何其他值。如果支持，则应基于属性类型进行常规值验证。

如果您具有值列表并且任何其他值仍应视为有效，则通常使用此提供程序。

以下示例提供on和off作为system.state的自动完成值：

{"hints": [
	{
		"name": "system.state",
		"values": [
			{
				"value": "on"
			},
			{
				"value": "off"
			}
		],
		"providers": [
			{
				"name": "any"
			}
		]
	}
]}

注意，在前面的示例中，还允许任何其他值。

Class Reference

类别参考提供程序会自动完成项目中可用的类别。该提供程序支持以下参数：

以下元数据片段对应于定义要使用的JspServlet类名称的标准server.servlet.jsp.class-name属性：

{"hints": [
	{
		"name": "server.servlet.jsp.class-name",
		"providers": [
			{
				"name": "class-reference",
				"parameters": {
					"target": "javax.servlet.http.HttpServlet"
				}
			}
		]
	}
]}

Handle As

handle-as 提供程序使您可以将属性的类型替换为更高级的类型。当属性的类型为java.lang.String时，通常会发生这种情况，因为您不希望配置类依赖于可能不在 Classpath 中的类。该提供程序支持以下参数：

可以使用以下类型：

• 任意java.lang.Enum：列出该属性的可能值。 (我们建议使用Enum类型定义属性，因为 IDE 不需要其他提示即可自动完成值.)

• java.nio.charset.Charset：支持字符集/编码值(例如UTF-8)的自动完成

• java.util.Locale：自动完成语言环境(例如en_US)

• org.springframework.util.MimeType：支持 Content Type 值的自动完成(例如text/plain)

• org.springframework.core.io.Resource：支持自动完成 Spring 的 Resource 抽象，以引用文件系统或 Classpath 上的文件。 (例如classpath:/sample.properties)

以下元数据片段对应于标准spring.liquibase.change-log属性，该属性定义要使用的变更日志的路径。实际上，它在内部用作org.springframework.core.io.Resource，但不能这样公开，因为我们需要保留原始的 String 值以将其传递给 Liquibase API。

{"hints": [
	{
		"name": "spring.liquibase.change-log",
		"providers": [
			{
				"name": "handle-as",
				"parameters": {
					"target": "org.springframework.core.io.Resource"
				}
			}
		]
	}
]}

Logger Name

logger-name 提供程序会自动填写有效的 logger 名称和logger groups。通常，可以自动完成当前项目中可用的包和类名。如果启用了组(默认)，并且在配置中标识了自定义记录程序组，则应为其提供自动完成功能。特定框架可能还具有其他可以支持的魔术 Logger 名称。

该提供程序支持以下参数：

由于 Logger 名称可以是任意名称，因此该提供程序应允许使用任何值，但可以突出显示项目的 Classpath 中不可用的有效包和类名称。

以下元数据片段对应于标准logging.level属性。键是* logger 名称*，其值对应于标准日志级别或任何自定义级别。当 Spring Boot 开箱即用地定义一些 Logger 组时，已经为这些 Logger 添加了专用的 Value hint。

{"hints": [
	{
		"name": "logging.level.keys",
		"values": [
			{
				"value": "root",
				"description": "Root logger used to assign the default logging level."
			},
			{
				"value": "sql",
				"description": "SQL logging group including Hibernate SQL logger."
			},
			{
				"value": "web",
				"description": "Web logging group including codecs."
			}
		],
		"providers": [
			{
				"name": "logger-name"
			}
		]
	},
	{
		"name": "logging.level.values",
		"values": [
			{
				"value": "trace"
			},
			{
				"value": "debug"
			},
			{
				"value": "info"
			},
			{
				"value": "warn"
			},
			{
				"value": "error"
			},
			{
				"value": "fatal"
			},
			{
				"value": "off"
			}

		],
		"providers": [
			{
				"name": "any"
			}
		]
	}
]}

Spring Bean 参考

spring-bean-reference 提供程序会自动完成在当前项目的配置中定义的 bean。该提供程序支持以下参数：

以下元数据片段对应于标准spring.jmx.server属性，该属性定义了要使用的MBeanServer bean 的名称：

{"hints": [
	{
		"name": "spring.jmx.server",
		"providers": [
			{
				"name": "spring-bean-reference",
				"parameters": {
					"target": "javax.management.MBeanServer"
				}
			}
		]
	}
]}

Spring Profile 名称

spring-profile-name **提供程序会自动完成在当前项目的配置中定义的 Spring 概要文件。

以下元数据片段对应于标准spring.profiles.active属性，该属性定义了要启用的 Spring 配置文件的名称：

{"hints": [
	{
		"name": "spring.profiles.active",
		"providers": [
			{
				"name": "spring-profile-name"
			}
		]
	}
]}

B.3 使用 Comments 处理器生成您自己的元数据

您可以使用spring-boot-configuration-processor jar 从带有@ConfigurationPropertiesComments 的项目中轻松生成自己的配置元数据文件。该 jar 包含一个 Java Comments 处理器，在您的项目被编译时会被调用。要使用处理器，请包括对spring-boot-configuration-processor的依赖。

使用 Maven，应将依赖项声明为可选，如以下示例所示：

<dependency>
	<groupId>org.springframework.boot</groupId>
	<artifactId>spring-boot-configuration-processor</artifactId>
	<optional>true</optional>
</dependency>

对于 Gradle 4.5 及更早版本，依赖关系应在compileOnly配置中声明，如以下示例所示：

dependencies {
	compileOnly "org.springframework.boot:spring-boot-configuration-processor"
}

在 Gradle 4.6 及更高版本中，依赖性应在annotationProcessor配置中声明，如以下示例所示：

dependencies {
	annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}

如果使用的是additional-spring-configuration-metadata.json文件，则应将compileJava任务配置为取决于processResources任务，如以下示例所示：

compileJava.dependsOn(processResources)

这种依赖性确保 Comments 处理器在编译期间运行时，其他元数据可用。

处理器选择用@ConfigurationPropertiesComments 的类和方法。配置类中字段值的 Javadoc 用于填充description属性。

属性的发现是通过对集合类型进行特殊处理的标准 getter 和 setter 进行的(即使仅存在 getter 也会被检测到)。Comments 处理器还支持使用@Data，@Getter和@Setter lombok Comments。

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<configuration>
		<proc>none</proc>
	</configuration>
</plugin>

B.3.1 嵌套的属性

Comments 处理器自动将内部类视为嵌套属性。考虑以下类别：

@ConfigurationProperties(prefix="server")
public class ServerProperties {

	private String name;

	private Host host;

	// ... getter and setters

	public static class Host {

		private String ip;

		private int port;

		// ... getter and setters

	}

}

前面的示例生成server.name，server.host.ip和server.host.port属性的元数据信息。您可以在字段上使用@NestedConfigurationProperty注解来指示应将常规(非内部)类视为嵌套类。

B.3.2 添加其他元数据

Spring Boot 的配置文件处理非常灵活，通常情况下可能存在未绑定到@ConfigurationProperties bean 的属性。您可能还需要调整现有键的某些属性。为了支持这种情况，并允许您提供自定义的“提示”，Comments 处理器会自动将META-INF/additional-spring-configuration-metadata.json中的项目合并到主元数据文件中。

如果引用了已自动检测到的属性，则如果指定了描述，默认值和弃用信息，则它们将被覆盖。如果当前模块中未标识手动属性声明，则将其添加为新属性。

additional-spring-configuration-metadata.json文件的格式与常规spring-configuration-metadata.json完全相同。附加属性文件是可选的。如果没有任何其他属性，请不要添加文件。