配置元数据

1. 元数据格式

配置元数据文件位于 jar 内的下。它们使用 JSON 格式，其中项分类在“groups”或“properties”下，其他值提示分类在“hints”下，如以下示例所示：META-INF/spring-configuration-metadata.jsonspring-doc.cn

{"groups": [
    {
        "name": "server",
        "type": "org.springframework.boot.autoconfigure.web.ServerProperties",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "spring.jpa.hibernate",
        "type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
        "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
        "sourceMethod": "getHibernate()"
    }
    ...
],"properties": [
    {
        "name": "server.port",
        "type": "java.lang.Integer",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
        "name": "server.address",
        "type": "java.net.InetAddress",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    },
    {
          "name": "spring.jpa.hibernate.ddl-auto",
          "type": "java.lang.String",
          "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
          "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
    }
    ...
],"hints": [
    {
        "name": "spring.jpa.hibernate.ddl-auto",
        "values": [
            {
                "value": "none",
                "description": "Disable DDL handling."
            },
            {
                "value": "validate",
                "description": "Validate the schema, make no changes to the database."
            },
            {
                "value": "update",
                "description": "Update the schema if necessary."
            },
            {
                "value": "create",
                "description": "Create the schema and destroy previous data."
            },
            {
                "value": "create-drop",
                "description": "Create and then destroy the schema at the end of the session."
            }
        ]
    }
]}

每个 “property” 都是用户使用给定值指定的配置项。例如，可以在 / 中指定，如下所示：server.portserver.addressapplication.propertiesapplication.yamlspring-doc.cn

性能

server.port=9090
server.address=127.0.0.1

Yaml

server:
  port: 9090
  address: 127.0.0.1

“组”是更高级别的项目，它们本身不指定值，而是为属性提供上下文分组。例如，和属性是组的一部分。server.portserver.addressserverspring-doc.cn

不要求每个 “property” 都有一个 “group”。某些属性可能本身就存在。

最后，“提示”是用于帮助用户配置给定属性的附加信息。例如，当开发人员配置属性时，工具可以使用提示为、、、和值提供一些自动完成帮助。spring.jpa.hibernate.ddl-autononevalidateupdatecreatecreate-dropspring-doc.cn

1.1. 组属性

数组中包含的 JSON 对象可以包含下表中所示的属性：groupsspring-doc.cn

名字类型目的

名字	类型	目的
`name`spring-doc.cn	字符串spring-doc.cn	组的全名。此属性是必需的。spring-doc.cn
`type`spring-doc.cn	字符串spring-doc.cn	组数据类型的类名。例如，如果组基于一个带有 Comments 的类，则该属性将包含该类的完全限定名称。如果它基于方法，则它将是该方法的返回类型。如果类型未知，则可以省略该属性。`@ConfigurationProperties@Bean`spring-doc.cn
`description`spring-doc.cn	字符串spring-doc.cn	可向用户显示的组的简短描述。如果没有可用的描述，则可以省略它。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。`.`spring-doc.cn
`sourceType`spring-doc.cn	字符串spring-doc.cn	提供此组的源的类名。例如，如果组基于注释有的方法，则此属性将包含包含该方法的类的完全限定名称。如果源类型未知，则可以省略该属性。`@Bean@ConfigurationProperties@Configuration`spring-doc.cn
`sourceMethod`spring-doc.cn	字符串spring-doc.cn	提供此组的方法的全名（包括括号和参数类型）（例如，带批注的方法的名称）。如果源方法未知，则可以省略它。`@ConfigurationProperties@Bean`spring-doc.cn

namespring-doc.cn

字符串spring-doc.cn

组的全名。此属性是必需的。spring-doc.cn

typespring-doc.cn

字符串spring-doc.cn

组数据类型的类名。例如，如果组基于一个带有 Comments 的类，则该属性将包含该类的完全限定名称。如果它基于方法，则它将是该方法的返回类型。如果类型未知，则可以省略该属性。@ConfigurationProperties@Beanspring-doc.cn

descriptionspring-doc.cn

字符串spring-doc.cn

可向用户显示的组的简短描述。如果没有可用的描述，则可以省略它。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。.spring-doc.cn

sourceTypespring-doc.cn

字符串spring-doc.cn

提供此组的源的类名。例如，如果组基于注释有的方法，则此属性将包含包含该方法的类的完全限定名称。如果源类型未知，则可以省略该属性。@Bean@ConfigurationProperties@Configurationspring-doc.cn

