提供手动提示

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

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

  • 关联提供者，以便为属性附加明确的语义，从而使工具可以根据项目的上下文发现潜在值列表。

值提示

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

如果您的属性类型为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支持，这绝对是实现自动完成功能的最有效方法。

值提供者

提供者是一种将语义附加到属性的强大方法。在本节中，我们定义了您可以用于自己的提示的官方提供者。但是，您喜欢的IDE可能实现其中的一些或全部都不实现。此外，它最终可能会提供自己的提供者。

由于这是一项新功能，IDE供应商必须了解其工作原理。采用时间自然会有所不同。

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

名称 描述

any

允许提供任何其他值。

class-reference

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

handle-as

处理属性，就好像它是由target参数定义的类型定义的那样。

logger-name

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

spring-bean-reference

自动完成当前项目中可用的bean名称。通常受target参数指定的基类约束。

spring-profile-name

自动完成项目中可用的Spring配置文件名称。
对于给定的属性，只能有一个提供者处于活动状态，但如果所有提供者都可以以某种方式管理该属性，则可以指定多个提供者。请确保将最强大的提供者放在首位，因为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）

none

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

concrete

boolean

true

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

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

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

Handle As

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

参数 类型 默认值 描述

target

String（Class）

none

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

可以使用以下类型

  • 任何java.lang.Enum：列出属性的可能值。（我们建议使用Enum类型定义属性，因为IDE不需要进一步提示即可自动完成值）

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

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

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

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

如果可以提供多个值，请使用Collection或Array类型来教IDE了解它。

以下元数据片段对应于定义要使用的更改日志路径的标准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提供者自动完成有效的日志记录器名称和日志记录器组。通常，可以自动完成当前项目中可用的包和类名称。如果启用了组（默认值）并且在配置中识别出自定义日志记录器组，则应为其提供自动完成。特定框架可能还具有可以支持的其他魔法日志记录器名称。

此提供者支持以下参数

参数 类型 默认值 描述

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）

none

应分配给候选者的bean类的完全限定名称。通常用于筛选出非候选bean。

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

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

Spring配置文件名称

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

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

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