配置元数据

1. 元数据格式

配置元数据文件位于 jar 中,位于META-INF/spring-configuration-metadata.json. 它们使用 JSON 格式,其中项分类在“组”或“属性”下,附加值提示分类在“提示”下,如以下示例所示: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."
            }
        ]
    }
]}

每个“属性”都是用户使用给定值指定的配置项。 例如server.portserver.address可能会在application.properties/application.yaml如下:spring-doc.cadn.net.cn

性能
server.port=9090
server.address=127.0.0.1
亚姆尔
server:
  port: 9090
  address: 127.0.0.1

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

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

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

1.1. 组属性

包含在groupsarray 可以包含下表所示的属性: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,则该属性将包含该类的完全限定名称。 如果它基于@Bean方法,它将是该方法的返回类型。 如果类型未知,则可以省略该属性。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. 属性属性

包含在propertiesarray 可以包含下表中描述的属性: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. 当属性具有warningdeprection 级别,它仍然应该绑定在环境中。 但是,当它有一个error弃用级别,则该属性不再受管理且未绑定。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元素。 这仍然以已弃用的方式受支持,不应再使用。 如果没有原因和替换可用,则空deprecation对象。

弃用也可以在代码中声明式指定,方法是将@DeprecatedConfigurationProperty注释给 getter 公开已弃用的属性。 例如,假设my.app.target属性令人困惑,并被重命名为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始终被假定,因为代码仍在处理该属性。

前面的代码确保已弃用的属性仍然有效(委托给name幕后房产)。 一旦getTargetsetTarget可以从公共 API 中删除方法,元数据中的自动弃用提示也会消失。 如果您想保留提示,请使用error弃用级别可确保用户仍了解该属性。 当replacement被提供。spring-doc.cadn.net.cn

1.3. 提示属性

包含在hintsarray 可以包含下表所示的属性: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

价值提示[]spring-doc.cadn.net.cn

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

providersspring-doc.cadn.net.cn

价值提供者[]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,您可以为键和值提供提示(但不能为映射本身提供提示)。 特别的.keys.values后缀必须分别引用键和值。spring-doc.cadn.net.cn

假设一个my.contexts地图魔法String值设置为整数,如以下示例所示: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

处理属性,就像它是由必需的target参数。spring-doc.cadn.net.cn

logger-namespring-doc.cadn.net.cn

自动完成有效的记录器名称和记录器组。通常,当前项目中可用的包和类名称以及定义的组都可以自动完成。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

truespring-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": "javax.servlet.http.HttpServlet"
                }
            }
        ]
    }
]}

2.2.3. 处理为

handle-as 提供程序允许您将属性的类型替换为更高级的类型。 当属性具有java.lang.String类型,因为您不希望配置类依赖于可能不在类路径上的类。 此提供程序支持以下参数: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:列出属性的可能值。 (我们建议使用Enum类型,因为 IDE 不需要进一步的提示来自动完成值)spring-doc.cadn.net.cn

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

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

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

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

如果可以提供多个值,请使用Collection数组类型来向 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 提供程序会自动完成有效的记录器名称和记录器组。 通常,当前项目中可用的包和类名称可以自动完成。 如果启用了组(默认),并且在配置中标识了自定义记录器组,则应为其提供自动完成功能。 特定框架可能也有额外的魔术记录器名称,也可以支持。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

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

以下元数据片段对应于标准logging.level财产。 键是记录器名称,值对应于标准日志级别或任何自定义级别。 由于 Spring Boot 定义了一些开箱即用的记录器组,因此为这些记录器组添加了专用的值提示。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"
                }
            }
        ]
    }
]}
活页夹不知道元数据。 如果您提供该提示,您仍然需要使用ApplicationContext.

2.2.6. 弹簧配置文件名称

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. 使用注释处理器生成您自己的元数据

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

3.1. 配置注释处理器

要使用处理器,请包含对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文件,则compileJava任务应配置为依赖于processResources任务,如以下示例所示:spring-doc.cadn.net.cn

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

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

如果您在项目中使用 AspectJ,则需要确保注释处理器仅运行一次。 有几种方法可以做到这一点。 使用 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 处理器被类路径上可用的依赖项选取,请确保lombok依赖关系在spring-boot-configuration-processorDependency。spring-doc.cadn.net.cn

3.2. 自动元数据生成

处理器选取带有注释的类和方法@ConfigurationProperties.spring-doc.cadn.net.cn

如果类还用@ConstructorBinding,则需要一个构造函数,并且每个构造函数参数创建一个属性。 否则,通过标准 getter 和 setter 的存在来发现属性,这些 getter 和 setter 对集合和映射类型进行了特殊处理(即使仅存在 getter,也会检测到)。 注释处理器还支持使用@Data,@Value,@Getter@Setter龙目岛注释。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 on 字段用于填充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.json文件与常规文件完全相同spring-configuration-metadata.json. 附加属性文件是可选的。 如果没有任何其他属性,请不要添加该文件。spring-doc.cadn.net.cn