sourceMethodspring-doc.cn

字符串spring-doc.cn

提供此组的方法的全名（包括括号和参数类型）（例如，带批注的方法的名称）。如果源方法未知，则可以省略它。@ConfigurationProperties@Beanspring-doc.cn

1.2. 属性属性

数组中包含的 JSON 对象可以包含下表中描述的属性：propertiesspring-doc.cn

名字类型目的

名字	类型	目的
`name`spring-doc.cn	字符串spring-doc.cn	属性的全名。名称采用小写句点分隔形式（例如）。此属性是必需的。`server.address`spring-doc.cn
`type`spring-doc.cn	字符串spring-doc.cn	属性数据类型的完整签名（例如），但也是一个完整的泛型类型（如）。您可以使用此属性来指导用户了解他们可以输入的值类型。为了保持一致性，通过使用其包装器对应项（例如，变为）来指定基元的类型。请注意，此类可能是在绑定值时从 a 转换而来的复杂类型。如果类型未知，则可以省略。`java.lang.Stringjava.util.Map<java.lang.String,com.example.MyEnum>booleanjava.lang.BooleanString`spring-doc.cn
`description`spring-doc.cn	字符串spring-doc.cn	可向用户显示的属性的简短说明。如果没有可用的描述，则可以省略它。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。`.`spring-doc.cn
`sourceType`spring-doc.cn	字符串spring-doc.cn	提供此属性的源的类名。例如，如果属性来自注释有的类，则此属性将包含该类的完全限定名称。如果源类型未知，则可以省略它。`@ConfigurationProperties`spring-doc.cn
`defaultValue`spring-doc.cn	对象spring-doc.cn	默认值，如果未指定属性，则使用该值。如果属性的类型是数组，它可以是值的数组。如果默认值未知，则可以省略它。spring-doc.cn
`deprecation`spring-doc.cn	折旧spring-doc.cn	指定是否弃用该属性。如果该字段未弃用或该信息未知，则可以省略该字段。下表提供了有关该属性的更多详细信息。`deprecation`spring-doc.cn

namespring-doc.cn

字符串spring-doc.cn

属性的全名。名称采用小写句点分隔形式（例如）。此属性是必需的。server.addressspring-doc.cn

typespring-doc.cn

字符串spring-doc.cn

属性数据类型的完整签名（例如），但也是一个完整的泛型类型（如）。您可以使用此属性来指导用户了解他们可以输入的值类型。为了保持一致性，通过使用其包装器对应项（例如，变为）来指定基元的类型。请注意，此类可能是在绑定值时从 a 转换而来的复杂类型。如果类型未知，则可以省略。java.lang.Stringjava.util.Map<java.lang.String,com.example.MyEnum>booleanjava.lang.BooleanStringspring-doc.cn

descriptionspring-doc.cn

字符串spring-doc.cn

可向用户显示的属性的简短说明。如果没有可用的描述，则可以省略它。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。.spring-doc.cn

sourceTypespring-doc.cn

字符串spring-doc.cn

提供此属性的源的类名。例如，如果属性来自注释有的类，则此属性将包含该类的完全限定名称。如果源类型未知，则可以省略它。@ConfigurationPropertiesspring-doc.cn

defaultValuespring-doc.cn

对象spring-doc.cn

默认值，如果未指定属性，则使用该值。如果属性的类型是数组，它可以是值的数组。如果默认值未知，则可以省略它。spring-doc.cn

deprecationspring-doc.cn

折旧spring-doc.cn

指定是否弃用该属性。如果该字段未弃用或该信息未知，则可以省略该字段。下表提供了有关该属性的更多详细信息。deprecationspring-doc.cn

每个元素的属性中包含的 JSON 对象可以包含以下属性：deprecationpropertiesspring-doc.cn

名字类型目的

名字	类型	目的
`level`spring-doc.cn	字符串spring-doc.cn	弃用级别，可以是（默认）或。当属性具有弃用级别时，它仍应在环境中绑定。但是，当它具有弃用级别时，该属性将不再被管理，也不会被绑定。`warningerrorwarningerror`spring-doc.cn
`reason`spring-doc.cn	字符串spring-doc.cn	弃用属性的原因的简短描述。如果没有可用的原因，则可以省略。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。`.`spring-doc.cn
`replacement`spring-doc.cn	字符串spring-doc.cn	替换此已弃用属性的属性的全名。如果此属性没有替代项，则可以省略它。spring-doc.cn

