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

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

1. 元数据格式

配置元数据文件位于 .jar 下的 jar 内META-INF/spring-configuration-metadata.json。它们使用 JSON 格式，其中项目分类在“组”或“属性”下，附加值提示分类在“提示”下，如以下示例所示：

{"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.portand可能在/server.address中指定，如下所示：application.propertiesapplication.yaml

Properties
server.port=9090
server.address=127.0.0.1
Yaml
server:
  port: 9090
  address: 127.0.0.1

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

并不要求每个“属性”都有一个“组”。有些属性可能以其自身的形式存在。

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

1.1. 群组属性

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

姓名 类型 目的

name

细绳

团体的全名。该属性是强制性的。

type

细绳

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

description

细绳

可向用户显示的组的简短描述。如果没有可用的描述，则可以省略。建议描述采用简短的段落，第一行提供简洁的摘要。描述中的最后一行应以句点 ( .) 结尾。

sourceType

细绳

贡献该组的源的类名称。例如，如果该组基于@Bean用 注释的方法@ConfigurationProperties，则此属性将包含包含该方法的类的完全限定名称@Configuration。如果源类型未知，则可以省略该属性。

sourceMethod

细绳

贡献该组的方法的全名（包括括号和参数类型）（例如，带@ConfigurationProperties注释的@Bean方法的名称）。如果不知道来源方法，则可以省略。

1.2. 属性属性

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

姓名 类型 目的

name

细绳

财产的全名。名称采用小写且以句点分隔的形式（例如，server.address）。该属性是强制性的。

type

细绳

属性数据类型的完整签名（例如java.lang.String），而且也是完整的泛型类型（例如java.util.Map<java.lang.String,com.example.MyEnum>）。您可以使用此属性来指导用户可以输入的值类型。为了保持一致性，原语的类型是通过使用其对应的包装器来指定的（例如，boolean变为java.lang.Boolean）。请注意，此类可能是从 a 转换为值绑定的复杂类型String。如果类型未知，则可以省略。

description

细绳

可向用户显示的属性的简短描述。如果没有可用的描述，则可以省略。建议描述采用简短的段落，第一行提供简洁的摘要。描述中的最后一行应以句点 ( .) 结尾。

sourceType

细绳

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

defaultValue

目的

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

deprecation

弃用

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

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

姓名 类型 目的

level

细绳

弃用级别，可以是warning（默认）或error。当属性具有warning弃用级别时，它仍应绑定在环境中。但是，当它具有error弃用级别时，该属性将不再受管理且不受绑定。

reason

细绳

对该属性被弃用的原因的简短描述。如果没有合理的理由，可以省略。建议描述采用简短的段落，第一行提供简洁的摘要。描述中的最后一行应以句点 ( .) 结尾。

replacement

细绳

替换此已弃用属性的属性的全名。如果没有替代该属性，则可以省略它。
deprecated在 Spring Boot 1.3 之前，可以使用 单个布尔属性来代替deprecation元素。这仍然以已弃用的方式受到支持，不应再使用。如果没有可用的原因和替换，deprecation则应设置一个空对象。

还可以通过将@DeprecatedConfigurationProperty注释添加到暴露已弃用属性的 getter 来在代码中以声明方式指定弃用。例如，假设该my.app.target属性令人困惑并被重命名为my.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当提供a 时，这样做特别有用。

1.3. 提示属性

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

姓名 类型 目的

name

细绳

此提示所引用的属性的全名。名称采用小写并以句点分隔的形式（例如spring.mvc.servlet.path）。如果属性引用映射（例如system.contexts），则提示适用于映射的键system.contexts.keys( ) 或映射的值( )。system.contexts.values该属性是强制性的。

values

值提示[]

对象定义的有效值列表ValueHint（如下表所述）。每个条目定义值并且可能有描述。

providers

价值提供者[]

由对象定义的提供者列表ValueProvider（本文档稍后描述）。每个条目定义提供者的名称及其参数（如果有）。

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

姓名 类型 目的

value

目的

提示所引用的元素的有效值。如果属性的类型是数组，它也可以是值数组。该属性是强制性的。

description

细绳

可向用户显示的值的简短描述。如果没有可用的描述，则可以省略。建议描述采用简短的段落，第一行提供简洁的摘要。描述中的最后一行应以句点 ( .) 结尾。

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

姓名 类型 目的

name

细绳

用于为提示所引用的元素提供附加内容帮助的提供程序的名称。

parameters

JSON 对象

提供程序支持的任何附加参数（查看提供程序的文档以获取更多详细信息）。

1.4. 重复元数据项

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

2. 提供手动提示

为了改善用户体验并进一步帮助用户配置给定属性，您可以提供以下附加元数据：

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

  • 关联提供者，将明确定义的语义附加到属性，以便工具可以根据项目的上下文发现潜在值的列表。

2.1. 价值提示

name每个提示的属性指的是属性name的 。在前面显示的初始示例中，我们为属性提供了五个值spring.jpa.hibernate.ddl-auto：none、validate、update、create和create-drop。每个值也可能有一个描述。

如果您的属性的类型为Map，您可以为键和值提供提示（但不能为地图本身提供提示）。特殊符号.keys和.values后缀必须分别引用键和值。

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

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

}

