提供手动提示

QWen Max 中英对照 Providing Manual Hints

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

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

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

Value Hint

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

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

假设 my.contexts 将魔法 String 值映射到一个整数，如下例所示：

Java

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

}

Kotlin

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

@ConfigurationProperties("my")
class MyProperties(val contexts: Map<String, Int>)

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

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

提示

我们建议你改用 Enum 来表示这两个值。如果你的 IDE 支持，这无疑是实现自动补全最有效的方法。

Value Providers

Providers 是一种为属性附加语义的强大方式。在本节中，我们定义了你可以用于自己提示（hints）的官方 providers。然而，你所喜爱的 IDE 可能会实现其中一些、全部，或者一个都不实现。此外，它最终也可能提供自己的 providers。

备注

由于这是一个新特性，IDE 厂商需要时间来跟进其工作方式。采用时间自然会有所不同。

下表汇总了支持的提供商列表：

名称	描述
any	允许提供任意额外的值。
class-reference	自动补全项目中可用的类。通常通过 target 参数指定的基类进行约束。
handle-as	将该属性视为由必填参数 target 所定义的类型来处理。
logger-name	自动补全有效的日志记录器名称和 日志记录器组。通常，当前项目中可用的包名、类名以及已定义的组均可自动补全。
spring-bean-reference	自动补全当前项目中可用的 Bean 名称。通常通过 target 参数指定的基类进行约束。
spring-profile-name	自动补全项目中可用的 Spring 配置文件（profile）名称。

提示

对于给定的属性，只能有一个提供者处于激活状态，但如果你指定的多个提供者都能以某种方式管理该属性，则可以列出多个提供者。请务必将功能最强大的提供者放在首位，因为 IDE 必须使用 JSON 部分中它能够处理的第一个提供者。如果给定属性没有任何受支持的提供者，则也不会提供任何特殊的内容辅助。

Any

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

如果有一组值列表，并且任何额外的值仍应被视为有效，则通常使用此 provider。

以下示例为 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：支持 charset/编码值的自动补全（例如 UTF-8）

• Locale：支持 locale 的自动补全（例如 en_US）

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

• Resource：支持 Spring 的 Resource 抽象的自动补全，用于引用文件系统或 classpath 中的文件（例如 classpath:/sample.properties）

提示

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

以下元数据片段对应于标准的 spring.liquibase.change-log 属性，该属性定义了要使用的 changelog 的路径。它在内部实际上被用作 Resource，但不能以 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。通常，当前项目中可用的包名和类名可以被自动补全。如果启用了 groups（默认启用），并且在配置中识别出自定义的 logger group，则应提供该 group 的自动补全。某些特定框架可能还支持额外的“魔法” logger 名称。

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

Parameter	Type	Default value	Description
group	boolean	true	指定是否应考虑已知的组。

由于日志记录器名称可以是任意名称，因此该提供程序应允许任何值，但可以高亮显示那些在项目 classpath 中不可用的有效包名和类名。

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

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

备注

Binder 并不了解元数据。即使你提供了该提示，仍然需要使用 ApplicationContext 将 bean 名称转换为实际的 Bean 引用。

Spring Profile Name

spring-profile-name 提供者会自动补全当前项目配置中定义的 Spring profiles。

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

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