配置元数据

Spring Boot jar包含元数据文件，这些文件提供了所有受支持的配置属性的详细信息。这些文件旨在让IDE开发人员在用户使用application.properties或application.yml文件时提供上下文帮助和“代码完成” 。
通过处理带有注释的所有项目，大多数元数据文件会在编译时自动生成@ConfigurationProperties。但是，可以针对极端情况或更高级的用例手动编写部分元数据。

1.元数据格式

配置元数据文件位于的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.port并且server.address可能在中指定application.properties，如下所示：

server.port=9090
server.address=127.0.0.1

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

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

1.1。组属性

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

1.2。属性属性

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

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

也可以在代码中以声明方式指定@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);
    }
}

前面的代码确保不推荐使用的属性仍然有效（将其委托给name幕后的属性）。一旦getTargetandsetTarget方法可以从公共API中删除，元数据中的自动弃用提示也将消失。如果要保留提示，请添加具有error弃用级别的手动元数据，以确保仍然向用户通知该属性。当replacement提供a时，这样做特别有用。

1.3。提示属性

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

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

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

1.4。重复的元数据项

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

2.提供手动提示

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

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

  2.1。价值提示

  name每个提示的属性均指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"
            }
        ]
    }
  ]}

  | | 我们建议您Enum对这两个值使用代替。如果您的IDE支持，则这是迄今为止最有效的自动完成方法。 | | :—-: | —- |

2.2。价值提供者

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

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

2.2.1。任何

特殊的任何提供程序值允许提供任何其他值。如果支持，则应基于属性类型进行常规值验证。
如果您具有值列表，并且任何其他值仍应视为有效，则通常使用此提供程序。
以下示例提供on和off作为自动完成值system.state：

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

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

2.2.2。类参考

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

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

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

2.2.3。处理为

该手柄的供应商，您可以替代属性的类型到一个更高层次的类型。当属性具有java.lang.String类型时，通常会发生这种情况，因为您不希望配置类依赖于可能不在类路径中的类。该提供程序支持以下参数：

可以使用以下类型：

• 任意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或数组类型向IDE讲解。 | | :—-: | —- |

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

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

由于记录器名称可以是任意名称，因此该提供程序应允许使用任何值，但可以突出显示项目的类路径中不可用的有效程序包和类名称。
以下元数据片段对应于standardlogging.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.jmx.server属性，该属性定义了MBeanServer要使用的Bean的名称：

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

2.2.6。春季资料名称

该弹簧轮廓名提供商自动完成当前项目的配置中定义的春天配置文件。
以下元数据片段对应于标准spring.profiles.active属性，该属性定义了要启用的Spring概要文件的名称：

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

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

您可以@ConfigurationProperties使用spring-boot-configuration-processorjar轻松地从带有注释的项目中生成自己的配置元数据文件。该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任务，如以下示例所示：

compileJava.inputs.files(processResources)

这种依赖性确保注释处理器在编译期间运行时，其他元数据可用。

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

org.apache.maven.plugins maven-compiler-plugin none

 |
| :---: | --- |
<a name="configuration-metadata-annotation-processor-metadata-generation"></a>
### 3.2。自动元数据生成
处理器选择用注释的类和方法`@ConfigurationProperties`。<br />如果该类也用注释`@ConstructorBinding`，则应该使用一个构造函数，并且每个构造函数参数都将创建一个属性。否则，将通过对集合和地图类型进行特殊处理的标准getter和setter来发现属性（即使仅存在getter也会被检测到）。注解处理器还支持使用的`@Data`，`@Getter`和`@Setter`Lombok的注释。<br />考虑以下示例：

@ConfigurationProperties(prefix=”server”) public class ServerProperties { /**

* 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;
// ... getter and setters

}

这暴露了三个属性，其中`server.name`有没有缺省值，`server.ip`并`server.port`默认为`"127.0.0.1"`和`9797`分别。字段上的Javadoc用于填充`description`属性。例如，描述`server.ip`为“要收听的IP地址”。
|  | 您仅应将纯文本与`@ConfigurationProperties`Javadoc字段一起使用，因为在将纯文本添加到JSON之前不会对其进行处理。 |
| :---: | --- |
注释处理器应用多种启发式方法从源模型中提取默认值。必须静态提供默认值。特别是不要引用另一个类中定义的常量。另外，注释处理器无法自动检测`Enum`s和`Collections`s的默认值。<br />对于无法检测到默认值的情况，应提供[手动元数据](https://docs.spring.io/spring-boot/docs/2.4.3/reference/html/appendix-configuration-metadata.html#configuration-metadata-additional-metadata)。考虑以下示例：

@ConfigurationProperties(prefix = “acme.messaging”) public class MessagingProperties { private List addresses = new ArrayList<>(Arrays.asList(“a”, “b”)); private ContainerType containerType = ContainerType.SIMPLE; // … getter and setters public enum ContainerType { SIMPLE, DIRECT } }

为了记录以上类中属性的默认值，您可以将以下内容添加到[模块的手动元数据中](https://docs.spring.io/spring-boot/docs/2.4.3/reference/html/appendix-configuration-metadata.html#configuration-metadata-additional-metadata)：

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

|  | 仅`name`属性的即可记录现有属性的其他元数据。 |
| :---: | --- |
<a name="configuration-metadata-annotation-processor-metadata-generation-nested"></a>
#### 3.2.1。嵌套属性
注释处理器自动将内部类视为嵌套属性。除了可以在命名空间的根目录中记录`ip`和之外`port`，我们还可以为其创建一个子命名空间。考虑更新后的示例：

@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.3。添加其他元数据

Spring Boot的配置文件处理非常灵活，通常情况下可能存在未绑定到@ConfigurationPropertiesBean的属性。您可能还需要调整现有键的某些属性。为了支持这种情况，并允许您提供自定义的“提示”，注释处理器会自动将项目从其中合并META-INF/additional-spring-configuration-metadata.json到主元数据文件中。
如果引用了已自动检测到的属性，则如果指定，则将覆盖描述，默认值和弃用信息。如果当前模块中未标识手动属性声明，则将其添加为新属性。
该additional-spring-configuration-metadata.json文件的格式与常规格式完全相同spring-configuration-metadata.json。附加属性文件是可选的。如果没有任何其他属性，请不要添加文件。