VitePress

Appendix B: 配置元数据

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

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

B.1. Metadata 格式

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

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

每个 “property” 都是用户使用给定值指定的配置项. 例如,可以在 application.properties/application.yaml 中指定 server.port 和 server.address,如下所示:

yaml

server:
  port: 9090
  address: 127.0.0.1

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

TIP

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

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

Group 属性

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

名称	类型	目的
`name`	String	组的全名. 此属性是必需的.
`type`	String	组数据类型的类名. group 数据类型的类名.例如,如果 group 是基于一个被 `@ConfigurationProperties` 注解的类,该属性将包含该类的全限定名.如果基于一个 `@Bean` 方法,它将是该方法的返回类型.如果该类型未知,则该属性将被忽略
`description`	String	一个简短的 group 描述,用于展示给用户.如果没有可用描述,该属性将被忽略.推荐使用一个简短的段落描述,第一行提供一个简洁的总结,最后一行以句号结尾
`sourceType`	String	贡献该组的来源类名.例如,如果组基于一个被 `@ConfigurationProperties` 注解的 `@Bean` 方法,该属性将包含 `@Configuration` 类的全限定名,该类包含此方法.如果来源类型未知,则该属性将被忽略
`sourceMethod`	String	贡献该组的方法的全名(包含括号及参数类型).例如,被 `@ConfigurationProperties` 注解的 `@Bean` 方法名.如果源方法未知,该属性将被忽略

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. 以下示例显示了如何处理这种情况:

java

@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 时,这样做特别有用.

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 的文档) .

重复的元数据项

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

B.2. 提供手动提示

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

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

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>,如以下示例所示:

java

@ConfigurationProperties("my")
public class MyProperties {    
    private Map<String, Integer> contexts;
    // getters/setters ...
}

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

json

{"hints": [
    {
        "name": "my.contexts.keys",
        "values": [
            {
                "value": "sample1"
            },
            {
                "value": "sample2"
            }
        ]
    }
]}

TIP

我们建议您对这两个值使用 Enum. 如果您的 IDE 支持,这是迄今为止最有效的自动完成方法.

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 名称.

TIP

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

Any

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

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

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

json

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

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

Class Reference

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

参数	类型	默认值	描述
`target`	`String` (`Class`)	none	应分配给所选值的类的完全限定名称. 通常用于过滤掉非候选类. 请注意,可以通过暴露具有适当上限的类来由类型本身提供此信息.
`concrete`	`boolean`	true	指定是否仅将具体类视为有效候选者.

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

json

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

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)

TIP

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

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

json

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

Logger Name

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

此 provider 支持以下参数:

参数	类型	默认值	描述
`group`	`boolean`	`true`	指定是否应考虑已知组.

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

以下元数据片段对应于标准 logging.level 属性. 键是记录器名称,其值对应于标准日志级别或任何自定义级别. 当 Spring Boot 开箱即用地定义了一些记录器组时,已经为它们添加了专用的值提示.

json

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

Spring Bean Reference

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

参数	类型	默认值	描述
`target`	`String` (`Class`)	none	应分配给候选者的Bean类的完全限定名称. 通常用于过滤掉非候选 bean.

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

json

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

TIP

binder 不会自动装配日这些元数据,如果提供了该提示,则仍需要使用 ApplicationContext 将 Bean 名称转换为实际的 Bean 引用.

Spring Profile Name

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

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

json

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

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

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

配置注解处理器

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

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

xml

<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 配置中执行所有处理时禁用注解处理,如下所示

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

自动生成元数据

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

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

考虑以下类:

java

@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 ...

这暴露了三个属性,其中 my.server.name 没有默认值,my.server.ip 和 my.server.port 分别默认为 "127.0.0.1" 和 9797. 字段值的 Javadoc 用于填充 description 属性.. 例如,my.server.ip 的描述是 "IP address to listen to".

TIP

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

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

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

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

考虑以下类:

java

@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 enum ContainerType {        
        SIMPLE, DIRECT    
    }
}

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

json

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

TIP

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

嵌套属性

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

java

@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {    
    private String name;    
    private Host host;

    // getters/setters ...

    public static class Host {        
        private String ip;        
        private int port;

        // getters/setters ...

    }}

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

TIP

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

添加其他元数据

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

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

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

Appendix B: 配置元数据 ​

B.1. Metadata 格式 ​

Group 属性 ​

Property 属性 ​

Hint 属性 ​

重复的元数据项 ​

B.2. 提供手动提示 ​

Value Hint ​

Value Providers ​

Any ​

Class Reference ​

Handle As ​

Logger Name ​

Spring Bean Reference ​

Spring Profile Name ​

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

配置注解处理器 ​

自动生成元数据 ​

嵌套属性 ​

添加其他元数据 ​

Appendix B: 配置元数据

B.1. Metadata 格式

Group 属性

Property 属性

Hint 属性

重复的元数据项

B.2. 提供手动提示

Value Hint

Value Providers

Any

Class Reference

Handle As

Logger Name

Spring Bean Reference

Spring Profile Name

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

配置注解处理器

自动生成元数据

嵌套属性

添加其他元数据