附录 B.配置元数据

Spring Boot jar 附带有元数据文件，这些文件提供了所有受支持的配置属性的详细信息。这些文件旨在允许 IDE 开发人员在用户处理application.properties或application.yml文件时提供上下文帮助和“代码完成”。

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

B.1 元数据格式

配置元数据文件位于META-INF/spring-configuration-metadata.json下的 jar 内，它们使用简单的 JSON 格式，将项目归类为“组”或“属性”，并将其他 Value hint 归类为“提示”：

{"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.servlet-path",
        "type": "java.lang.String",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties",
        "defaultValue": "/"
    },
    {
          "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."
            }
        ]
    }
]}

每个“属性”都是用户使用给定值指定的配置项。例如，可以在application.properties中指定server.port和server.servlet-path，如下所示：

server.port=9090
server.servlet-path=/home

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

最后，“提示”是用于帮助用户配置给定属性的其他信息。配置spring.jpa.hibernate.ddl-auto属性时，工具可以使用它为none，validate，update，create和create-drop值提供一些自动完成帮助。

B.1.1 组属性

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

B.1.2 属性属性

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

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

通过将@DeprecatedConfigurationProperty注解添加到暴露不推荐使用的属性的 getter 中，也可以在代码中以声明方式指定不推荐使用。例如，假设app.foo.target属性令人困惑，并将其重命名为app.foo.name

@ConfigurationProperties("app.foo")
public class FooProperties {

    private String name;

    public String getName() { ... }

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

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

    @Deprecated
    public void setTarget(String target) {
        setName(target);
    }
}

上面的代码确保不推荐使用的属性仍然有效(将其委托给幕后的name属性)。一旦可以从您的公共 API 中删除getTarget和setTarget方法，元数据中的自动弃用提示也会消失。如果要保持提示，添加具有error弃用级别的手动元数据可确保仍然向用户通知该属性，并且在提供replacement时特别有用。

B.1.3 提示属性

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

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

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

B.1.4 重复的元数据项

具有相同名称的“属性”和“组”对象在元数据文件中多次出现是完全可以接受的。例如，您可以将两个单独的类绑定到同一前缀，每个类可能提供重叠的属性名称。尽管这不应该经常出现，但是元数据的使用者应该注意确保他们支持这种情况。

B.2 提供手动提示

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

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

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

B.2.1Value hint

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

如果您的属性类型为Map，则可以提供键和值的提示(但不提供 Map 本身的提示)。必须使用特殊的.keys和.values后缀来分别指代键和值。

假设foo.contexts将魔术字符串值 Map 为整数：

@ConfigurationProperties("foo")
public class FooProperties {

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

魔术值例如是 foo 和 bar。为了提供有关键的其他内容帮助，您可以将以下内容添加到模块的手动元数据：

{"hints": [
    {
        "name": "foo.contexts.keys",
        "values": [
            {
                "value": "foo"
            },
            {
                "value": "bar"
            }
        ]
    }
]}

B.2.2Value provider

提供程序是将语义附加到属性的强大方法。我们在下面的部分中定义了您可以用来提供自己提示的官方提供程序。但是请记住，您最喜欢的 IDE 可能不会实现其中一些。它最终也可以提供自己的。

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

Any

any 提供程序允许提供任何其他值。如果支持，则应基于属性类型进行常规值验证。

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

下面的示例提供on和off作为system.state的自动完成值；也可以使用任何其他值：

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

Class reference

类别参考提供程序会自动完成项目中可用的类别。此提供程序支持以下参数：

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

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

Handle As

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

可以使用以下类型：

• 列出该属性的可能值的任何java.lang.Enum(通过所有方式，请尝试使用Enum类型定义该属性，因为 IDE 不需要其他提示即可自动完成这些值)。

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

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

• org.springframework.util.MimeType：自动完成 Content Type 值(例如text/plain)

• org.springframework.core.io.Resource：自动完成 Spring 的 Resource 抽象，以引用文件系统或 Classpath 上的文件。 (例如classpath:/foo.properties)

以下元数据代码段对应于标准liquibase.change-log属性，该属性定义了要使用的变更日志的路径。实际上，它在内部用作org.springframework.core.io.Resource，但无法公开，因为我们需要保留原始 String 值以将其传递给 Liquibase API。

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

Logger name

Logger 名称提供程序会自动填写有效的 Logger 名称。通常，可以自动完成当前项目中可用的包和类名。特定框架可能还具有其他可能支持的魔术 Logger 名称。

由于 Logger 名称可以是任意名称，因此，此提供程序实际上应该允许任何值，但可以突出显示项目的 Classpath 中不可用的有效包和类名称。

以下元数据代码段对应于标准logging.level属性，键是* logger 名称*，值对应于标准日志级别或任何自定义级别：

{"hints": [
    {
        "name": "logging.level.keys",
        "values": [
            {
                "value": "root",
                "description": "Root logger used to assign the default logging level."
            }
        ],
        "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"
            }
        ]
    }
]}

Spring bean 参考

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

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

{"hints": [
    {
        "name": "spring.jmx.server",
        "providers": [
            {
                "name": "spring-bean-reference",
                "parameters": {
                    "target": "javax.management.MBeanServer"
                }
            }
        ]
    }
]}

SpringProfile 名称

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

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

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

B.3 使用 Comments 处理器生成自己的元数据

您可以使用spring-boot-configuration-processor jar 从@ConfigurationPropertiesComments 的项目中轻松生成自己的配置元数据文件。该 jar 包含一个 JavaComments 处理器，在您的项目被编译时会被调用。要使用处理器，只需将spring-boot-configuration-processor作为可选依赖项包含在内，例如，对于 Maven，您将添加：

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

使用 Gradle，您可以使用propdeps-plugin并指定：

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

compileJava.dependsOn(processResources)

处理器将选择用@ConfigurationPropertiesComments 的类和方法。配置类中字段值的 Javadoc 将用于填充description属性。

属性的发现是通过对集合类型进行特殊处理的标准 getter 和 setter 进行的(即使仅存在 getter 也会被检测到)。Comments 处理器还支持@Data，@Getter和@Setter lombokComments 的使用。

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

B.3.1 嵌套的属性

Comments 处理器将自动将内部类视为嵌套属性。例如，以下类：

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

    private String name;

    private Host host;

    // ... getter and setters

    private static class Host {

        private String ip;

        private int port;

        // ... getter and setters

    }

}

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

B.3.2 添加其他元数据

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

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

additional-spring-configuration-metadata.json文件的格式与常规spring-configuration-metadata.json完全相同。附加属性文件是可选的，如果您没有任何其他属性，则只需添加即可。