提供手动提示

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

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

  • 关联一个提供者，为属性附加明确定义的语义，使工具能够基于项目上下文发现潜在值列表。

值提示

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

如果你的属性类型为 Map，你可以分别为键和值提供提示（但不能为整个 map 提供）。 特殊的 .keys 和 .values 后缀分别用于键和值。

假设 my.contexts 将 magic 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;
	}

}

本例中的 magic 值为 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 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 提供者允许你将属性类型替换为更高层次的类型。 这通常发生在属性为 String 类型时，因为你不希望配置类依赖于可能不在 classpath 上的类。 该提供者支持以下参数：

参数 类型 默认值 描述

target

String (Class)

无

要考虑的属性类型的全限定名。 此参数为必填。

可用类型包括：

  • 任何 Enum：列出属性的所有可能值。 （我们建议直接用 Enum 类型定义属性，这样 IDE 可直接自动补全，无需额外提示）

  • Charset：支持编码值（如 UTF-8）的自动补全

  • Locale：支持区域设置（如 en_US）的自动补全

  • MimeType：支持内容类型（如 text/plain）的自动补全

  • Resource：支持 Spring Resource 抽象的自动补全，可引用文件系统或 classpath 上的文件（如 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

指定是否考虑已知分组。

由于日志名称可以是任意名称，该提供者应允许任意值，但可高亮显示项目 classpath 中不可用的有效包名和类名。

以下元数据片段对应标准的 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。

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

{"hints": [
	{
		"name": "spring.jmx.server",
		"providers": [
			{
				"name": "spring-bean-reference",
				"parameters": {
					"target": "javax.management.MBeanServer"
				}
			}
		]
	}
]}
binder 并不了解这些元数据。 如果你提供了该提示，仍需通过 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"
			}
		]
	}
]}