levelspring-doc.cn

字符串spring-doc.cn

弃用级别，可以是（默认）或。当属性具有弃用级别时，它仍应在环境中绑定。但是，当它具有弃用级别时，该属性将不再被管理，也不会被绑定。warningerrorwarningerrorspring-doc.cn

reasonspring-doc.cn

字符串spring-doc.cn

弃用属性的原因的简短描述。如果没有可用的原因，则可以省略。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。.spring-doc.cn

replacementspring-doc.cn

字符串spring-doc.cn

替换此已弃用属性的属性的全名。如果此属性没有替代项，则可以省略它。spring-doc.cn

在 Spring Boot 1.3 之前，可以使用单个 boolean 属性来代替元素。这仍然以已弃用的方式受支持，不应再使用。如果没有可用的 reason 和 replacement，则应设置一个空对象。deprecateddeprecationdeprecation

还可以通过将注释添加到公开已弃用属性的 getter 中，在代码中以声明方式指定弃用。例如，假设该属性令人困惑，并已重命名为 . 以下示例显示如何处理这种情况：@DeprecatedConfigurationPropertymy.app.targetmy.app.namespring-doc.cn

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

@ConfigurationProperties("my.app")
public class MyProperties {

    private String name;

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    @Deprecated
    @DeprecatedConfigurationProperty(replacement = "my.app.name")
    public String getTarget() {
        return this.name;
    }

    @Deprecated
    public void setTarget(String target) {
        this.name = target;
    }

}

无法设置 . 始终假定，因为代码仍在处理该属性。levelwarning

前面的代码确保已弃用的属性仍然有效（委托给幕后的属性）。一旦可以从公共 API 中删除 and 方法，元数据中的自动弃用提示也会消失。如果要保留提示，请添加具有弃用级别的手动元数据，以确保用户仍能了解该属性。当提供 a 时，这样做特别有用。namegetTargetsetTargeterrorreplacementspring-doc.cn

1.3. Hint 属性

数组中包含的 JSON 对象可以包含下表中所示的属性：hintsspring-doc.cn

名字类型目的

名字	类型	目的
`name`spring-doc.cn	字符串spring-doc.cn	此提示所引用的属性的全名。名称采用小写句点分隔形式（如）。如果属性引用 map （例如），则提示适用于 map （）的键或 map 的值（）。此属性是必需的。`spring.mvc.servlet.pathsystem.contextssystem.contexts.keyssystem.contexts.values`spring-doc.cn
`values`spring-doc.cn	ValueHint[]spring-doc.cn	对象定义的有效值列表（如下表所述）。每个条目都定义值，并且可能具有说明。`ValueHint`spring-doc.cn
`providers`spring-doc.cn	ValueProvider[]spring-doc.cn	由对象定义的提供程序列表（本文档稍后将介绍）。每个条目都定义提供程序的名称及其参数（如果有）。`ValueProvider`spring-doc.cn

namespring-doc.cn

字符串spring-doc.cn

此提示所引用的属性的全名。名称采用小写句点分隔形式（如）。如果属性引用 map （例如），则提示适用于 map （）的键或 map 的值（）。 此属性是必需的。spring.mvc.servlet.pathsystem.contextssystem.contexts.keyssystem.contexts.valuesspring-doc.cn

valuesspring-doc.cn

ValueHint[]spring-doc.cn

对象定义的有效值列表（如下表所述）。每个条目都定义值，并且可能具有说明。ValueHintspring-doc.cn

providersspring-doc.cn

ValueProvider[]spring-doc.cn

由对象定义的提供程序列表（本文档稍后将介绍）。每个条目都定义提供程序的名称及其参数（如果有）。ValueProviderspring-doc.cn

每个元素的属性中包含的 JSON 对象可以包含下表中描述的属性：valueshintspring-doc.cn

名字类型目的

名字	类型	目的
`value`spring-doc.cn	对象spring-doc.cn	提示引用的元素的有效值。如果属性的类型是数组，则它也可以是值的数组。此属性是必需的。spring-doc.cn
`description`spring-doc.cn	字符串spring-doc.cn	可向用户显示的值的简短描述。如果没有可用的描述，则可以省略它。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。`.`spring-doc.cn

valuespring-doc.cn

对象spring-doc.cn

