提供手动提示

为了改善用户体验并进一步帮助用户配置给定的属性，你可以提供额外的元数据，这些元数据可以

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

  • 关联一个提供者（provider），以便为属性附加明确定义的语义，这样工具就可以根据项目的上下文发现潜在值的列表。

值提示

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

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

假设一个 my.contexts 将神奇的 String 值映射到一个整数，如下例所示

import java.util.Map;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("my")
public class MyProperties {

	private Map<String, Integer> contexts;

	// getters/setters ...

	public Map<String, Integer> getContexts() {
		return this.contexts;
	}

	public void setContexts(Map<String, Integer> contexts) {
		this.contexts = contexts;
	}

}

这些神奇值（在本例中）是 sample1 和 sample2。为了为键提供额外的上下文辅助，你可以将以下 JSON 添加到该模块的手动元数据中

{"hints": [
	{
		"name": "my.contexts.keys",
		"values": [
			{
				"value": "sample1"
			},
			{
				"value": "sample2"
			}
		]
	}
]}
我们建议你改为对这两个值使用 Enum。如果你的 IDE 支持，这是目前为止最有效的自动完成方法。

值提供者

提供者（Provider）是为属性附加语义的强大方式。在本节中，我们定义了你可以用于自己提示的官方提供者。但是，你喜欢的 IDE 可能实现其中一些或全部，也可能最终提供它自己的提供者。

由于这是一个新特性，IDE 供应商必须跟上它的工作方式。采用时间自然会有所不同。

下表总结了支持的提供者列表

名称 描述

any

允许提供任何额外的值。

class-reference

自动完成项目中可用的类。通常受到 target 参数指定的基类的限制。

handle-as

将属性视为由强制的 target 参数定义的类型所定义。

logger-name

自动完成有效的记录器名称和记录器组。通常，当前项目中可用的包名和类名以及已定义的组都可以自动完成。

spring-bean-reference

自动完成当前项目中可用的 Bean 名称。通常受到 target 参数指定的基类的限制。

spring-profile-name

自动完成项目中可用的 Spring profile 名称。
对于给定的属性，只有一个提供者可以处于活动状态，但是如果它们都可以 以某种方式 管理该属性，你可以指定多个提供者。请确保将最强大的提供者放在首位，因为 IDE 必须使用 JSON 部分中它能处理的第一个。如果给定的属性不支持任何提供者，则也不会提供特殊的上下文辅助。

Any

特殊的 any 提供者值允许提供任何额外的值。如果支持，应应用基于属性类型的常规值验证。

如果你有一个值列表，并且任何额外的值都应被视为有效，通常使用此提供者。

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

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

请注意，在前面的示例中，也允许使用任何其他值。

类引用

class-reference 提供者自动完成项目中可用的类。此提供者支持以下参数

参数 类型 默认值 描述

target

String (Class)

无

应可赋值给所选值的类的完全限定名。通常用于过滤掉非候选类。请注意，此信息可以由类型本身通过公开具有适当上限的类来提供。

concrete

boolean

true

指定是否仅将具体类视为有效候选。

以下元数据片段对应于标准 server.servlet.jsp.class-name 属性，该属性定义了要使用的类名必须是 HttpServlet

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

Handle As

handle-as 提供者允许你将属性的类型替换为更高级别的类型。这通常发生在属性具有 String 类型时，因为你不希望你的配置类依赖于可能不在类路径上的类。此提供者支持以下参数

参数 类型 默认值 描述

target

String (Class)

无

要考虑用于属性的类型的完全限定名。此参数是强制性的。

可以使用以下类型

  • 任何 Enum：列出属性的可能值。（我们建议使用 Enum 类型定义属性，因为 IDE 自动完成值时无需额外提示）

  • Charset：支持自动完成字符集/编码值（例如 UTF-8）

  • Locale：自动完成区域设置（例如 en_US）

  • MimeType：支持自动完成内容类型值（例如 text/plain）

  • Resource：支持自动完成 Spring 的 Resource 抽象，以引用文件系统或类路径上的文件（例如 classpath:/sample.properties）

如果可以提供多个值，请使用 Collection 或 Array 类型来告知 IDE。

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

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

记录器名称

logger-name 提供者自动完成有效的记录器名称和记录器组。通常，当前项目中可用的包名和类名可以自动完成。如果启用了组（默认），并且在配置中识别出了自定义记录器组，则应为其提供自动完成。特定的框架也可能有一些额外的特殊记录器名称可以得到支持。

此提供者支持以下参数

参数 类型 默认值 描述

group

boolean

true

指定是否应考虑已知组。

由于记录器名称可以是任意名称，此提供者应允许任何值，但可以突出显示项目中类路径中不存在的有效包名和类名。

以下元数据片段对应于标准 logging.level 属性。键是 记录器名称，值对应于标准日志级别或任何自定义级别。由于 Spring Boot 开箱即用地定义了一些记录器组，因此已为这些组添加了专门的值提示。

{"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。此提供者支持以下参数

参数 类型 默认值 描述

target

String (Class)

无

应可赋值给候选 Bean 的 Bean 类的完全限定名。通常用于过滤掉非候选 Bean。

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

{"hints": [
	{
		"name": "spring.jmx.server",
		"providers": [
			{
				"name": "spring-bean-reference",
				"parameters": {
					"target": "javax.management.MBeanServer"
				}
			}
		]
	}
]}
绑定器不知道这些元数据。如果你提供了该提示，你仍然需要通过 ApplicationContext 将 Bean 名称转换为实际的 Bean 引用。

Spring Profile 名称

spring-profile-name 提供者自动完成当前项目配置中定义的 Spring profile。

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

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