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

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

1. Metadata 格式

配置元数据文件位于 jars 文件中的 META-INF/spring-configuration-metadata.json . 它们使用一个具有 “groups” 或 “properties” 分类节点的简单 JSON 格式,并将其他值提示归类为 "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/application.yaml 中指定 server.port 和 server.address,如下所示:

server:
  port: 9090
  address: 127.0.0.1

“groups” 是高级别的节点,它们本身不指定一个值,但为 properties 提供一个有上下文关联的分组. 例如,server.port 和 server.address 属性是 server 组的一部分.

不需要每个 “property” 都有一个 “group”. 一些属性可以以自己的形式存在.

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

1.1. Group 属性

groups 数组包含的 JSON 对象可以由以下属性组成:

名称 类型 目的

name

String

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

type

String

组数据类型的类名. group 数据类型的类名.例如,如果 group 是基于一个被 @ConfigurationProperties 注解的类,该属性将包含该类的全限定名.如果基于一个 @Bean 方法,它将是该方法的返回类型.如果该类型未知,则该属性将被忽略

description

String

一个简短的 group 描述,用于展示给用户.如果没有可用描述,该属性将被忽略.推荐使用一个简短的段落描述,第一行提供一个简洁的总结,最后一行以句号结尾

sourceType

String

贡献该组的来源类名.例如,如果组基于一个被 @ConfigurationProperties 注解的 @Bean 方法,该属性将包含 @Configuration 类的全限定名,该类包含此方法.如果来源类型未知,则该属性将被忽略

sourceMethod

String

贡献该组的方法的全名(包含括号及参数类型).例如,被 @ConfigurationProperties 注解的 @Bean 方法名.如果源方法未知,该属性将被忽略

1.2. Property 属性

properties 数组中包含的 JSON 对象可由以下属性构成:

名称 类型 目的

name

String

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

type

String

property 数据类型的类名(例如,java.lang.String) ,还具有完整的泛型类型(例如,java.util.Map<java.lang.String,com.example.MyEnum>) . 该属性可以用来指导用户他们可以输入值的类型.为了保持一致,原生类型使用它们的包装类代替(例如,boolean 变为 java.lang.Boolean) . 注意,这个类可能是个从一个字符串转换而来的复杂类型.如果类型未知则该属性会被忽略

description

String

一个简短的组的描述,用于展示给用户.如果没有描述可用则该属性会被忽略.推荐使用一个简短的段落描述,开头提供一个简洁的总结,最后一行以 . 结束

sourceType

String

contributed property 的来源类名.例如,如果 property 来自一个被 @ConfigurationProperties 注解的类,该属性将包括该类的全限定名.如果来源类型未知则该属性会被忽略

defaultValue

Object

当 property 没有定义时使用的默认值.如果 property 类型是个数组则该属性也可以是个数组.如果默认值未知则该属性会被忽略

deprecation

Deprecation

指定该 property 是否过期.如果该字段没有过期或该信息未知则该属性会被忽略. 下表提供了有关 deprecation 属性的更多详细信息.

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

名称 类型 目的

level

String

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

reason

String

简短描述了该资源被弃用的原因.如果没有理由可以省略.建议描述是一个简短的段落,第一行提供简明扼要的摘要.说明中的最后一行应以(.) 结尾.

replacement

String

正在替换此不推荐使用的属性的属性的全名.如果没有替换此属性,可以省略.
在 Spring Boot 1.3 之前,可以使用单个 deprecated 使用的布尔属性来代替 deprecation 元素. 这仍然以不推荐的方式支持,不应再使用.如果没有理由和替换可用, deprecation 应该设置一个空的对象.

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

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 属性) . 一旦可以从公共 API 中删除 getTarget 和 setTarget 方法,元数据中的自动弃用提示也将消失. 如果要保留提示,请添加具有 error 级别的手动元数据,以确保仍然向用户通知该属性. 当提供 replacement 时,这样做特别有用.

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

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

1.4. 重复的元数据项

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

2. 提供手动提示

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

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

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

2.1. Value Hint

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

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

假设 my.contexts 将 String 值映射到整数，如以下示例所示：

假设有一个 my.contexts 的 Map<String,Integer>,如以下示例所示:

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

}

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

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

2.2. Value Providers

Providers 是一种将语义附加到属性的强有力的方法,我们将定义可以用于您自己的提示的官方 Providers. 但是,您最喜欢的 IDE 可能只实现其中一些,也可能没有实现.

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

下表总结了受支持的 provider 的列表:

名字 描述

any

允许提供任何附加值.

class-reference

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

handle-as

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

logger-name

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

spring-bean-reference

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

spring-profile-name

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

2.2.1. Any

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

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

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

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

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

2.2.2. Class Reference

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

参数 类型 默认值 描述

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

参数 类型 默认值 描述

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 Name

logger-name provider 会自动完成有效的记录器名称和 记录器组. 通常,可以自动完成当前项目中可用的程序包和类名. 如果启用了组(默认) ,并且在配置中标识了自定义记录程序组,则应为其提供自动完成功能. 特定的框架可能还具有其他可以支持的魔法值记录器名称.

此 provider 支持以下参数:

参数 类型 默认值 描述

group

boolean

true

指定是否应考虑已知组.

由于记录器名称可以是任意名称,因此该 provider 应允许使用任何值,但可以突出显示项目的类路径中不可用的有效程序包和类名称.

以下元数据片段对应于标准 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 Reference

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

参数 类型 默认值 描述

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 Name

spring-profile-name provider 自动完成在当前项目的配置中定义的 Spring profile.

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

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

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

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

3.1. 配置注解处理器

要使用处理器,请添加 spring-boot-configuration-processor 的依赖.

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

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

使用 Gradle,应该在 annotationProcessor 配置中声明依赖,如以下示例所示:

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

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

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

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

如果在项目中使用 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.2. 自动生成元数据

处理器选择用 @ConfigurationProperties 注解的类和方法.

如果该类也使用了 @ConstructorBinding 注解,则应使用单个构造函数,并为每个构造函数参数创建一个属性.否则,将通过存在标准的 getter 和 setter 并对集合和 Map 类型进行特殊处理来发现属性(即使仅存在 getter 也会被检测到).注解处理器还支持使用 @Data, @Value, @Value`@Getter` 和 @Setter lombok 注解.

考虑以下类:

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.ip 和 my.server.port 分别默认为 "127.0.0.1" 和 9797. 字段值的 Javadoc 用于填充 description 属性.. 例如,my.server.ip 的描述是 "IP address to listen to".

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

注解处理器应用多种启发式方法从源模型中提取默认值.必须静态提供默认值. 特别是不要引用另一个类中定义的常量. 另外,注解处理器无法自动检测 Enum 和 Collections 的默认值.

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

对于无法检测到默认值的情况,应提供 手动元数据.

考虑以下类:

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

    }

}

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

{"properties": [
    {
        "name": "my.messaging.addresses",
        "defaultValue": ["a", "b"]
    },
    {
        "name": "my.messaging.container-type",
        "defaultValue": "simple"
    }
]}
只需要属性 name 即可记录带有手动元数据的其他字段.

3.2.1. 嵌套属性

注解处理器自动将内部类视为嵌套属性.我们可以为它创建一个子命名空间,而不是在根命名空间的记录 ip 和 port.考虑更新后的示例: 考虑以下类:

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.ip 和 my.server.host.port 属性生成元数据信息. 您可以在字段上使用 @NestedConfigurationProperty 注解,以指示应将常规(非内部) 类视为嵌套类.

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

3.3. 添加其他元数据

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

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

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