提示引用的元素的有效值。如果属性的类型是数组，则它也可以是值的数组。此属性是必需的。spring-doc.cn

descriptionspring-doc.cn

字符串spring-doc.cn

可向用户显示的值的简短描述。如果没有可用的描述，则可以省略它。建议描述为简短的段落，第一行提供简明的摘要。描述中的最后一行应以句点（）结尾。.spring-doc.cn

每个元素的属性中包含的 JSON 对象可以包含下表中描述的属性：providershintspring-doc.cn

名字类型目的

名字	类型	目的
`name`spring-doc.cn	字符串spring-doc.cn	用于为提示引用的元素提供其他内容帮助的提供程序的名称。spring-doc.cn
`parameters`spring-doc.cn	JSON 对象spring-doc.cn	提供程序支持的任何其他参数（有关更多详细信息，请查看提供程序的文档）。spring-doc.cn

namespring-doc.cn

字符串spring-doc.cn

用于为提示引用的元素提供其他内容帮助的提供程序的名称。spring-doc.cn

parametersspring-doc.cn

JSON 对象spring-doc.cn

提供程序支持的任何其他参数（有关更多详细信息，请查看提供程序的文档）。spring-doc.cn

1.4. 重复的元数据项

具有相同“属性”和“组”名称的对象可以在元数据文件中多次出现。例如，可以将两个单独的类绑定到同一前缀，每个类都具有可能重叠的属性名称。虽然元数据中多次出现的相同名称应该不常见，但元数据的使用者应注意确保他们支持它。spring-doc.cn

2. 提供手动提示

为了改善用户体验并进一步帮助用户配置给定属性，您可以提供其他元数据，以便：spring-doc.cn

描述属性的可能值列表。spring-doc.cn
关联提供程序，以将定义完善的语义附加到属性，以便工具可以根据项目的上下文发现潜在值的列表。spring-doc.cn

2.1. 值提示

每个 hint 的 attribute 都引用 property 的。在前面显示的初始示例中，我们为属性提供了五个值：、、、和。每个值也可能具有说明。namenamespring.jpa.hibernate.ddl-autononevalidateupdatecreatecreate-dropspring-doc.cn

如果您的 property 是 type ，则可以为键和值提供提示（但不能为映射本身提供提示）。 special 和 suffixes 必须分别引用 keys 和 values。Map.keys.valuesspring-doc.cn

假设将 magic values 映射到整数，如以下示例所示：my.contextsStringspring-doc.cn

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

}

魔术值是（在此示例中）是和。为了为键提供额外的内容帮助，您可以将以下 JSON 添加到模块的手动元数据中：sample1sample2spring-doc.cn

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

我们建议您改用 for 这两个值。如果您的 IDE 支持它，这是迄今为止最有效的自动完成方法。Enum

2.2. 价值提供者

提供程序是将语义附加到属性的有效方法。在本节中，我们定义了可用于您自己的提示的官方提供程序。但是，您最喜欢的 IDE 可能会实现其中的一些，或者没有实现。此外，它最终可能会提供自己的服务。spring-doc.cn

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

下表总结了支持的提供程序列表：spring-doc.cn

名字描述

名字	描述
`any`spring-doc.cn	允许提供任何其他值。spring-doc.cn
`class-reference`spring-doc.cn	自动完成项目中可用的类。通常由参数指定的基类约束。`target`spring-doc.cn
`handle-as`spring-doc.cn	处理属性，就好像它是由 mandatory 参数定义的类型定义的一样。`target`spring-doc.cn
`logger-name`spring-doc.cn	自动完成有效的 Logger 名称和 Logger 组。通常，当前项目中可用的包名和类名可以自动完成，也可以定义组。spring-doc.cn
`spring-bean-reference`spring-doc.cn	自动完成当前项目中的可用 Bean 名称。通常由参数指定的基类约束。`target`spring-doc.cn
`spring-profile-name`spring-doc.cn	自动完成项目中可用的 Spring 配置文件名称。spring-doc.cn

anyspring-doc.cn

允许提供任何其他值。spring-doc.cn

class-referencespring-doc.cn

自动完成项目中可用的类。通常由参数指定的基类约束。targetspring-doc.cn

handle-asspring-doc.cn

处理属性，就好像它是由 mandatory 参数定义的类型定义的一样。targetspring-doc.cn

logger-namespring-doc.cn

