Spring Boot 3.0.0-M1 Reference Documentation(Spring Boot中文参考文档)-附录A-C_@value("${whs.sdk.scheduler.before-delay:1800}")

附录

附录A：常用的应用程序属性

多种属性可以指定到application.properties文件，application.yml文件内，或者作为命令行开关。这个附录提供常用的Spring Boot属性列表以及对使用他们底层类的引用。

Spring Boot提供多种高级格式化的转化机制，请务必查看属性转换部分。

属性贡献可以来自于类路径中的额外的jar文件，所以你应该不认为这是一个详细的列表。而且，你可以定义你自己的属性。

.A.1. 核心属性

.A.2. 缓存属性

.A.3. 邮件属性

.A.4. JSON属性

.A.5. 数据属性

.A.6. 事务属性

.A.7. 数据迁移属性

.A.8. 集成属性

.A.9. Web属性

.A.10. 模板属性

.A.11. 服务器属性

.A.12. 安全属性

.A.13. RSocket属性

.A.14. Actuator属性

.A.15. Devtools属性

.A.16. 测试属性

附录B：配置元数据

Spring Boot jar包含元数据文件，提供所有支持的配置属性明细。这个文件被设计为让IDE开发者提供上下文的帮助和作为与application.properties或者application.yml文件工作的"代码补全"。

元数据文件的大多数是在编译期通过处理使用@ConfigurationProperties注解的所有项自动化生成。然而，对于极端情况或者更高级用例可以手工写元数据的部分。

.B.1. 元数据格式

配置元数据文件位于jar文件META-INF/spring-configuration-metadata.json下。他们使用和项类别在“groups”或者“properties”下并且额外的值提示类别在“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."
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

每一个“property”是一个配置项，用户使用给定的值指定。例如，server.port和server.address可以在你的application.properties/application.yaml中指定，如下：

server:
  port: 9090
  address: 127.0.0.1
1
2
3

“groups”是更高级别项，他们自己不会指定一个值但是为属性提供一个上下文的组。例如，server.port和server.address属性是server组的一部分。

不是必须每一个“property”有一个“group”。一些属性可能在他们自己的权利。

最后，“hints”是额外的信息用来协助用户配置一个给定的属性。例如，当开发者正在配置spring.jpa.hibernate.ddl-auto属性，工具可以使用提示来提供一些对于none,validata,update,create,create-drop值自动补全的帮助。

Group属性

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

Property属性

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

在Spring Boot 1.3之前，单独的deprecated boolean属性可以使用代替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;
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

没有方式设置level。假设warning，因为代码一直处理这个属性。

前面的代码确保启用属性仍然可以工作（幕后委托给name属性）。一旦getTarget和setTarget方法可以在你的公共API中移除，在元数据中的自动化的弃用提示也将移除。如果你想要保持提示，添加手动的error弃用级别的元数据保证用户关于该属性也是知情的。当提供了一个replacement这样做特别有用。

Hint属性

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

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

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

重复的元数据项

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

.B.2. 提供手动提示

在配置一个给定的属性时，要提升用户经验和进一步帮助用户，你可以提供额外的元数据，他们是：

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

值提示

每一个提示的name属性引用一个name属性。在前面展示的初始化的示例中，我们为spring.jpa.hibernate.ddl-auto属性提供了五个值：none,validate,update,create和create-drop。每一个值也有一个描述。

如果你的属性是Map类型，你可以为keys和values提供提示（并不是为map本身）。特定的.keys和.values后缀必须依次引用keys和values。

假设my.contexts映射逻辑的String值到一个interger,如下示例所示：

import java.util.Map;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("my")
public class MyProperties {

    private Map<String, Integer> contexts;

    public Map<String, Integer> getContexts() {
        return this.contexts;
    }

