配置元数据

1. 元数据格式

配置元数据文件位于 jar 内的META-INF/spring-configuration-metadata.json. 它们使用 JSON 格式,其中项分类在“groups”或“properties”下,其他值提示分类在“hints”下,如以下示例所示:spring-doc.cadn.net.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.address可以在application.properties/application.yaml如下:spring-doc.cadn.net.cn

性能
server.port=9090
server.address=127.0.0.1
Yaml
server:
  port: 9090
  address: 127.0.0.1

“组”是更高级别的项目,它们本身不指定值,而是为属性提供上下文分组。 例如,server.portserver.addressproperties 是server群。spring-doc.cadn.net.cn

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

最后,“提示”是用于帮助用户配置给定属性的附加信息。 例如,当开发人员配置spring.jpa.hibernate.ddl-auto属性中,工具可以使用提示为none,validate,update,createcreate-drop值。spring-doc.cadn.net.cn

1.1. 组属性

包含在groups数组可以包含下表中显示的属性:spring-doc.cadn.net.cn

名字 类型 目的

namespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

typespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

descriptionspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

sourceTypespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

提供此组的源的类名。 例如,如果组基于@Bean方法注释@ConfigurationProperties,则此属性将包含@Configuration类。 如果源类型未知,则可以省略该属性。spring-doc.cadn.net.cn

sourceMethodspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

提供此组的方法的全名(包括括号和参数类型)(例如,一个@ConfigurationProperties注释@Bean方法)。 如果源方法未知,则可以省略它。spring-doc.cadn.net.cn

1.2. 属性属性

包含在properties数组可以包含下表中描述的属性:spring-doc.cadn.net.cn

名字 类型 目的

namespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

属性的全名。 名称采用小写句点分隔形式(例如server.address). 此属性是必需的。spring-doc.cadn.net.cn

typespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

属性数据类型的完整签名(例如java.lang.String),但也是一个完整的泛型类型(例如java.util.Map<java.lang.String,com.example.MyEnum>). 您可以使用此属性来指导用户了解他们可以输入的值类型。 为了保持一致性,原语的类型通过使用其包装器对应项(例如boolean成为java.lang.Boolean). 请注意,此类可能是从String作为值绑定。 如果类型未知,则可以省略。spring-doc.cadn.net.cn

descriptionspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

sourceTypespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

提供此属性的源的类名。 例如,如果属性来自一个带有@ConfigurationProperties,此属性将包含该类的完全限定名称。 如果源类型未知,则可以省略它。spring-doc.cadn.net.cn

defaultValuespring-doc.cadn.net.cn

对象spring-doc.cadn.net.cn

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

deprecationspring-doc.cadn.net.cn

折旧spring-doc.cadn.net.cn

指定是否弃用该属性。 如果该字段未弃用或该信息未知,则可以省略该字段。 下表提供了有关deprecation属性。spring-doc.cadn.net.cn

包含在deprecation每个properties元素可以包含以下属性:spring-doc.cadn.net.cn

名字 类型 目的

levelspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

弃用级别,可以是warning(默认)或error. 当属性具有warningdeprecation 级别,它仍应在环境中绑定。 但是,当它具有errordeprecation 级别,则该属性不再被管理且未绑定。spring-doc.cadn.net.cn

reasonspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

replacementspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

在 Spring Boot 1.3 之前,单个deprecatedboolean 属性代替deprecation元素。 这仍然以已弃用的方式受支持,不应再使用。 如果没有可用的原因和替换项,则为空的deprecationobject 的

弃用也可以在代码中以声明方式指定,方法是将@DeprecatedConfigurationProperty注解传递给 getter 来公开已弃用的属性。 例如,假设my.app.targetproperty 令人困惑,并被重命名为my.app.name. 以下示例显示如何处理这种情况:spring-doc.cadn.net.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;
    }

}
无法设置level.warning始终假定,因为代码仍在处理该属性。

前面的代码确保 deprecated 属性仍然有效(委托给name幕后属性)。 一旦getTargetsetTarget方法可以从你的公共 API 中删除,元数据中的自动弃用提示也会消失。 如果您想保留提示,请使用errordeprecation 级别可确保用户仍会收到有关该属性的信息。 当replacementspring-doc.cadn.net.cn

1.3. Hint 属性

包含在hints数组可以包含下表中显示的属性:spring-doc.cadn.net.cn

名字 类型 目的

namespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