自动完成有效的 Logger 名称和 Logger 组。通常，当前项目中可用的包名和类名可以自动完成，也可以定义组。spring-doc.cn

spring-bean-referencespring-doc.cn

自动完成当前项目中的可用 Bean 名称。通常由参数指定的基类约束。targetspring-doc.cn

spring-profile-namespring-doc.cn

自动完成项目中可用的 Spring 配置文件名称。spring-doc.cn

对于给定属性，只能有一个提供程序处于活动状态，但如果它们都可以以某种方式管理该属性，则可以指定多个提供程序。确保将最强大的提供程序放在最前面，因为 IDE 必须使用 JSON 部分中它可以处理的第一个提供程序。如果不支持给定属性的提供程序，则也不会提供特殊内容帮助。

2.2.1. 任何

特殊的 any provider 值允许提供任何其他值。如果支持，则应应用基于属性类型的常规值验证。spring-doc.cn

如果您有值列表，并且任何额外的值仍应被视为有效，则通常使用此提供程序。spring-doc.cn

以下示例提供和作为 auto-completion 值：onoffsystem.statespring-doc.cn

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

请注意，在前面的示例中，还允许任何其他值。spring-doc.cn

2.2.2. 类参考

类引用提供程序会自动完成项目中可用的类。此提供程序支持以下参数：spring-doc.cn

参数类型默认值描述

参数	类型	默认值	描述
`target`spring-doc.cn	`String` (`Class`)spring-doc.cn	没有spring-doc.cn	应分配给所选值的类的完全限定名称。通常用于筛选出非候选类。请注意，此信息可以由类型本身通过公开具有适当上限的类来提供。spring-doc.cn
`concrete`spring-doc.cn	`boolean`spring-doc.cn	真spring-doc.cn	指定是否仅将具体类视为有效候选项。spring-doc.cn

targetspring-doc.cn

String (Class)spring-doc.cn

没有spring-doc.cn

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

concretespring-doc.cn

booleanspring-doc.cn

真spring-doc.cn

指定是否仅将具体类视为有效候选项。spring-doc.cn

以下元数据代码片段对应于定义要使用的类名的标准属性：server.servlet.jsp.class-nameJspServletspring-doc.cn

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

2.2.3. 处理为

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

参数类型默认值描述

参数	类型	默认值	描述
`target`spring-doc.cn	`String` (`Class`)spring-doc.cn	没有spring-doc.cn	要为属性考虑的类型的完全限定名称。此参数为必填项。spring-doc.cn

targetspring-doc.cn

String (Class)spring-doc.cn

没有spring-doc.cn

要为属性考虑的类型的完全限定名称。此参数为必填项。spring-doc.cn

可以使用以下类型：spring-doc.cn

任意：列出属性的可能值。（我们建议使用类型定义属性，因为 IDE 不需要进一步的提示即可自动完成值）java.lang.EnumEnumspring-doc.cn
java.nio.charset.Charset：支持自动完成字符集/编码值（例如UTF-8)spring-doc.cn
java.util.Locale：自动完成 locales（例如en_US)spring-doc.cn
org.springframework.util.MimeType：支持自动完成内容类型值（如text/plain)spring-doc.cn
org.springframework.core.io.Resource：支持自动完成 Spring 的 Resource 抽象，以引用文件系统或 Classpath 上的文件（例如classpath:/sample.properties)spring-doc.cn

如果可以提供多个值，请使用或 Array 类型向 IDE 传授有关该值的信息。Collection

以下元数据代码片段对应于定义要使用的更改日志路径的标准属性。它实际上在内部用作 a，但不能作为 a 公开，因为我们需要保留原始的 String 值以将其传递给 Liquibase API。spring.liquibase.change-logorg.springframework.core.io.Resourcespring-doc.cn

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

2.2.4. 记录器名称

logger-name 提供程序会自动完成有效的 Logger 名称和 Logger 组。通常，当前项目中可用的包和类名称可以自动完成。如果启用了组（默认），并且在配置中标识了自定义 logger 组，则应为其提供自动完成。特定框架可能具有额外的 magic logger 名称，也可以支持这些名称。spring-doc.cn

此提供程序支持以下参数：spring-doc.cn

参数类型默认值描述

参数	类型	默认值	描述
`group`spring-doc.cn	`boolean`spring-doc.cn	`true`spring-doc.cn	指定是否应考虑已知组。spring-doc.cn