    public void setContexts(Map<String, Integer> contexts) {
        this.contexts = contexts;
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

魔术值（在这个示例中）是sample1和sample2。为了对keys提供额外的内容帮助, 你可以添加以下JSON到模块的手动元数据中：

{"hints": [
    {
        "name": "my.contexts.keys",
        "values": [
            {
                "value": "sample1"
            },
            {
                "value": "sample2"
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13

我们建议你使用Enum代替这两个值。如果你的IDE支持它，这是迄今为止最有效的自动完成的方法。

值提供者

提供者是非常有力的方式来将语义附加到属性。在这部分，我们定义官方的提供者，你可以使用它为你自己的提示。然而，你最擅长的IDE可以实现一些他们或者没有实现。而且，它最终可以提供他自己的服务。

因为这是一个新特性，IDE提供商必须赶上他是如何工作的。采纳的时间自然不同。

以下表格汇总了支持的提供者列表：

对应给定的属性，只能有一个提供者是活动的，但是如果他们都可以以相同的方式管理该属性，你可以指定几个提供者。确保优先使用最有力的提供者，IDE必须使用使用JSON部分中它可以处理的第一个提供者。如果对给定的属性没有支持的提供者，也不会提供特殊的内容帮助。

Any

特殊的Any提供者值允许任何额外的值被提供。如果支持的话，会应用基于属性类型的常规的值校验。

如果你有值的列表，并且任何额外的值仍然应该被认为是有效的，则通常使用此提供者。

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

{"hints": [
    {
        "name": "system.state",
        "values": [
            {
                "value": "on"
            },
            {
                "value": "off"
            }
        ],
        "providers": [
            {
                "name": "any"
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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

Class Reference

class-reference提供者自动补全在项目中可用的类。这个提供者支持以下参数：

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

{"hints": [
    {
        "name": "server.servlet.jsp.class-name",
        "providers": [
            {
                "name": "class-reference",
                "parameters": {
                    "target": "jakarta.servlet.http.HttpServlet"
                }
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13

Handle As

handle-as提供者允许你替换属性类型为更高级别的类型。此提供者通常在属性存在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属性相对应，它定义了修改要使用的日志的路径。它实际作为一个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"
                }
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13

Logger Name

logger-name提供者自动完成有效的日志名称和日志组。通常，在当前项目有效的包和类名称是自动完成。如果启用组（默认情况）并且如果在配置中识别自定义日志记录器组，已经为它提供了自动完成。特定的框架可能有额外的逻辑日志记录器名称可以被支持。

此提供者支持一下参数：

因为一个日志名称可以是任意的名称，这个提供者应该允许任何值，可以突出显示在项目类路径中的不可用的有效包和类名称。

以下元数据片段对应标准的logging.level属性。keys是日志记录器名称，values对应标准的日志级别或者任意自定义级别。由于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"
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

Spring Bean Reference

spring-bean-reference 提供者自动完成当前项目配置定义的bean。这个提供者支持一下参数：

以下元数据片段对应标准的spring.jmx.server属性，它定义了要使用的MBeanServerbean：

{"hints": [
    {
        "name": "spring.jmx.server",
        "providers": [
            {
                "name": "spring-bean-reference",
                "parameters": {
                    "target": "javax.management.MBeanServer"
                }
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10
11
12
13

绑定器不知道元数据。如果你提供该提示，你仍需要通过使用ApplicationContext转换bean名称到一个真实的Bean引用。

Spring Profile Name

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

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

{"hints": [
    {
        "name": "spring.profiles.active",
        "providers": [
            {
                "name": "spring-profile-name"
            }
        ]
    }
]}
1
2
3
4
5
6
7
8
9
10

.B.3. 通过使用注解处理器生成你自己的源数据

你可以非常容易地使用spring-boot-configuration-processorjar将注解了@ConfigurationProperties项目生成你自己的配置元数据文件。这个jar包含一个Java注解处理器，当你的项目编译时调用。

配置注解处理器

要使用处理器，包含spring-boot-configuration-processor依赖。

使用Maven依赖应该声明为可选的，如下示例所示：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>
1
2
3
4
5

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

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

如果你使用一个additional-spring-configuration-metadata.json文件，compileJava任务配置取决于processResources任务，如下示例所示：

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

此依赖确保当注解处理器在编译器运行期间，额外的元数据可用。

如果在你的项目中，你正在使用AspectJ，你需要确保注解处理器只运行一次。有几种方式可以做到这些。使用Maven,你可以显示地配置maven-apt-plugin并且只在那将此依赖添加到注解处理器。你也可以让AspectJ插件在maven-comiler-plugin配置中运行所有处理并禁用注解处理，如下：

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-compiler-plugin</artifactId>
   <configuration>
       <proc>none</proc>
   </configuration>
</plugin>
1
2
3
4
5
6
7

如果在你的项目中你使用Lombok，你需要确保他的注解处理器在spring-boot-configuration-processor之前运行。为此使用Maven,你可以使用Maven编译插件的annotationProcessors属性以正确的顺序列出注解处理器。如果你没有使用这个属性，并且通过在类路径中的可用依赖选取注解处理器，确保spring-boot-configuration-processor依赖之前定义的lombok依赖。

自动化元数据生成

处理器同时选取使用@ConfigurationProperties类和方法。

如果此类有一个单独的参数构造器，每个构造器参数创建一个属性，除非构造器使用了@Autowired注解。如果这个类有一个显示地使用@ConstructorBinding注解的构造器，该构造器的每个构造器参数创建一个属性。除此之外，通过对于集合和map类型特殊的处理（即使只有一个getter存在也会检测）与标准的getters和setters的存在来发现属性。此注解处理器也支持@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;

    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
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

此暴露三个属性，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中自动检测默认值。

对于这些情况默认值不能检测。应该提供手动元数据。考虑以下示例：

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;

    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

    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

为了上面类中的属性的文档默认值，你可以添加以下内容到模块的手动元数据中

{"properties": [
    {
        "name": "my.messaging.addresses",
        "defaultValue": ["a", "b"]
    },
    {
        "name": "my.messaging.container-type",
        "defaultValue": "simple"
    }
]}
1
2
3
4
5
6
7
8
9
10

只有属性的name需要记录现有属性额外的元数据。

内嵌的属性

注解处理器自动考虑内嵌的类作为内嵌属性。而不是在根命名空间记录ip和port，我们将为它创建子命名空间，考虑更新的示例：

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "my.server")
public class MyServerProperties {

    private String name;

    private Host host;

    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;

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

    }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

前面的示例生产元数据信息为my.server.name，my.server.host.port属性。你可以在一个字段上使用@NestedConfigurationProperty注解来表明一个常规的类（非内部类）应该和内嵌的类一样对待。

这个对collections和maps没有影响，因为这些类型是自动识别的。为他们的每一个生成一个单独的元数据。

添加额外的元数据

SpringBoot的配置文件处理是非常灵活的，它经常遇到一种情况可能存在没有绑定到@ConfigurationPropertiesbean的属性。你可能需要调整一些现有key的属性。为支持这种情况，允许你提供自定义的“提示”，注解处理器自动将来自META-INF/additional-spring-configuration-metadata.json的项合并到主要的元数据文件。

如果你依赖一个已经自动化检测的属性，描述，默认值和启用信息（如果指定的话）将被覆盖。如果手动属性声明没有在当前模块声明，作为一个新的属性添加。

additional-spring-configuration-metadata.json文件的格式是完全与常规的spring-configuration-metadata.json一样。额外的属性文件是可选的。如果你没有任何额外的属性，不要添加这个文件。

附录C：自动配置类

此附录包含所有Spring Boot提供的自动配置类的明细，并链接到文档和源码。记得要看下在你的应用程序中的条件报告了解更多自动配置特性开关的详情。（为此，使用--debug或者-Ddebug启用应用程序或者使用Actuator应用程序，使用conditions端点）。

.C.1. spring-boot-autoconfigure

以下自动配置类来自spring-boot-autoconfigure模块：

.C.2. spring-boot-actuator-autoconfigure

以下自动配置类来自spring-boot-actuator-autoconfigure模块：