Spring Boot jar包含元数据文件,这些文件提供了所有受支持的配置属性的详细信息. 这些文件旨在让IDE开发人员在用户使用 application.properties 或 application.yml 文件时提供上下文帮助和 "代码完成".

元数据文件的大部分是在编译时通过处理所有用 @ConfigurationProperties 注解的项目自动生成的. 但是,对于极端情况或更高级的用例,可以手动编写部分元数据 .

1. Metadata 格式

配置元数据文件位于 META-INF/spring-configuration-metadata.json 下的jar中. 他们使用简单的JSON格式,将项目归类为 “groups” 或 “properties” ,并将其他值提示归类为 "hints",如以下示例所示:

{"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” 都是用户使用给定值指定的配置项. 例如,可以在 application.properties 中指定 server.port 和 server.address,如下所示:

server.port=9090
server.address=127.0.0.1

“groups” 是更高级别的条目,它们本身并不指定值,而是提供属性的上下文分组. 例如,server.port 和 server.address 属性是服务器组的一部分.

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

最后, “hints” 是用于帮助用户配置给定属性的其他信息. 例如,当开发人员配置 spring.jpa.hibernate.ddl-auto 属性时,工具可以使用提示 none, validate, update, create 和 create-drop 值 .

1.1. Group 属性

groups 数组中包含的JSON对象可以包含下表中显示的属性:

名称 类型 用意

name

String

组的全名. 此属性是必需的.

type

String

组数据类型的类名. 例如,如果组基于带 @ConfigurationProperties 注解的类,则该属性将包含该类的完全限定名称. 如果基于 @Bean 方法,则它将是该方法的返回类型. 如果类型未知,则可以省略该属性.

description

String

可以显示给用户的组的简短描述. 如果没有可用的描述,则可以省略. 建议使用简短的描述,第一行提供简要的摘要. 说明中的最后一行应以句点(.) 结尾.

sourceType

String

贡献此组的源的类名. 例如,如果组基于 @Bean 方法并带有 @ConfigurationProperties 注解,则此属性将包含包含该方法的 @Configuration 类的完全限定名称. 如果源类型未知,则可以省略该属性.

sourceMethod

String

贡献此组的方法的全名(包括括号和参数类型) (例如,带 @ConfigurationProperties 注解的 @Bean 方法的名称) .

1.2. Property 属性

properties 数组中包含的JSON对象可以包含下表中描述的属性:

名称 类型 用意

name

String

属性的全名. 名称以小写的句点分隔(例如,server.address) . 此属性是必需的.

type

String

属性的数据类型的完整签名(例如,java.lang.String) ,还具有完整的泛型类型(例如,java.util.Map<java.lang.String,acme.MyEnum>) . 您可以使用此属性指导用户输入的值的类型. 为了保持一致性,通过使用包装的对应对象来指定基元的类型(例如,boolean 变为 java.lang.Boolean) . 请注意,此类可能是一个复杂的类型,当绑定值时,它会从 String 转换而来. 如果类型未知,则可以省略.

description

String

可以显示给用户的属性的简短描述. 如果没有可用的描述,则可以省略. 建议使用简短的描述,第一行提供简要的摘要. 说明中的最后一行应以句点(.) 结尾.

sourceType

String

贡献此属性的源的类名. 例如,如果属性来自带有 @ConfigurationProperties 注解的类,则此属性将包含该类的完全限定名称. 如果源类型未知,则可以省略.

defaultValue

Object

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

deprecation

Deprecation

指定是否不推荐使用该属性. 如果不建议使用该字段,或者该信息未知,则可以将其省略. 下表提供了有关 deprecation 属性的更多详细信息.

每个 properties 元素的 deprecation 属性中包含的JSON对象可以包含以下属性:

名称 类型 用意

level

String

弃用级别,可以是警告(默认) 或错误. 当某个属性具有警告弃用级别时,它仍应绑定在环境中. 但是,当它具有错误弃用级别时,该属性将不再受管理且未绑定.

reason

String

对不推荐使用该属性的原因的简短描述. 如果没有任何理由,则可以省略. 建议使用简短的描述,第一行提供简要的摘要. 说明中的最后一行应以句点(.) 结尾.

replacement

String

替换此不推荐使用的属性的属性的全名. 如果无法替代此属性,则可以省略.
在Spring Boot 1.3之前,可以使用单个 deprecated 使用的布尔属性来代替 deprecation 元素. 仍然以不推荐的方式支持此功能,并且不应再使用它. 如果没有原因和可用的替代方法,则应设置一个空的 deprecation 对象.

也可以在代码中以声明方式指定弃用,方法是将 @DeprecatedConfigurationProperty 注解添加到暴露弃用属性的getter中. 例如,假设 app.acme.target 属性令人困惑,并将其重命名为 app.acme.name. 以下示例显示了如何处理这种情况:

@ConfigurationProperties("app.acme")
public class AcmeProperties {

    private String name;

    public String getName() { ... }

    public void setName(String name) { ... }

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

    @Deprecated
    public void setTarget(String target) {
        setName(target);
    }
}
无法设置级别. 由于代码仍在处理该属性,因此始终 warning .

前面的代码确保不推荐使用的属性仍然有效(将其委托给幕后的name属性) . 一旦可以从公共API中删除 getTarget 和 setTarget 方法,元数据中的自动弃用提示也将消失. 如果要保留提示,请添加具有错误弃用级别的手动元数据,以确保仍然向用户通知该属性. 进行替换时,这样做特别有用.

1.3. Hint 属性

hints 数组中包含的JSON对象可以包含下表中显示的属性:

名称 类型 用意

name

String

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

values

ValueHint[]

由 ValueHint 对象定义的有效值列表(如下表所述) . 每个条目都定义该值,并且可以具有描述.

providers

ValueProvider[]

由 ValueProvider 对象定义的提供者列表(在本文档的后面介绍) . 每个条目定义提供者的名称及其参数(如果有) .

每个 hint 元素的 values 属性中包含的JSON对象可以包含下表中描述的属性:

名称 类型 用意

value

Object

提示所引用元素的有效值. 如果属性的类型是数组,则它也可以是值的数组. 此属性是必需的.

description

String

可以显示给用户的值的简短描述. 如果没有可用的描述,则可以省略. 建议使用简短的描述,第一行提供简要的摘要. 说明中的最后一行应以句点(.) 结尾.

每个 hint 元素的 providers 属性中包含的JSON对象可以包含下表中描述的属性:

名称 类型 用意

name

String

用于为提示所引用的元素提供附加内容帮助的提供者的名称.

parameters

JSON object

提供程序支持的任何其他参数(有关更多详细信息,请参阅提供程序的文档) .

1.4. 重复的元数据项

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

2. 提供手动提示

为了改善用户体验并进一步帮助用户配置给定属性,您可以提供其他元数据,这些元数据可以:

  • 描述属性的潜在值列表.

  • 关联提供者,以将定义良好的语义附加到属性,以便工具可以根据项目的上下文来发现潜在值的列表.

2.1. Value Hint

每个提示的 name 属性是指属性的名称. 在前面显示的初始示例中,我们为 spring.jpa.hibernate.ddl-auto 属性提供了五个值: none, validate, update, create, 和 create-drop. 每个值也可以具有描述.

如果您的属性属于 Map 类型,则可以提供键和值的提示(但不提供地图本身的提示) . 特殊的 .keys 和 .values 后缀必须分别引用键和值.

假设有一个 sample.contexts 将魔法值 String 值映射为一个整数,如以下示例所示:

@ConfigurationProperties("sample")
public class SampleProperties {

    private Map<String,Integer> contexts;
    // getters and setters
}

魔法值(在此示例中) 为 sample1 和 sample2. 为了为键提供其他内容帮助,您可以将以下JSON添加到模块的手动元数据中:

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

2.2. Value 提供者

提供程序是将语义附加到属性的有效方法. 在本节中,我们定义了可用于您自己的提示的官方提供程序. 但是,您最喜欢的IDE可能只实现其中一些,也可能不实现. 而且,它最终可以提供自己的.

由于这是一项新功能,IDE供应商必须赶上它的工作方式. 采用时间自然会有所不同. 下表总结了受支持的提供程序的列表:
名字 描述

any

允许提供任何附加值.

class-reference

自动完成项目中可用的类. 通常受 target 参数指定的基类的约束.

handle-as

如同按强制 target 参数定义的类型定义属性一样处理属性.

logger-name

自动完成有效的记录器名称和 记录器组. 通常,可以自动完成当前项目中可用的包和类名以及定义的组. .

spring-bean-reference

自动完成当前项目中的可用bean名称. 通常受 target 参数指定的基类的约束.

spring-profile-name

自动完成项目中可用的Spring概要文件名称.
对于给定的属性,只有一个提供程序可以处于 active 状态,但是如果它们都可以通过某种方式管理该属性,则可以指定多个提供程序. 确保将最强大的提供程序放在首位,因为IDE必须使用它可以处理的JSON部分中的第一个. 如果不支持给定属性的提供程序,则也不提供特殊的内容帮助.

2.2.1. Any

特殊的任何提供程序值允许提供任何其他值. 如果支持,则应基于属性类型进行常规值验证.

如果您具有值列表,并且任何其他值仍应视为有效,则通常使用此提供程序.

以下示例提供了 system.state 的自动完成值的 on 和 off:

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

注意,在前面的示例中,还允许任何其他值.

2.2.2. Class 引用

类引用 提供程序自动完成项目中可用的类. 此提供程序支持以下参数:

参数 类型 默认值 描述

target

String (Class)

none

应分配给所选值的类的完全限定名称. 通常用于过滤掉非候选类. 请注意,可以通过暴露具有适当上限的类来由类型本身提供此信息.

concrete

boolean

true

指定是否仅将具体类视为有效候选者.

以下元数据片段对应于标准 server.servlet.jsp.class-name 属性,该属性定义了要使用的 JspServlet 类名称:

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

2.2.3. Handle As

handle-as 提供程序使您可以将属性的类型替换为更高级的类型. 当该属性具有 java.lang.String 类型时,通常会发生这种情况,因为您不希望配置类依赖于可能不在类路径中的类. 此提供程序支持以下参数:

参数 类型 默认值 描述

target

String (Class)

none

要为属性考虑的类型的标准名称. 此参数是必需的.

可以使用以下类型:

  • 任何 java.lang.Enum: 列出属性的可能值. (我们建议使用 Enum 类型定义属性,因为IDE不需要其他提示即可自动完成值)

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

  • java.util.Locale: 语言环境的自动完成(例如 en_US)

  • org.springframework.util.MimeType: 支持内容类型值(例如 text/plain) 的自动完成

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

如果可以提供多个值,请使用 Collection 或 Array 类型向IDE讲解.

以下元数据片段对应于标准 spring.liquibase.change-log 属性,该属性定义了要使用的更改日志的路径. 实际上,它在内部用作 org.springframework.core.io.Resource,但不能这样暴露,因为我们需要保留原始的String值以将其传递给Liquibase API.

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

2.2.4. Logger 名

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

2.2.5. Spring Bean 引用

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

参数 类型 默认值 描述

target

String (Class)

none

应分配给候选者的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引用. .

2.2.6. Spring Profile 名

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

以下元数据片段对应于标准 ·spring.profiles.active· 属性,该属性定义了要启用的Spring概要文件的名称:

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

3. 使用注解处理器生成您自己的元数据

您可以使用 spring-boot-configuration-processor jar从带有 @ConfigurationProperties 注解的项目中轻松生成自己的配置元数据文件. 该jar包含一个Java注解处理器,在您的项目被编译时会被调用. 要使用处理器,请包括对 spring-boot-configuration-processor 的依赖.

使用Maven,依赖应声明为可选,如以下示例所示:

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

对于Gradle 4.6和更高版本,应在 compileOnly 配置中声明依赖,如以下示例所示:

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

对于Gradle 4.6和更高版本,应在 annotationProcessor 配置中声明依赖,如以下示例所示:

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

如果您使用的是额外的 spring-configuration-metadata.json 文件,则应将 compileJava 任务配置为依赖于 processResources 任务,如以下示例所示:

compileJava.dependsOn(processResources)

这种依赖关系确保注解处理器在编译期间运行时,其他元数据可用.

处理器选择用 @ConfigurationProperties 注解的类和方法. 配置类中字段值的Javadoc用于填充 description 属性.

您仅应将简单文本与 @ConfigurationProperties 字段Javadoc一起使用,因为在将它们添加到JSON之前不会对其进行处理.

如果该类具有一个带有至少一个参数的构造函数,则为每个构造函数参数创建一个属性. 否则,将通过存在标准的 getter 和 setter 并对集合类型进行特殊处理来发现属性(即使仅存在getter也会被检测到) .

注解处理器还支持使用 @Data,@Getter 和 @Setter lombok注解.

注解处理器无法自动检测 Enum 和 `Collections 的默认值. 在 Collection 或 Enum 属性具有非空默认值的情况下,应提供手动元数据.

考虑以下类:

@ConfigurationProperties(prefix = "acme.messaging")
public class MessagingProperties {

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

    private ContainerType containerType = ContainerType.SIMPLE;

    // ... getter and setters

    public enum ContainerType {

        SIMPLE,
        DIRECT

    }

}

为了记录以上类中属性的默认值,您可以将以下内容添加到模块的手动元数据:

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

只需要属性 name 即可记录带有手动元数据的其他字段.

如果在项目中使用AspectJ,则需要确保注解处理器仅运行一次. 有几种方法可以做到这一点. 使用Maven,您可以显式配置 maven-apt-plugin 并将依赖仅添加到注解处理器中. 您还可以让AspectJ插件在 maven-compiler-plugin 配置中运行所有处理并禁用注解处理,如下所示:

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

3.1. 嵌套属性

注解处理器自动将内部类视为嵌套属性. 考虑以下类:

@ConfigurationProperties(prefix="server")
public class ServerProperties {

    private String name;

    private Host host;

    // ... getter and setters

    public static class Host {

        private String ip;

        private int port;

        // ... getter and setters

    }

}

前面的示例为 server.name,server.host.ip 和 server.host.port 属性生成元数据信息. 您可以在字段上使用 @NestedConfigurationProperty 注解,以指示应将常规(非内部) 类视为嵌套类.

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

3.2. 添加其他元数据

Spring Boot的配置文件处理非常灵活,通常情况下可能存在未绑定到 @ConfigurationProperties bean的属性. 您可能还需要调整现有键的某些属性. 为了支持这种情况,并允许您提供自定义的 "hints",注解处理器会自动将 META-INF/additional-spring-configuration-metadata.json 中的项目合并到主元数据文件中.

如果引用了已自动检测到的属性,则如果指定了描述,默认值和弃用信息,则它们将被覆盖. 如果在当前模块中未标识手动属性声明,则将其添加为新属性.

另外,spring-configuration-metadata.json 文件的格式与常规的 spring-configuration-metadata.json 完全相同. 附加属性文件是可选的. 如果没有任何其他属性,请不要添加文件.