groupspring-doc.cn

booleanspring-doc.cn

truespring-doc.cn

指定是否应考虑已知组。spring-doc.cn

由于 Logger 名称可以是任意名称，因此此提供程序应允许任何值，但可以突出显示项目 Classpath 中不可用的有效包和类名称。spring-doc.cn

以下元数据代码片段对应于 standard 属性。键是 Logger 名称，值对应于标准日志级别或任何自定义级别。由于 Spring Boot 定义了一些开箱即用的 Logger 组，因此为这些组添加了专用的值提示。logging.levelspring-doc.cn

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

2.2.5. Spring Bean 参考

spring-bean-reference 提供程序自动完成在当前项目的配置中定义的 bean。此提供程序支持以下参数：spring-doc.cn

参数类型默认值描述

参数	类型	默认值	描述
`target`spring-doc.cn	`String` (`Class`)spring-doc.cn	没有spring-doc.cn	应分配给候选项的 Bean 类的完全限定名称。通常用于过滤掉非候选 bean。spring-doc.cn

targetspring-doc.cn

String (Class)spring-doc.cn

没有spring-doc.cn

应分配给候选项的 Bean 类的完全限定名称。通常用于过滤掉非候选 bean。spring-doc.cn

以下元数据代码片段对应于定义要使用的 bean 名称的标准属性：spring.jmx.serverMBeanServerspring-doc.cn

{"hints": [
    {
        "name": "spring.jmx.server",
        "providers": [
            {
                "name": "spring-bean-reference",
                "parameters": {
                    "target": "javax.management.MBeanServer"
                }
            }
        ]
    }
]}

Binder 不知道元数据。如果提供该提示，则仍需要使用 .ApplicationContext

2.2.6. Spring 配置文件名称

spring-profile-name 提供程序自动完成在当前项目的配置中定义的 Spring 配置文件。spring-doc.cn

以下元数据代码片段对应于定义要启用的 Spring 配置文件名称的标准属性：spring.profiles.activespring-doc.cn

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

3. 使用 Annotation Processor 生成您自己的元数据

您可以使用 jar 轻松地从带有 Comments 的项生成自己的配置元数据文件。该 jar 包括一个 Java 注释处理器，该处理器在编译项目时调用。@ConfigurationPropertiesspring-boot-configuration-processorspring-doc.cn

3.1. 配置 Annotation 处理器

要使用处理器，请包含对的依赖项。spring-boot-configuration-processorspring-doc.cn

使用 Maven 时，依赖项应声明为可选，如以下示例所示：spring-doc.cn

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

使用 Gradle 时，应在配置中声明依赖项，如以下示例所示：annotationProcessorspring-doc.cn

dependencies {
    annotationProcessor "org.springframework.boot:spring-boot-configuration-processor"
}

如果您使用的是文件，则应将任务配置为依赖于该任务，如以下示例所示：additional-spring-configuration-metadata.jsoncompileJavaprocessResourcesspring-doc.cn

tasks.named('compileJava') {
    inputs.files(tasks.named('processResources'))
}

此依赖关系可确保在编译期间 Comments 处理器运行时其他元数据可用。spring-doc.cn

如果你在你的项目中使用 AspectJ，你需要确保 Comments 处理器只运行一次。有几种方法可以做到这一点。使用 Maven，您可以显式配置，并仅在其中将依赖项添加到注释处理器。你也可以让 AspectJ 插件运行所有处理并在配置中禁用 Comments 处理，如下所示：maven-apt-pluginmaven-compiler-pluginspring-doc.cn

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <proc>none</proc>
    </configuration>
</plugin>

如果您在项目中使用 Lombok，则需要确保其注释处理器在 . 要使用 Maven 执行此操作，您可以使用 Maven 编译器插件的属性以正确的顺序列出 Annotation 处理器。如果您未使用此属性，并且 Comments 处理器由 Classpath 上可用的依赖项选取，请确保在依赖项之前定义依赖项。spring-boot-configuration-processorannotationProcessorslombokspring-boot-configuration-processorspring-doc.cn

3.2. 自动元数据生成

处理器会选取带有 .@ConfigurationPropertiesspring-doc.cn

如果类还使用进行批注，则需要一个构造函数，并且每个构造函数参数创建一个属性。否则，将通过存在标准 getter 和 setter 来发现属性，并对 collection 和 map 类型进行特殊处理（即使仅存在 getter，也会检测到）。注解处理器还支持使用、、和 lombok 注解。@ConstructorBinding@Data@Value@Getter@Setterspring-doc.cn