此提示所引用的属性的全名。 名称采用小写句点分隔形式(例如spring.mvc.servlet.path). 如果该属性引用映射(例如system.contexts),则提示将应用于映射 (system.contexts.keys) 或 (system.contexts.values) 中。 此属性是必需的。spring-doc.cadn.net.cn

valuesspring-doc.cadn.net.cn

ValueHint[]spring-doc.cadn.net.cn

ValueHint对象(如下表所述)。 每个条目都定义值,并且可能具有说明。spring-doc.cadn.net.cn

providersspring-doc.cadn.net.cn

ValueProvider[]spring-doc.cadn.net.cn

ValueProvider对象(本文档稍后将介绍)。 每个条目都定义提供程序的名称及其参数(如果有)。spring-doc.cadn.net.cn

包含在values每个hint元素可以包含下表中描述的属性:spring-doc.cadn.net.cn

名字 类型 目的

valuespring-doc.cadn.net.cn

对象spring-doc.cadn.net.cn

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

descriptionspring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

包含在providers每个hint元素可以包含下表中描述的属性:spring-doc.cadn.net.cn

名字 类型 目的

namespring-doc.cadn.net.cn

字符串spring-doc.cadn.net.cn

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

parametersspring-doc.cadn.net.cn

JSON 对象spring-doc.cadn.net.cn

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

1.4. 重复的元数据项

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

2. 提供手动提示

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

2.1. 值提示

name属性引用name的财产。 在前面显示的初始示例中,我们为spring.jpa.hibernate.ddl-auto财产:none,validate,update,createcreate-drop. 每个值也可能具有说明。spring-doc.cadn.net.cn

如果您的属性为Map中,你可以为 key 和 values 提供提示(但不能为 map 本身提供提示)。 特别的.keys.valuessuffixes 必须分别引用 keys 和 values。spring-doc.cadn.net.cn

假设my.contexts地图魔术Stringvalues 设置为 integer,如以下示例所示:spring-doc.cadn.net.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;
    }

}

魔术值是(在此示例中)是sample1sample2. 为了为键提供额外的内容帮助,您可以将以下 JSON 添加到模块的手动元数据中:spring-doc.cadn.net.cn

{"hints": [
    {
        "name": "my.contexts.keys",
        "values": [
            {
                "value": "sample1"
            },
            {
                "value": "sample2"
            }
        ]
    }
]}
我们建议您使用Enum对于这两个值。 如果您的 IDE 支持它,这是迄今为止最有效的自动完成方法。

2.2. 价值提供者

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

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

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

名字 描述

anyspring-doc.cadn.net.cn

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

class-referencespring-doc.cadn.net.cn

自动完成项目中可用的类。 通常由target参数。spring-doc.cadn.net.cn

handle-asspring-doc.cadn.net.cn

处理属性,就好像它是由 mandatory 定义的类型定义的一样target参数。spring-doc.cadn.net.cn

logger-namespring-doc.cadn.net.cn

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

spring-bean-referencespring-doc.cadn.net.cn

自动完成当前项目中的可用 Bean 名称。 通常由target参数。spring-doc.cadn.net.cn

spring-profile-namespring-doc.cadn.net.cn

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

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

2.2.1. 任何

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

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

以下示例提供onoff作为system.state:spring-doc.cadn.net.cn

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

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

2.2.2. 类参考

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

参数 类型 默认值 描述

targetspring-doc.cadn.net.cn

String (Class)spring-doc.cadn.net.cn

没有spring-doc.cadn.net.cn

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

concretespring-doc.cadn.net.cn

booleanspring-doc.cadn.net.cn

spring-doc.cadn.net.cn

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

以下元数据代码片段对应于标准server.servlet.jsp.class-name定义JspServlet要使用的类名:spring-doc.cadn.net.cn

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

2.2.3. 处理为

handle-as 提供程序允许您将属性的类型替换为更高级的类型。 当属性具有java.lang.Stringtype,因为您不希望 configuration 类依赖于可能不在 Classpath 上的类。 此提供程序支持以下参数:spring-doc.cadn.net.cn

参数 类型 默认值 描述

targetspring-doc.cadn.net.cn

String (Class)spring-doc.cadn.net.cn

没有spring-doc.cadn.net.cn

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

可以使用以下类型:spring-doc.cadn.net.cn

  • 任何java.lang.Enum:列出属性的可能值。 (我们建议使用Enumtype,因为 IDE 不需要进一步的提示即可自动完成这些值)spring-doc.cadn.net.cn

  • java.nio.charset.Charset:支持自动完成字符集/编码值(例如UTF-8)spring-doc.cadn.net.cn

  • java.util.Locale:自动完成 locales(例如en_US)spring-doc.cadn.net.cn

  • org.springframework.util.MimeType:支持自动完成内容类型值(如text/plain)spring-doc.cadn.net.cn

  • org.springframework.core.io.Resource:支持自动完成 Spring 的 Resource 抽象,以引用文件系统或 Classpath 上的文件(例如classpath:/sample.properties)spring-doc.cadn.net.cn