神奇的值（在本例中）是sample1和sample2。为了为密钥提供额外的内容帮助，您可以将以下 JSON 添加到模块的手动元数据中：

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

2.2. 价值提供者

提供者是将语义附加到属性的强大方法。在本节中，我们定义了您可以用于自己的提示的官方提供程序。然而，您最喜欢的 IDE 可能会实现其中的一些，也可能不会实现其中的任何一个。而且，它最终可以提供自己的。

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

下表总结了支持的提供程序的列表：

姓名 描述

any

允许提供任何附加值。

class-reference

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

handle-as

处理该属性，就像它是由强制参数定义的类型定义的一样target。

logger-name

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

spring-bean-reference

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

spring-profile-name

自动补全项目中可用的 Spring 配置文件名称。
对于给定的属性，只能有一个提供程序处于活动状态，但如果多个提供程序都可以以某种方式 管理该属性，则您可以指定多个提供程序。确保将最强大的提供程序放在第一位，因为 IDE 必须使用它可以处理的 JSON 部分中的第一个提供程序。如果不支持给定属性的提供者，则也不会提供特殊的内容帮助。

2.2.1. 任何

特殊的任何提供者值允许提供任何附加值。如果支持，则应应用基于属性类型的常规值验证。

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

以下示例提供on和off作为 的自动完成值system.state：

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

请注意，在前面的示例中，也允许任何其他值。

2.2.2. 类参考

类引用提供程序自动完成项目中可用的类。该提供程序支持以下参数：

范围 类型 默认值 描述

target

String( Class)

没有任何

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

concrete

boolean

真的

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

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

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

2.2.3. 处理为

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

范围 类型 默认值 描述

target

String( Class)

没有任何

要考虑的属性类型的完全限定名称。该参数为必填项。

可以使用以下类型：

  • Any 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的Resource抽象的自动完成来引用文件系统或类路径上的文件（例如classpath:/sample.properties）

如果可以提供多个值，请使用Collection或Array类型来指导 IDE。

以下元数据片段对应于spring.liquibase.change-log定义要使用的变更日志的路径的标准属性。它实际上在内部用作 aorg.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. 记录器名称

记录器名称提供程序自动完成有效的记录器名称和记录器组。通常，当前项目中可用的包和类名称可以自动完成。如果启用了组（默认）并且在配置中标识了自定义记录器组，则应为其提供自动完成功能。特定框架可能还有额外的魔法记录器名称也可以支持。

该提供程序支持以下参数：

范围 类型 默认值 描述

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)

没有任何

应分配给候选者的 Bean 类的完全限定名称。通常用于过滤掉非候选 Bean。

以下元数据片段对应于spring.jmx.server定义要使用的 bean 名称的标准属性MBeanServer：

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

2.2.6. 弹簧配置文件名称

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

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

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

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

@ConfigurationProperties您可以使用jar从带有注释的项目轻松生成您自己的配置元数据文件spring-boot-configuration-processor。该 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"
}

如果您使用additional-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>

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

3.2. 自动元数据生成

处理器选取用 注释的类和方法@ConfigurationProperties。

如果类具有单个参数化构造函数，则为每个构造函数参数创建一个属性，除非该构造函数用 进行注释@Autowired。如果该类具有显式注释为 的构造函数@ConstructorBinding，则将为该构造函数的每个构造函数参数创建一个属性。否则，通过对集合和映射类型进行特殊处理的标准 getter 和 setter 的存在来发现属性（即使仅存在 getter，也会检测到）。注释处理器还支持使用@Data、@Value、@Getter和@Setterlombok 注释。

考虑以下示例：

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地址”。

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

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

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

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 的配置文件处理非常灵活，通常情况下可能存在未绑定到@ConfigurationPropertiesbean 的属性。您可能还需要调整现有密钥的某些属性。为了支持此类情况并让您提供自定义“提示”，注释处理器会自动将项目合并到META-INF/additional-spring-configuration-metadata.json主元数据文件中。

如果您引用已自动检测到的属性，则说明、默认值和弃用信息（如果指定）将被覆盖。如果当前模块中未识别手动属性声明，则将其添加为新属性。

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