请考虑以下示例：spring-doc.cn

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

@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {

    /**
     * Name of the server.
     */
    private String name;

    /**
     * IP address to listen to.
     */
    private String ip = "127.0.0.1";

    /**
     * Port to listener to.
     */
    private int port = 9797;

    // getters/setters ...

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getIp() {
        return this.ip;
    }

    public void setIp(String ip) {
        this.ip = ip;
    }

    public int getPort() {
        return this.port;
    }

    public void setPort(int port) {
        this.port = port;
    }
    // fold:off

这暴露了三个属性，其中 has no default 和 defaults to 分别是和。字段上的 Javadoc 用于填充属性。例如，的描述是 “IP address to listen to.”。my.server.namemy.server.ipmy.server.port"127.0.0.1"9797descriptionmy.server.ipspring-doc.cn

您应该只使用带有字段 Javadoc 的纯文本，因为它们在添加到 JSON 之前不会进行处理。@ConfigurationProperties

注释处理器应用许多启发式方法从源模型中提取默认值。默认值必须静态提供。特别是，不要引用在另一个类中定义的常量。此外，注释处理器无法自动检测 s 和 s 的默认值。EnumCollectionsspring-doc.cn

对于无法检测到默认值的情况，应提供手动元数据。请考虑以下示例：spring-doc.cn

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;

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

@ConfigurationProperties(prefix = "my.messaging")
public class MyMessagingProperties {

    private List<String> addresses = new ArrayList<>(Arrays.asList("a", "b"));

    private ContainerType containerType = ContainerType.SIMPLE;

    // getters/setters ...

    public List<String> getAddresses() {
        return this.addresses;
    }

    public void setAddresses(List<String> addresses) {
        this.addresses = addresses;
    }

    public ContainerType getContainerType() {
        return this.containerType;
    }

    public void setContainerType(ContainerType containerType) {
        this.containerType = containerType;
    }

    public enum ContainerType {

        SIMPLE, DIRECT

    }

}

为了记录上述类中属性的默认值，您可以将以下内容添加到模块的手动元数据中：spring-doc.cn

{"properties": [
    {
        "name": "my.messaging.addresses",
        "defaultValue": ["a", "b"]
    },
    {
        "name": "my.messaging.container-type",
        "defaultValue": "simple"
    }
]}

只有 of the property 需要记录现有属性的其他元数据。name

3.2.1. 嵌套属性

注释处理器会自动将内部类视为嵌套属性。我们可以为它创建一个子命名空间，而不是在命名空间的根目录下记录 and。请考虑更新后的示例：ipportspring-doc.cn

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

@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {

    private String name;

    private Host host;

    // getters/setters ...

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public Host getHost() {
        return this.host;
    }

    public void setHost(Host host) {
        this.host = host;
    }

    public static class Host {

        private String ip;

        private int port;

        // getters/setters ...

        public String getIp() {
            return this.ip;
        }

        public void setIp(String ip) {
            this.ip = ip;
        }

        public int getPort() {
            return this.port;
        }

        public void setPort(int port) {
            this.port = port;
        }

    }

}

前面的示例生成、和属性的元数据信息。您可以在字段上使用 Comments 来指示应将常规（非内部）类视为嵌套类。my.server.namemy.server.host.ipmy.server.host.port@NestedConfigurationPropertyspring-doc.cn

这对集合和映射没有影响，因为这些类型是自动识别的，并且会为每个类型生成一个元数据属性。

3.3. 添加其他元数据

Spring Boot 的配置文件处理非常灵活，并且通常存在未绑定到 bean 的属性。您可能还需要调整现有键的某些属性。为了支持此类情况并让您提供自定义“提示”，注释处理器会自动将项目合并到主元数据文件中。@ConfigurationPropertiesMETA-INF/additional-spring-configuration-metadata.jsonspring-doc.cn

如果引用已自动检测到的属性，则描述、默认值和弃用信息（如果指定）将被覆盖。如果在当前模块中未标识手动属性声明，则会将其添加为新属性。spring-doc.cn

文件的格式与常规 . 其他属性文件是可选的。如果您没有任何其他属性，请不要添加该文件。additional-spring-configuration-metadata.jsonspring-configuration-metadata.jsonspring-doc.cn