如果可以提供多个值,请使用CollectionArray 类型来向 IDE 传授相关信息。

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

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

参数 类型 默认值 描述

groupspring-doc.cadn.net.cn

booleanspring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

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

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

以下元数据代码片段对应于标准logging.level财产。 键是 Logger 名称,值对应于标准日志级别或任何自定义级别。 由于 Spring Boot 定义了一些开箱即用的 Logger 组,因此为这些组添加了专用的值提示。spring-doc.cadn.net.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.cadn.net.cn

参数 类型 默认值 描述

targetspring-doc.cadn.net.cn

String (Class)spring-doc.cadn.net.cn

没有spring-doc.cadn.net.cn

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

以下元数据代码片段对应于标准spring.jmx.server定义MBeanServer要使用的 bean:spring-doc.cadn.net.cn

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

2.2.6. Spring 配置文件名称

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

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

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

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

您可以轻松地从带有@ConfigurationProperties通过使用spring-boot-configuration-processor罐。 该 jar 包括一个 Java 注释处理器,该处理器在编译项目时调用。spring-doc.cadn.net.cn

3.1. 配置 Annotation 处理器

要使用处理器,请包括spring-boot-configuration-processor.spring-doc.cadn.net.cn

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

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

使用 Gradle 时,应在annotationProcessor配置,如以下示例所示:spring-doc.cadn.net.cn

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

如果您使用的是additional-spring-configuration-metadata.json文件中,使用compileJavatask 应配置为依赖于processResources任务,如以下示例所示:spring-doc.cadn.net.cn

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

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

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

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

如果您在项目中使用 Lombok,则需要确保其注释处理器在spring-boot-configuration-processor. 要使用 Maven 执行此作,您可以使用annotationProcessorsMaven 编译器插件的属性。 如果您未使用此属性,并且 Comments 处理器由 Classpath 上可用的依赖项选取,请确保lombokdependency 在spring-boot-configuration-processorDependency。spring-doc.cadn.net.cn

3.2. 自动元数据生成

处理器会选取带有@ConfigurationProperties.spring-doc.cadn.net.cn

如果类具有单个参数化构造函数,则每个构造函数参数将创建一个属性,除非构造函数使用@Autowired. 如果类具有显式注释为@ConstructorBinding,则为该构造函数的每个构造函数参数创建一个属性。 否则,将通过存在标准 getter 和 setter 来发现属性,并对 collection 和 map 类型进行特殊处理(即使仅存在 getter,也会检测到)。 注解处理器还支持使用@Data,@Value,@Getter@Setterlombok 注释。spring-doc.cadn.net.cn

请考虑以下示例:spring-doc.cadn.net.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

这暴露了三个属性,其中my.server.name没有默认值,并且my.server.ipmy.server.port默认为"127.0.0.1"9797分别。 字段上的 Javadoc 用于填充description属性。例如,my.server.ip是 “要侦听的 IP 地址”。spring-doc.cadn.net.cn

您应该只使用@ConfigurationProperties字段 Javadoc,因为它们在添加到 JSON 之前不会进行处理。

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

对于无法检测到默认值的情况,应提供手动元数据。 请考虑以下示例:spring-doc.cadn.net.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.cadn.net.cn

{"properties": [
    {
        "name": "my.messaging.addresses",
        "defaultValue": ["a", "b"]
    },
    {
        "name": "my.messaging.container-type",
        "defaultValue": "simple"
    }
]}
只有name需要记录现有属性的其他元数据。

3.2.1. 嵌套属性

注释处理器会自动将内部类视为嵌套属性。 而不是记录ipport在命名空间的根目录中,我们可以为其创建一个子命名空间。 请考虑更新后的示例:spring-doc.cadn.net.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;
        }

    }

}

前面的示例生成my.server.name,my.server.host.ipmy.server.host.port性能。 您可以使用@NestedConfigurationProperty注解,以指示应将常规(非内部)类视为嵌套类。spring-doc.cadn.net.cn

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

3.3. 添加其他元数据

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

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

additional-spring-configuration-metadata.jsonfile 与常规的spring-configuration-metadata.json. 其他属性文件是可选的。 如果您没有任何其他属性,请不要添加该文件。spring-doc.cadn.net.cn