提供手动提示

DeepSeek V3 中英对照 Providing Manual Hints

为了提升用户体验并进一步帮助用户配置特定属性，您可以提供以下附加元数据：

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

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

值提示

每个提示的 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;
    }

}

java

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

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

json

提示

我们建议你为这两个值使用 Enum。如果你的 IDE 支持，这无疑是自动补全的最有效方法。

值提供器

Provider 是一种强大的方式，可以为属性附加语义。在本节中，我们定义了你可以用于自己提示的官方 provider。然而，你喜欢的 IDE 可能实现了其中的一些，或者一个也没有实现。此外，它最终可能会提供自己的 provider。

备注

由于这是一个新功能，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"
            }
        ]
    }
]}

json

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

类参考

类引用（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"
                }
            }
        ]
    }
]}

json

处理方式

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 属性，该属性定义了要使用的变更日志的路径。它实际上在内部用作 Resource，但不能直接暴露为资源，因为我们需要保留原始的字符串值以传递给 Liquibase API。

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

json

日志记录器名称

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

json

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

json

备注

绑定器并不知道元数据。即使你提供了这个提示，你仍然需要通过 ApplicationContext 将 bean 名称转换为实际的 Bean 引用。

Spring 配置文件名称

spring-profile-name 提供程序会自动补全当前项目配置中定义的 Spring 配置文件。

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

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

json