核心功能

1. SpringApplication 应用程序

SpringApplication类提供了一种便捷的方法来引导从main()方法。 在许多情况下,您可以委托给 staticSpringApplication.run方法,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
Kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication


@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}

当您的应用程序启动时,您应该会看到类似于以下输出的内容:spring-doc.cadn.net.cn

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::               (v3.1.12)

2024-05-23T07:28:02.825Z  INFO 110418 --- [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 17.0.11 with PID 110418 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2024-05-23T07:28:02.838Z  INFO 110418 --- [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"
2024-05-23T07:28:04.651Z  INFO 110418 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2024-05-23T07:28:04.677Z  INFO 110418 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-05-23T07:28:04.678Z  INFO 110418 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.24]
2024-05-23T07:28:04.829Z  INFO 110418 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2024-05-23T07:28:04.832Z  INFO 110418 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1814 ms
2024-05-23T07:28:05.612Z  INFO 110418 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2024-05-23T07:28:05.629Z  INFO 110418 --- [           main] o.s.b.d.f.logexample.MyApplication       : Started MyApplication in 4.205 seconds (process running for 5.381)

默认情况下,INFO将显示日志记录消息,包括一些相关的启动详细信息,例如启动应用程序的用户。 如果您需要的日志级别不是INFO中,您可以设置它,如 Log Levels 中所述。 应用程序版本是使用主应用程序类的包中的实现版本确定的。 可以通过设置spring.main.log-startup-infofalse. 这还将关闭应用程序活动配置文件的日志记录。spring-doc.cadn.net.cn

要在启动期间添加其他日志记录,您可以覆盖logStartupInfo(boolean)SpringApplication.

1.1. 启动失败

如果您的应用程序无法启动,请注册FailureAnalyzers有机会提供专用的错误消息和解决问题的具体措施。 例如,如果您在 port 上启动 Web 应用程序8080并且该端口已在使用中,您应该会看到类似于以下消息的内容:spring-doc.cadn.net.cn

***************************
APPLICATION FAILED TO START
***************************

Description:

Embedded servlet container failed to start. Port 8080 was already in use.

Action:

Identify and stop the process that is listening on port 8080 or configure this application to listen on another port.
Spring Boot 提供了许多FailureAnalyzerimplementations,您可以添加自己的实现。

如果没有故障分析器能够处理异常,您仍然可以显示完整的条件报告,以更好地了解出了什么问题。 为此,您需要启用debug财产使DEBUGLoggingorg.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener.spring-doc.cadn.net.cn

例如,如果您使用java -jar中,您可以启用debug属性,如下所示:spring-doc.cadn.net.cn

$ java -jar myproject-0.0.1-SNAPSHOT.jar --debug

1.2. 延迟初始化

SpringApplication允许延迟初始化应用程序。 启用延迟初始化后,将根据需要创建 bean,而不是在应用程序启动期间创建 bean。 因此,启用延迟初始化可以减少应用程序启动所需的时间。 在 Web 应用程序中,启用延迟初始化将导致许多与 Web 相关的 bean 在收到 HTTP 请求之前不会初始化。spring-doc.cadn.net.cn

延迟初始化的一个缺点是,它可能会延迟发现应用程序的问题。 如果延迟初始化了配置错误的 bean,则在启动期间将不再发生失败,并且只有在初始化 bean 时问题才会变得明显。 还必须注意确保 JVM 具有足够的内存来容纳应用程序的所有 bean,而不仅仅是在启动期间初始化的 bean。 由于这些原因,默认情况下不启用延迟初始化,建议在启用延迟初始化之前对 JVM 的堆大小进行微调。spring-doc.cadn.net.cn

可以使用lazyInitializationmethod 开启SpringApplicationBuildersetLazyInitializationmethod 开启SpringApplication. 或者,也可以使用spring.main.lazy-initialization属性,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.main.lazy-initialization=true
Yaml
spring:
  main:
    lazy-initialization: true
如果要对某些 bean 禁用惰性初始化,同时对应用程序的其余部分使用惰性初始化,则可以使用@Lazy(false)注解。

1.3. 自定义横幅

启动时打印的横幅可以通过添加banner.txtfile 添加到你的 classpath 中,或者通过将spring.banner.location属性设置为此类文件的位置。 如果文件的编码不是 UTF-8,则可以设置spring.banner.charset.spring-doc.cadn.net.cn

在您的banner.txt文件中,您可以使用Environment以及以下任何占位符:spring-doc.cadn.net.cn

表 1.横幅变量
变量 描述

${application.version}spring-doc.cadn.net.cn

应用程序的版本号,如MANIFEST.MF. 例如Implementation-Version: 1.0打印为1.0.spring-doc.cadn.net.cn

${application.formatted-version}spring-doc.cadn.net.cn

应用程序的版本号,如MANIFEST.MF并设置显示格式(用括号括起来,前缀为v). 例如(v1.0).spring-doc.cadn.net.cn

${spring-boot.version}spring-doc.cadn.net.cn

您正在使用的 Spring Boot 版本。 例如3.1.12.spring-doc.cadn.net.cn

${spring-boot.formatted-version}spring-doc.cadn.net.cn

您正在使用的 Spring Boot 版本,格式设置为显示(用括号括起来,前缀为v). 例如(v3.1.12).spring-doc.cadn.net.cn

${Ansi.NAME}(或${AnsiColor.NAME},${AnsiBackground.NAME},${AnsiStyle.NAME})spring-doc.cadn.net.cn

哪里NAME是 ANSI 转义码的名称。 看AnsiPropertySource了解详情。spring-doc.cadn.net.cn

${application.title}spring-doc.cadn.net.cn

应用程序的标题,如MANIFEST.MF. 例如Implementation-Title: MyApp打印为MyApp.spring-doc.cadn.net.cn

SpringApplication.setBanner(…​)method 来启用。 使用org.springframework.boot.Banner接口并实现您自己的printBanner()方法。

您还可以使用spring.main.banner-mode属性来确定是否必须打印横幅System.out (console),发送到配置的记录器 (log)或根本不生产 (off).spring-doc.cadn.net.cn

打印的横幅将注册为以下名称下的单例 Bean:springBootBanner.spring-doc.cadn.net.cn

application.title,application.versionapplication.formatted-version属性仅在您使用java -jarjava -cp使用 Spring Boot Starters。 如果您正在运行解压缩的 jar 并使用java -cp <classpath> <mainclass>或将应用程序作为本机映像运行。spring-doc.cadn.net.cn

要使用application.属性中,使用java -jar或者作为解压的 jar 使用java org.springframework.boot.loader.JarLauncher. 这将初始化application.banner 属性。spring-doc.cadn.net.cn

1.4. 自定义 SpringApplication

如果SpringApplication默认值不符合您的口味,您可以改为创建本地实例并对其进行自定义。 例如,要关闭横幅,您可以编写:spring-doc.cadn.net.cn

Java
import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(MyApplication.class);
        application.setBannerMode(Banner.Mode.OFF);
        application.run(args);
    }

}
Kotlin
import org.springframework.boot.Banner
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args) {
        setBannerMode(Banner.Mode.OFF)
    }
}
传递给SpringApplication是 Spring bean 的配置源。 在大多数情况下,这些是对@Configuration类,但它们也可以是直接引用@Component类。

还可以配置SpringApplication通过使用application.properties文件。 有关详细信息,请参阅 外部化配置spring-doc.cadn.net.cn

有关配置选项的完整列表,请参阅SpringApplicationJavadoc.spring-doc.cadn.net.cn

1.5. Fluent Builder API

如果您需要构建一个ApplicationContext层次结构(具有父/子关系的多个上下文),或者如果您更喜欢使用“Fluent”构建器 API,则可以使用SpringApplicationBuilder.spring-doc.cadn.net.cn

SpringApplicationBuilder允许您将多个方法调用链接在一起,并包含parentchild方法,如以下示例所示:spring-doc.cadn.net.cn

Java
new SpringApplicationBuilder().sources(Parent.class)
    .child(Application.class)
    .bannerMode(Banner.Mode.OFF)
    .run(args);
Kotlin
SpringApplicationBuilder()
    .sources(Parent::class.java)
    .child(Application::class.java)
    .bannerMode(Banner.Mode.OFF)
    .run(*args)
创建ApplicationContext等级制度。 例如,Web 组件必须包含在子上下文中,并且相同的Environment用于父上下文和子上下文。 请参阅SpringApplicationBuilderJavadoc了解完整详细信息。

1.6. 应用程序可用性

在平台上部署时,应用程序可以使用 Kubernetes 探针等基础设施向平台提供有关其可用性的信息。 Spring Boot 包括对常用的“liveness”和“readiness”可用性状态的开箱即用支持。 如果您使用的是 Spring Boot 的“actuator”支持,则这些状态将作为运行状况端点组公开。spring-doc.cadn.net.cn

此外,您还可以通过注入ApplicationAvailability接口连接到您自己的 bean 中。spring-doc.cadn.net.cn

1.6.1. 活跃状态

应用程序的 “Liveness” 状态表明其内部状态是否允许它正常工作,或者如果当前出现故障,则自行恢复。 损坏的 “Liveness” 状态意味着应用程序处于无法恢复的状态,基础设施应重新启动应用程序。spring-doc.cadn.net.cn

通常,“Liveness” 状态不应基于外部检查,例如 Health 检查。 如果是这样,则失败的外部系统(数据库、Web API、外部缓存)将在整个平台上触发大规模重启和级联故障。

Spring Boot 应用程序的内部状态主要由 SpringApplicationContext. 如果应用程序上下文已成功启动,则 Spring Boot 假定应用程序处于有效状态。 一旦刷新了上下文,应用程序就被视为活动了,请参阅 Spring Boot 应用程序生命周期和相关应用程序事件spring-doc.cadn.net.cn

1.6.2. 就绪状态

应用程序的 “Readiness” 状态表明应用程序是否已准备好处理流量。 失败的 “Readiness” 状态告诉平台它暂时不应将流量路由到应用程序。 这通常发生在启动期间,而CommandLineRunnerApplicationRunner组件正在处理中,或者如果应用程序决定它太忙而无法进行其他流量,则随时处理。spring-doc.cadn.net.cn

一旦调用了应用程序和命令行运行器,应用程序就被视为准备就绪,请参阅 Spring Boot 应用程序生命周期和相关应用程序事件spring-doc.cadn.net.cn

预期在启动期间运行的任务应由CommandLineRunnerApplicationRunner组件,而不是使用 Spring 组件生命周期回调,例如@PostConstruct.

1.6.3. 管理应用程序可用性状态

应用程序组件可以随时检索当前可用性状态,方法是将ApplicationAvailability接口并调用方法。 更常见的是,应用程序需要侦听状态更新或更新应用程序的状态。spring-doc.cadn.net.cn

例如,我们可以将应用程序的 “Readiness” 状态导出到一个文件中,以便 Kubernetes “exec Probe” 可以查看此文件:spring-doc.cadn.net.cn

Java
import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.ReadinessState;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Component
public class MyReadinessStateExporter {

    @EventListener
    public void onStateChange(AvailabilityChangeEvent<ReadinessState> event) {
        switch (event.getState()) {
            case ACCEPTING_TRAFFIC -> {
                // create file /tmp/healthy
            }
            case REFUSING_TRAFFIC -> {
                // remove file /tmp/healthy
            }
        }
    }

}
Kotlin
import org.springframework.boot.availability.AvailabilityChangeEvent
import org.springframework.boot.availability.ReadinessState
import org.springframework.context.event.EventListener
import org.springframework.stereotype.Component

@Component
class MyReadinessStateExporter {

    @EventListener
    fun onStateChange(event: AvailabilityChangeEvent<ReadinessState?>) {
        when (event.state) {
            ReadinessState.ACCEPTING_TRAFFIC -> {
                // create file /tmp/healthy
            }
            ReadinessState.REFUSING_TRAFFIC -> {
                // remove file /tmp/healthy
            }
            else -> {
                // ...
            }
        }
    }

}

当应用程序中断且无法恢复时,我们还可以更新应用程序的状态:spring-doc.cadn.net.cn

Java
import org.springframework.boot.availability.AvailabilityChangeEvent;
import org.springframework.boot.availability.LivenessState;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.stereotype.Component;

@Component
public class MyLocalCacheVerifier {

    private final ApplicationEventPublisher eventPublisher;

    public MyLocalCacheVerifier(ApplicationEventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }

    public void checkLocalCache() {
        try {
            // ...
        }
        catch (CacheCompletelyBrokenException ex) {
            AvailabilityChangeEvent.publish(this.eventPublisher, ex, LivenessState.BROKEN);
        }
    }

}
Kotlin
import org.springframework.boot.availability.AvailabilityChangeEvent
import org.springframework.boot.availability.LivenessState
import org.springframework.context.ApplicationEventPublisher
import org.springframework.stereotype.Component

@Component
class MyLocalCacheVerifier(private val eventPublisher: ApplicationEventPublisher) {

    fun checkLocalCache() {
        try {
            // ...
        } catch (ex: CacheCompletelyBrokenException) {
            AvailabilityChangeEvent.publish(eventPublisher, ex, LivenessState.BROKEN)
        }
    }

}

1.7. 应用程序事件和侦听器

除了通常的 Spring Framework 事件(例如ContextRefreshedEvent一个SpringApplication发送一些其他应用程序事件。spring-doc.cadn.net.cn

有些事件实际上是在ApplicationContext,因此您无法在这些@Bean. 您可以将它们注册到SpringApplication.addListeners(…​)方法或SpringApplicationBuilder.listeners(…​)方法。spring-doc.cadn.net.cn

如果您希望自动注册这些侦听器,而不管应用程序是如何创建的,您可以添加META-INF/spring.factories文件添加到项目中,并使用org.springframework.context.ApplicationListener键,如以下示例所示:spring-doc.cadn.net.cn

org.springframework.context.ApplicationListener=com.example.project.MyListener

应用程序事件在应用程序运行时按以下顺序发送:spring-doc.cadn.net.cn

  1. ApplicationStartingEvent在运行开始时发送,但在任何处理之前发送,侦听器和初始值设定项的注册除外。spring-doc.cadn.net.cn

  2. ApplicationEnvironmentPreparedEventEnvironmentto be used in the context 是已知的,但在创建上下文之前。spring-doc.cadn.net.cn

  3. ApplicationContextInitializedEventApplicationContext已准备好并调用ApplicationContextInitializers,但在加载任何 bean 定义之前。spring-doc.cadn.net.cn

  4. ApplicationPreparedEvent在刷新开始之前发送,但在加载 Bean 定义之后发送。spring-doc.cadn.net.cn

  5. ApplicationStartedEvent在刷新上下文之后,但在调用任何应用程序和命令行运行程序之前发送。spring-doc.cadn.net.cn

  6. AvailabilityChangeEvent紧随其后发送LivenessState.CORRECT,表示应用程序被视为 Live。spring-doc.cadn.net.cn

  7. ApplicationReadyEvent在调用任何应用程序和命令行运行程序后发送。spring-doc.cadn.net.cn

  8. AvailabilityChangeEvent紧随其后发送ReadinessState.ACCEPTING_TRAFFIC以指示应用程序已准备好为请求提供服务。spring-doc.cadn.net.cn

  9. ApplicationFailedEvent如果启动时出现异常,则发送。spring-doc.cadn.net.cn

以上列表仅包括SpringApplicationEvents 绑定到SpringApplication. 除此之外,以下事件还会在ApplicationPreparedEvent和之前ApplicationStartedEvent:spring-doc.cadn.net.cn

  • 一个WebServerInitializedEventWebServer已准备就绪。ServletWebServerInitializedEventReactiveWebServerInitializedEvent分别是 servlet 和 reactive 变体。spring-doc.cadn.net.cn

  • 一个ContextRefreshedEventApplicationContext刷新。spring-doc.cadn.net.cn

您通常不需要使用应用程序事件,但知道它们存在会很方便。 在内部, Spring Boot 使用事件来处理各种任务。
事件侦听器不应运行可能很长的任务,因为它们默认在同一线程中执行。 请考虑改用应用程序和命令行运行程序

应用程序事件是使用 Spring Framework 的事件发布机制发送的。 此机制的一部分可确保发布到子上下文中的侦听器的事件也会发布到任何祖先上下文中的侦听器。 因此,如果您的应用程序使用SpringApplication实例,则侦听器可能会接收同一类型应用程序事件的多个实例。spring-doc.cadn.net.cn

要使侦听器能够区分其上下文的事件和后代上下文的事件,它应请求注入其应用程序上下文,然后将注入的上下文与事件的上下文进行比较。 可以通过实现ApplicationContextAware或者,如果侦听器是一个 Bean,则通过使用@Autowired.spring-doc.cadn.net.cn

1.8. Web 环境

一个SpringApplication尝试创建正确类型的ApplicationContext代表您。 用于确定WebApplicationType如下所示:spring-doc.cadn.net.cn

这意味着,如果您使用的是 Spring MVC 和新的WebClient来自同一应用程序中的 Spring WebFlux,则默认情况下将使用 Spring MVC。 您可以通过调用setWebApplicationType(WebApplicationType).spring-doc.cadn.net.cn

也可以完全控制ApplicationContexttype 使用,该setApplicationContextFactory(…​).spring-doc.cadn.net.cn

通常希望调用setWebApplicationType(WebApplicationType.NONE)使用SpringApplication在 JUnit 测试中。

1.9. 访问应用程序参数

如果您需要访问传递给SpringApplication.run(…​),您可以注入org.springframework.boot.ApplicationArguments豆。 这ApplicationArguments接口提供对原始String[]参数以及 parsedoptionnon-option参数,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.util.List;

import org.springframework.boot.ApplicationArguments;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    public MyBean(ApplicationArguments args) {
        boolean debug = args.containsOption("debug");
        List<String> files = args.getNonOptionArgs();
        if (debug) {
            System.out.println(files);
        }
        // if run with "--debug logfile.txt" prints ["logfile.txt"]
    }

}
Kotlin
import org.springframework.boot.ApplicationArguments
import org.springframework.stereotype.Component

@Component
class MyBean(args: ApplicationArguments) {

    init {
        val debug = args.containsOption("debug")
        val files = args.nonOptionArgs
        if (debug) {
            println(files)
        }
        // if run with "--debug logfile.txt" prints ["logfile.txt"]
    }

}
Spring Boot 还会注册一个CommandLinePropertySource带弹簧Environment. 这样,您还可以使用@Value注解。

1.10. 使用 ApplicationRunner 或 CommandLineRunner

如果您需要运行某个特定的代码一次,SpringApplication已启动,您可以实现ApplicationRunnerCommandLineRunner接口。 这两个接口以相同的方式工作,并提供单个run方法,该方法在SpringApplication.run(…​)完成。spring-doc.cadn.net.cn

此协定非常适合应在应用程序启动之后但在开始接受流量之前运行的任务。

CommandLineRunnerinterfaces 以字符串数组的形式提供对应用程序参数的访问,而ApplicationRunner使用ApplicationArguments接口。 以下示例显示了CommandLineRunner替换为run方法:spring-doc.cadn.net.cn

Java
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

@Component
public class MyCommandLineRunner implements CommandLineRunner {

    @Override
    public void run(String... args) {
        // Do something...
    }

}
Kotlin
import org.springframework.boot.CommandLineRunner
import org.springframework.stereotype.Component

@Component
class MyCommandLineRunner : CommandLineRunner {

    override fun run(vararg args: String) {
        // Do something...
    }

}

如果多个CommandLineRunnerApplicationRunnerbean 必须按特定顺序调用,您还可以实现org.springframework.core.Ordered界面或使用org.springframework.core.annotation.Order注解。spring-doc.cadn.net.cn

1.11. 应用程序退出

SpringApplication向 JVM 注册一个关闭钩子,以确保ApplicationContext退出时正常关闭。 所有标准的 Spring 生命周期回调(例如DisposableBeaninterface 或@PreDestroyannotation) 的 intent 调用。spring-doc.cadn.net.cn

此外,bean 可以实现org.springframework.boot.ExitCodeGenerator接口,如果他们希望在SpringApplication.exit()被调用。 然后,可以将此退出代码传递给System.exit()将其作为状态代码返回,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.ExitCodeGenerator;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class MyApplication {

    @Bean
    public ExitCodeGenerator exitCodeGenerator() {
        return () -> 42;
    }

    public static void main(String[] args) {
        System.exit(SpringApplication.exit(SpringApplication.run(MyApplication.class, args)));
    }

}
Kotlin
import org.springframework.boot.ExitCodeGenerator
import org.springframework.boot.SpringApplication
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication
import org.springframework.context.annotation.Bean

import kotlin.system.exitProcess

@SpringBootApplication
class MyApplication {

    @Bean
    fun exitCodeGenerator() = ExitCodeGenerator { 42 }

}

fun main(args: Array<String>) {
    exitProcess(SpringApplication.exit(
        runApplication<MyApplication>(*args)))
}

此外,ExitCodeGeneratorinterface 可以通过 exceptions 实现。 当遇到这样的异常时, Spring Boot 返回由实现的getExitCode()方法。spring-doc.cadn.net.cn

如果有多个ExitCodeGenerator,则使用生成的第一个非零退出代码。 要控制生成器的调用顺序,请另外实现org.springframework.core.Ordered界面或使用org.springframework.core.annotation.Order注解。spring-doc.cadn.net.cn

1.12. 管理员功能

可以通过指定spring.application.admin.enabled财产。 这将公开SpringApplicationAdminMXBean在平台上MBeanServer. 您可以使用此功能远程管理 Spring Boot 应用程序。 此功能对于任何服务包装器实现也很有用。spring-doc.cadn.net.cn

如果您想知道应用程序正在哪个 HTTP 端口上运行,请获取键为local.server.port.

1.13. 应用程序启动跟踪

在应用程序启动期间,SpringApplicationApplicationContext执行许多与应用程序生命周期相关的任务, bean 生命周期,甚至处理应用程序事件。 跟ApplicationStartup、Spring 框架允许您使用StartupStep对象. 收集此数据可以用于分析目的,或者只是为了更好地了解应用程序启动过程。spring-doc.cadn.net.cn

您可以选择ApplicationStartup在设置SpringApplication实例。 例如,要使用BufferingApplicationStartup,你可以写成:spring-doc.cadn.net.cn

Java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.metrics.buffering.BufferingApplicationStartup;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(MyApplication.class);
        application.setApplicationStartup(new BufferingApplicationStartup(2048));
        application.run(args);
    }

}
Kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.context.metrics.buffering.BufferingApplicationStartup
import org.springframework.boot.runApplication

@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args) {
        applicationStartup = BufferingApplicationStartup(2048)
    }
}

第一个可用的实现FlightRecorderApplicationStartup由 Spring Framework 提供。 它将特定于 Spring 的启动事件添加到 Java Flight Recorder 会话中,用于分析应用程序并将其 Spring 上下文生命周期与 JVM 事件(例如分配、GC、类加载等)相关联。 配置后,您可以通过在启用 Flight Recorder 的情况下运行应用程序来记录数据:spring-doc.cadn.net.cn

$ java -XX:StartFlightRecording:filename=recording.jfr,duration=10s -jar demo.jar

Spring Boot 附带了BufferingApplicationStartup变体;此实现用于缓冲启动步骤并将其排空到外部 Metrics 系统中。 应用程序可以请求BufferingApplicationStartup在任何组件中。spring-doc.cadn.net.cn

Spring Boot 也可以配置为公开startup端点,该文档以 JSON 文档的形式提供此信息。spring-doc.cadn.net.cn

2. 外部化配置

Spring Boot 允许您外部化配置,以便您可以在不同环境中使用相同的应用程序代码。 您可以使用各种外部配置源,包括 Java 属性文件、YAML 文件、环境变量和命令行参数。spring-doc.cadn.net.cn

属性值可以通过使用@Value注解,通过 Spring 的Environment抽象,或通过@ConfigurationProperties.spring-doc.cadn.net.cn

Spring Boot 使用非常特殊的PropertySourceorder 的 ORDER 允许合理地覆盖值。 后面的属性源可以覆盖前面的属性源中定义的值。 按以下顺序考虑源:spring-doc.cadn.net.cn

  1. 默认属性(通过设置SpringApplication.setDefaultProperties).spring-doc.cadn.net.cn

  2. @PropertySourceannotations@Configuration类。 请注意,此类属性源不会添加到Environment直到刷新应用程序上下文。 现在配置某些属性(例如logging.*spring.main.*,这些 API 将在刷新开始之前读取。spring-doc.cadn.net.cn

  3. 配置数据(例如application.properties文件)。spring-doc.cadn.net.cn

  4. 一个RandomValuePropertySource仅在random.*.spring-doc.cadn.net.cn

  5. OS 环境变量。spring-doc.cadn.net.cn

  6. Java 系统属性 (System.getProperties()).spring-doc.cadn.net.cn

  7. JNDI 属性来自java:comp/env.spring-doc.cadn.net.cn

  8. ServletContextinit 参数。spring-doc.cadn.net.cn

  9. ServletConfiginit 参数。spring-doc.cadn.net.cn

  10. 属性来自SPRING_APPLICATION_JSON(嵌入在环境变量或系统属性中的内联 JSON)。spring-doc.cadn.net.cn

  11. 命令行参数。spring-doc.cadn.net.cn

  12. properties属性。 适用于@SpringBootTest以及用于测试应用程序的特定切片的 test annotationsspring-doc.cadn.net.cn

  13. @DynamicPropertySource注解。spring-doc.cadn.net.cn

  14. @TestPropertySourceComments 的 Comments。spring-doc.cadn.net.cn

  15. Devtools 全局设置属性$HOME/.config/spring-boot目录(当 DevTools 处于活动状态时)。spring-doc.cadn.net.cn

配置数据文件按以下顺序考虑:spring-doc.cadn.net.cn

  1. 打包在 jar 中的 Application 属性application.properties和 YAML 变体)。spring-doc.cadn.net.cn

  2. 打包在 jar 中的 Profile 特定应用程序属性application-{profile}.properties和 YAML 变体)。spring-doc.cadn.net.cn

  3. 打包的 jar 之外的应用程序属性application.properties和 YAML 变体)。spring-doc.cadn.net.cn

  4. 打包的 jar 之外特定于配置文件的应用程序属性application-{profile}.properties和 YAML 变体)。spring-doc.cadn.net.cn

建议整个应用程序坚持使用一种格式。 如果您的配置文件同时包含.properties和 YAML 格式,则.properties优先。
如果使用环境变量而不是系统属性,则大多数作系统不允许使用句点分隔的键名称,但您可以使用下划线代替(例如SPRING_CONFIG_NAME而不是spring.config.name). 有关详细信息,请参阅从环境变量绑定
如果您的应用程序在 servlet 容器或应用程序服务器中运行,则 JNDI 属性(在java:comp/env) 或 Servlet 上下文初始化参数来代替环境变量或系统属性。

为了提供一个具体的例子,假设您开发了一个@Component它使用name属性,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class MyBean {

    @Value("${name}")
    private String name;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Value
import org.springframework.stereotype.Component

@Component
class MyBean {

    @Value("\${name}")
    private val name: String? = null

    // ...

}

在应用程序类路径上(例如,在 jar 中),您可以有一个application.properties文件,该文件为name. 在新环境中运行时,application.properties文件可以在 jar 外部提供,该文件会覆盖name. 对于一次性测试,您可以使用特定的命令行开关(例如java -jar app.jar --name="Spring").spring-doc.cadn.net.cn

envconfigpropsendpoints 可用于确定属性具有特定值的原因。 您可以使用这两个终端节点来诊断意外的属性值。 有关详细信息,请参阅“生产就绪功能”部分。

2.1. 访问命令行属性

默认情况下,SpringApplication转换任何命令行选项参数(即以 开头的参数,例如----server.port=9000) 转换为property并将它们添加到 Spring 中Environment. 如前所述,命令行属性始终优先于基于文件的属性源。spring-doc.cadn.net.cn

如果您不希望将命令行属性添加到Environment中,您可以使用SpringApplication.setAddCommandLineProperties(false).spring-doc.cadn.net.cn

2.2. JSON 应用程序属性

环境变量和系统属性通常具有限制,这意味着无法使用某些属性名称。 为了帮助解决这个问题, Spring Boot 允许您将一个属性块编码为单个 JSON 结构。spring-doc.cadn.net.cn

当您的应用程序启动时,任何spring.application.jsonSPRING_APPLICATION_JSONproperties 将被解析并添加到Environment.spring-doc.cadn.net.cn

例如,SPRING_APPLICATION_JSONproperty 可以作为环境变量在 UN*X shell 的命令行中提供:spring-doc.cadn.net.cn

$ SPRING_APPLICATION_JSON='{"my":{"name":"test"}}' java -jar myapp.jar

在前面的示例中,您最终会得到my.name=test在SpringEnvironment.spring-doc.cadn.net.cn

相同的 JSON 也可以作为系统属性提供:spring-doc.cadn.net.cn

$ java -Dspring.application.json='{"my":{"name":"test"}}' -jar myapp.jar

或者,您可以使用命令行参数提供 JSON:spring-doc.cadn.net.cn

$ java -jar myapp.jar --spring.application.json='{"my":{"name":"test"}}'

如果要部署到经典 Application Server,还可以使用名为java:comp/env/spring.application.json.spring-doc.cadn.net.cn

虽然nullJSON 中的值将添加到生成的属性源中,PropertySourcesPropertyResolver对待nullproperties 作为缺失值。 这意味着 JSON 无法使用null价值。

2.3. 外部应用程序属性

Spring Boot 将自动查找并加载application.propertiesapplication.yaml应用程序启动时从以下位置获取的文件:spring-doc.cadn.net.cn

  1. 从 classpathspring-doc.cadn.net.cn

    1. 类路径根spring-doc.cadn.net.cn

    2. 类路径/configspring-doc.cadn.net.cn

  2. 从当前目录spring-doc.cadn.net.cn

    1. 当前目录spring-doc.cadn.net.cn

    2. config/子目录spring-doc.cadn.net.cn

    3. 的直接子目录config/子目录spring-doc.cadn.net.cn

该列表按优先级排序(较低项中的值将覆盖较早项的值)。 加载文件中的文档将添加为PropertySources到SpringEnvironment.spring-doc.cadn.net.cn

如果您不喜欢application作为配置文件名称,您可以通过指定spring.config.nameenvironment 属性。 例如,要查找myproject.propertiesmyproject.yaml文件,您可以按如下方式运行应用程序:spring-doc.cadn.net.cn

$ java -jar myproject.jar --spring.config.name=myproject

您还可以使用spring.config.locationenvironment 属性。 此属性接受要检查的一个或多个位置的逗号分隔列表。spring-doc.cadn.net.cn

以下示例显示如何指定两个不同的文件:spring-doc.cadn.net.cn

$ java -jar myproject.jar --spring.config.location=\
    optional:classpath:/default.properties,\
    optional:classpath:/override.properties
使用前缀optional:如果位置是可选的,并且您不介意它们不存在。
spring.config.name,spring.config.locationspring.config.additional-location很早就用于确定必须加载哪些文件。 它们必须定义为环境属性(通常是 OS 环境变量、系统属性或命令行参数)。

如果spring.config.location包含目录(而不是文件),它们应以 . 在运行时,它们将附加从/spring.config.name在加载之前。 在spring.config.location直接导入。spring-doc.cadn.net.cn

目录和文件位置值也都进行了扩展,以检查特定于配置文件的文件。 例如,如果你有一个spring.config.locationclasspath:myconfig.properties,您也会找到合适的classpath:myconfig-<profile>.properties文件。

在大多数情况下,每个spring.config.location项将引用单个文件或目录。 位置按其定义顺序进行处理,较晚的位置可以覆盖较早的位置的值。spring-doc.cadn.net.cn

如果你有一个复杂的位置设置,并且你使用特定于配置文件的配置文件,你可能需要提供进一步的提示,以便 Spring Boot 知道应该如何对它们进行分组。 位置组是所有位置都被视为同一级别的位置的集合。 例如,您可能希望对所有 Classpath 位置进行分组,然后对所有外部位置进行分组。 位置组中的项目应以 分隔。 有关更多详细信息,请参阅“分析特定文件”部分中的示例。;spring-doc.cadn.net.cn

使用 配置 Locationspring.config.location替换 Default Locations。 例如,如果spring.config.location配置了值optional:classpath:/custom-config/,optional:file:./custom-config/,则考虑的完整位置集为:spring-doc.cadn.net.cn

  1. optional:classpath:custom-config/spring-doc.cadn.net.cn

  2. optional:file:./custom-config/spring-doc.cadn.net.cn

如果您希望添加其他位置,而不是替换它们,则可以使用spring.config.additional-location. 从其他位置加载的属性可以覆盖默认位置中的属性。 例如,如果spring.config.additional-location配置了值optional:classpath:/custom-config/,optional:file:./custom-config/,则考虑的完整位置集为:spring-doc.cadn.net.cn

  1. optional:classpath:/;optional:classpath:/config/spring-doc.cadn.net.cn

  2. optional:file:./;optional:file:./config/;optional:file:./config/*/spring-doc.cadn.net.cn

  3. optional:classpath:custom-config/spring-doc.cadn.net.cn

  4. optional:file:./custom-config/spring-doc.cadn.net.cn

此搜索顺序允许您在一个配置文件中指定默认值,然后在另一个配置文件中选择性地覆盖这些值。 您可以在application.properties(或您选择的任何其他 basenamespring.config.name) 中的一个默认位置。 然后,可以在运行时使用位于其中一个自定义位置的不同文件覆盖这些默认值。spring-doc.cadn.net.cn

2.3.1. 可选位置

默认情况下,当指定的配置数据位置不存在时, Spring Boot 将抛出一个ConfigDataLocationNotFoundException,并且您的应用程序将无法启动。spring-doc.cadn.net.cn

如果要指定一个位置,但又不介意它并不总是存在,则可以使用optional:前缀。 您可以将此前缀与spring.config.locationspring.config.additional-location属性,以及spring.config.import声明。spring-doc.cadn.net.cn

例如,spring.config.import的值optional:file:./myconfig.properties允许您的应用程序启动,即使myconfig.properties文件丢失。spring-doc.cadn.net.cn

如果要忽略所有ConfigDataLocationNotFoundExceptions并始终继续启动应用程序,则可以使用spring.config.on-not-found财产。 将值设置为ignoreSpringApplication.setDefaultProperties(…​)或使用 system/environment 变量。spring-doc.cadn.net.cn

2.3.2. 通配符位置

如果配置文件位置包含最后一个路径段的字符,则将其视为通配符位置。 加载配置时,通配符会展开,以便同时检查直接子目录。 通配符位置在 Kubernetes 等环境中,当有多个 config 属性来源时特别有用。*spring-doc.cadn.net.cn

例如,如果您有一些 Redis 配置和一些 MySQL 配置,您可能希望将这两个配置分开,同时要求这两个配置都存在于application.properties文件。 这可能会导致两个单独的application.properties文件挂载在不同位置,例如/config/redis/application.properties/config/mysql/application.properties. 在这种情况下,将通配符位置设置为config/*/)将导致两个文件都被处理。spring-doc.cadn.net.cn

默认情况下,Spring Boot 包括config/*/在默认搜索位置。 这意味着/config目录中。spring-doc.cadn.net.cn

您可以自己将通配符位置与spring.config.locationspring.config.additional-location性能。spring-doc.cadn.net.cn

通配符位置必须仅包含一个通配符位置,并且对于目录或**/*/<filename>对于作为文件的搜索位置。 带有通配符的位置根据文件名的绝对路径按字母顺序排序。
通配符位置仅适用于外部目录。 您不能在classpath:位置。

2.3.3. 分析特定文件

以及applicationproperty 文件,Spring Boot 还将尝试使用命名约定加载特定于配置文件的文件application-{profile}. 例如,如果您的应用程序激活了名为prod并使用 YAML 文件,那么两者application.yamlapplication-prod.yaml将被考虑。spring-doc.cadn.net.cn

特定于配置文件的属性从与标准相同的位置加载application.properties,特定于配置文件的文件始终覆盖非特定文件。 如果指定了多个配置文件,则适用 last-wins 策略。 例如,如果配置文件prod,livespring.profiles.active属性, 值application-prod.properties可以被application-live.properties.spring-doc.cadn.net.cn

“最后获胜”策略适用于营业地点组级别。 一个spring.config.locationclasspath:/cfg/,classpath:/ext/将具有与classpath:/cfg/;classpath:/ext/.spring-doc.cadn.net.cn

例如,继续我们的prod,live例如,我们可能有以下文件:spring-doc.cadn.net.cn

/cfg
  application-live.properties
/ext
  application-live.properties
  application-prod.properties

当我们有一个spring.config.locationclasspath:/cfg/,classpath:/ext/我们处理所有/cfgfiles before all (所有/ext文件:spring-doc.cadn.net.cn

  1. /cfg/application-live.propertiesspring-doc.cadn.net.cn

  2. /ext/application-prod.propertiesspring-doc.cadn.net.cn

  3. /ext/application-live.propertiesspring-doc.cadn.net.cn

当我们有classpath:/cfg/;classpath:/ext/相反(使用分隔符),我们处理;/cfg/ext在同一级别:spring-doc.cadn.net.cn

  1. /ext/application-prod.propertiesspring-doc.cadn.net.cn

  2. /cfg/application-live.propertiesspring-doc.cadn.net.cn

  3. /ext/application-live.propertiesspring-doc.cadn.net.cn

Environment具有一组默认配置文件(默认情况下,[default]),如果未设置活动配置文件,则使用该配置文件。 换句话说,如果未显式激活任何配置文件,则application-default被考虑。spring-doc.cadn.net.cn

属性文件只加载一次。 如果您已经直接导入了特定于配置文件的属性文件,则不会再次导入它。

2.3.4. 导入其他数据

应用程序属性可以使用spring.config.import财产。 导入在被发现时进行处理,并被视为插入到声明导入的导入文档的正下方的附加文档。spring-doc.cadn.net.cn

例如,您的类路径中可能有以下内容application.properties文件:spring-doc.cadn.net.cn

性能
spring.application.name=myapp
spring.config.import=optional:file:./dev.properties
Yaml
spring:
  application:
    name: "myapp"
  config:
    import: "optional:file:./dev.properties"

这将触发dev.properties当前目录中的文件(如果存在此类文件)。 导入的dev.properties将优先于触发导入的文件。 在上面的示例中,dev.properties可以重新定义spring.application.name更改为不同的值。spring-doc.cadn.net.cn

无论声明多少次,导入都只会导入一次。 在 properties/yaml 文件中的单个文档中定义导入的顺序无关紧要。 例如,下面的两个示例产生相同的结果:spring-doc.cadn.net.cn

性能
spring.config.import=my.properties
my.property=value
Yaml
spring:
  config:
    import: "my.properties"
my:
  property: "value"
性能
my.property=value
spring.config.import=my.properties
Yaml
my:
  property: "value"
spring:
  config:
    import: "my.properties"

在上述两个示例中,my.propertiesfile 将优先于触发其导入的文件。spring-doc.cadn.net.cn

可以在单个spring.config.import钥匙。 位置将按照定义的顺序进行处理,以后的导入优先。spring-doc.cadn.net.cn

在适当时,还会考虑导入特定于 Profile 的变体。 上面的示例将导入my.properties以及任何my-<profile>.properties变种。

Spring Boot 包含可插拔 API,允许支持各种不同的位置地址。 默认情况下,您可以导入 Java 属性、YAML 和“配置树”。spring-doc.cadn.net.cn

第三方 jar 可以提供对其他技术的支持(不要求文件是本地的)。 例如,您可以想象配置数据来自 Consul、Apache ZooKeeper 或 Netflix Archaius 等外部存储。spring-doc.cadn.net.cn

如果要支持自己的位置,请参阅ConfigDataLocationResolverConfigDataLoader类中的org.springframework.boot.context.config包。spring-doc.cadn.net.cn

2.3.5. 导入无扩展文件

某些云平台无法向卷挂载的文件添加文件扩展名。 要导入这些无扩展名文件,你需要给 Spring Boot 一个提示,以便它知道如何加载它们。 您可以通过在方括号中放置扩展提示来执行此作。spring-doc.cadn.net.cn

例如,假设您有一个/etc/config/myconfig要作为 YAML 导入的文件。 您可以从application.properties使用以下内容:spring-doc.cadn.net.cn

性能
spring.config.import=file:/etc/config/myconfig[.yaml]
Yaml
spring:
  config:
    import: "file:/etc/config/myconfig[.yaml]"

2.3.6. 使用配置树

在云平台(如 Kubernetes)上运行应用程序时,您通常需要读取平台提供的配置值。 将环境变量用于此类目的并不少见,但这可能有缺点,尤其是在值应该保密的情况下。spring-doc.cadn.net.cn

作为环境变量的替代方案,许多云平台现在允许您将配置映射到挂载的数据卷。 例如,Kubernetes 可以同时对ConfigMapsSecrets.spring-doc.cadn.net.cn

可以使用两种常见的卷挂载模式:spring-doc.cadn.net.cn

  1. 单个文件包含一组完整的属性(通常写为 YAML)。spring-doc.cadn.net.cn

  2. 多个文件被写入目录树,文件名成为 'key',内容成为 'value'。spring-doc.cadn.net.cn

对于第一种情况,您可以直接使用spring.config.import如上所述。 对于第二种情况,您需要使用configtree:前缀,以便 Spring Boot 知道它需要将所有文件公开为属性。spring-doc.cadn.net.cn

例如,假设 Kubernetes 挂载了以下卷:spring-doc.cadn.net.cn

etc/
  config/
    myapp/
      username
      password

usernamefile 将是一个 config 值,而password将是一个秘密。spring-doc.cadn.net.cn

要导入这些属性,您可以将以下内容添加到application.propertiesapplication.yaml文件:spring-doc.cadn.net.cn

性能
spring.config.import=optional:configtree:/etc/config/
Yaml
spring:
  config:
    import: "optional:configtree:/etc/config/"

然后,您可以访问或注入myapp.usernamemyapp.password属性Environment以通常的方式。spring-doc.cadn.net.cn

配置树下的文件夹和文件的名称构成属性名称。 在上面的示例中,要将属性作为usernamepassword中,您可以设置spring.config.importoptional:configtree:/etc/config/myapp.
带有点表示法的文件名也会正确映射。 例如,在上面的示例中,名为myapp.username/etc/config将导致myapp.username属性在Environment.
配置树值可以绑定到两个字符串Stringbyte[]类型。

如果要从同一个父文件夹导入多个配置树,则可以使用通配符快捷方式。 任何configtree:location 结尾的 Location 会将所有直接子项作为配置树导入。 与非通配符导入一样,每个配置树下的文件夹和文件的名称构成属性名称。/*/spring-doc.cadn.net.cn

例如,给定以下卷:spring-doc.cadn.net.cn

etc/
  config/
    dbconfig/
      db/
        username
        password
    mqconfig/
      mq/
        username
        password

您可以使用configtree:/etc/config/*/作为导入位置:spring-doc.cadn.net.cn

性能
spring.config.import=optional:configtree:/etc/config/*/
Yaml
spring:
  config:
    import: "optional:configtree:/etc/config/*/"

这将添加db.username,db.password,mq.usernamemq.password性能。spring-doc.cadn.net.cn

使用通配符加载的目录按字母顺序排序。 如果您需要不同的顺序,则应将每个位置列为单独的导入

配置树还可用于 Docker 密钥。 当 Docker Swarm 服务被授予对 secret 的访问权限时,secret 将被挂载到容器中。 例如,如果名为db.password安装在/run/secrets/,您可以使db.password可用于 Spring 环境:spring-doc.cadn.net.cn

性能
spring.config.import=optional:configtree:/run/secrets/
Yaml
spring:
  config:
    import: "optional:configtree:/run/secrets/"

2.3.7. 属性占位符

中的 valueapplication.propertiesapplication.yaml通过现有的Environment,以便您可以参考以前定义的值(例如,从 System properties 或 environment variables)。 标准${name}property-placeholder 语法可以在值中的任何位置使用。 属性占位符还可以使用:将默认值与属性名称分开,例如${name:default}.spring-doc.cadn.net.cn

以下示例显示了带和不带默认值的占位符的用法:spring-doc.cadn.net.cn

性能
app.name=MyApp
app.description=${app.name} is a Spring Boot application written by ${username:Unknown}
Yaml
app:
  name: "MyApp"
  description: "${app.name} is a Spring Boot application written by ${username:Unknown}"

假设usernameproperty 没有在其他位置设置,app.description将具有值MyApp is a Spring Boot application written by Unknown.spring-doc.cadn.net.cn

您应该始终使用其规范形式(kebab-case 仅使用小写字母)在占位符中引用属性名称。 这将允许 Spring Boot 使用与松散绑定时相同的逻辑 @ConfigurationProperties.spring-doc.cadn.net.cn

例如${demo.item-price}会接球demo.item-pricedemo.itemPrice表单中application.properties文件以及DEMO_ITEMPRICE从系统环境。 如果您使用了${demo.itemPrice}相反demo.item-priceDEMO_ITEMPRICE不会被考虑。spring-doc.cadn.net.cn

您还可以使用此技术创建现有 Spring Boot 属性的“短”变体。 有关详细信息,请参阅 howto.html作方法。

2.3.8. 使用多文档文件

Spring Boot 允许您将单个物理文件拆分为多个 logical 文档,每个 logical 文档都是独立添加的。 文档按从上到下的顺序处理。 后面的文档可以覆盖前面文档中定义的属性。spring-doc.cadn.net.cn

application.yaml文件,则使用标准的 YAML 多文档语法。 三个连续的连字符表示一个文档的结尾和下一个文档的开头。spring-doc.cadn.net.cn

例如,以下文件有两个逻辑文档:spring-doc.cadn.net.cn

spring:
  application:
    name: "MyApp"
---
spring:
  application:
    name: "MyCloudApp"
  config:
    activate:
      on-cloud-platform: "kubernetes"

application.properties文件,一个特殊的或#---!---comment 用于标记文档拆分:spring-doc.cadn.net.cn

spring.application.name=MyApp
#---
spring.application.name=MyCloudApp
spring.config.activate.on-cloud-platform=kubernetes
属性文件分隔符不得有任何前导空格,并且必须恰好包含三个连字符。 紧接在分隔符之前和之后的行不能是相同的注释前缀。
多文档属性文件通常与激活属性结合使用,例如spring.config.activate.on-profile. 有关详细信息,请参阅下一节
无法使用@PropertySource@TestPropertySource附注。

2.3.9. 激活属性

有时,仅在满足某些条件时激活一组给定的属性很有用。 例如,您可能具有仅在特定配置文件处于活动状态时才相关的属性。spring-doc.cadn.net.cn

您可以使用spring.config.activate.*.spring-doc.cadn.net.cn

可以使用以下激活属性:spring-doc.cadn.net.cn

表 2.激活属性
财产 注意

on-profilespring-doc.cadn.net.cn

必须匹配的配置文件表达式,文档才能处于活动状态。spring-doc.cadn.net.cn

on-cloud-platformspring-doc.cadn.net.cn

CloudPlatform必须检测到该 ID 才能使文档处于活动状态。spring-doc.cadn.net.cn

例如,以下指定第二个文档仅在 Kubernetes 上运行时处于活动状态,并且仅当 “prod” 或 “staging” 配置文件处于活动状态时:spring-doc.cadn.net.cn

性能
myprop=always-set
#---
spring.config.activate.on-cloud-platform=kubernetes
spring.config.activate.on-profile=prod | staging
myotherprop=sometimes-set
Yaml
myprop:
  "always-set"
---
spring:
  config:
    activate:
      on-cloud-platform: "kubernetes"
      on-profile: "prod | staging"
myotherprop: "sometimes-set"

2.4. 加密属性

Spring Boot 不提供对加密属性值的任何内置支持,但是,它确实提供了修改 Spring 中包含的值所需的钩子点Environment. 这EnvironmentPostProcessor界面允许您作Environment在应用程序启动之前。 有关详细信息,请参阅 howto.htmlspring-doc.cadn.net.cn

如果你需要一种安全的方式来存储凭证和密码,Spring Cloud Vault 项目提供了在 HashiCorp Vault 中存储外部化配置的支持。spring-doc.cadn.net.cn

2.5. 使用 YAML

YAML 是 JSON 的超集,因此是指定分层配置数据的便捷格式。 这SpringApplication每当 Classpath 上有 SnakeYAML 库时,class 都会自动支持 YAML 作为属性的替代方案。spring-doc.cadn.net.cn

如果您使用 “Starters”,则 SnakeYAML 由spring-boot-starter.

2.5.1. 将 YAML 映射到属性

YAML 文档需要从它们的分层格式转换为可以与 Spring 一起使用的平面结构Environment. 例如,请考虑以下 YAML 文档:spring-doc.cadn.net.cn

environments:
  dev:
    url: "https://dev.example.com"
    name: "Developer Setup"
  prod:
    url: "https://another.example.com"
    name: "My Cool App"

为了从Environment,它们将被平展,如下所示:spring-doc.cadn.net.cn

environments.dev.url=https://dev.example.com
environments.dev.name=Developer Setup
environments.prod.url=https://another.example.com
environments.prod.name=My Cool App

同样,YAML 列表也需要扁平化。 它们表示为属性键,其中[index]dereferencers 的 dereferencers。 例如,请考虑以下 YAML:spring-doc.cadn.net.cn

my:
 servers:
 - "dev.example.com"
 - "another.example.com"

前面的示例将转换为以下属性:spring-doc.cadn.net.cn

my.servers[0]=dev.example.com
my.servers[1]=another.example.com
使用[index]表示法可以绑定到 JavaListSet对象使用 Spring Boot 的Binder类。 有关更多详细信息,请参阅下面的“类型安全配置属性”部分。
无法使用@PropertySource@TestPropertySource附注。 因此,如果需要以这种方式加载值,则需要使用属性文件。

2.5.2. 直接加载 YAML

Spring Framework 提供了两个方便的类,可用于加载 YAML 文档。 这YamlPropertiesFactoryBean将 YAML 加载为PropertiesYamlMapFactoryBean将 YAML 加载为Map.spring-doc.cadn.net.cn

您还可以使用YamlPropertySourceLoaderclass (如果要将 YAML 加载为 Spring)PropertySource.spring-doc.cadn.net.cn

2.6. 配置随机值

RandomValuePropertySource对于注入随机值(例如,注入 secret 或测试用例)非常有用。 它可以生成整数、长整型、uuid 或字符串,如以下示例所示:spring-doc.cadn.net.cn

性能
my.secret=${random.value}
my.number=${random.int}
my.bignumber=${random.long}
my.uuid=${random.uuid}
my.number-less-than-ten=${random.int(10)}
my.number-in-range=${random.int[1024,65536]}
Yaml
my:
  secret: "${random.value}"
  number: "${random.int}"
  bignumber: "${random.long}"
  uuid: "${random.uuid}"
  number-less-than-ten: "${random.int(10)}"
  number-in-range: "${random.int[1024,65536]}"

random.int*syntax 为OPEN value (,max) CLOSE其中,OPEN,CLOSE是任何字符,并且value,max是整数。 如果max,则value是最小值,而max是最大值 (不包括)。spring-doc.cadn.net.cn

2.7. 配置系统环境属性

Spring Boot 支持为环境属性设置前缀。 如果系统环境由具有不同配置要求的多个 Spring Boot 应用程序共享,这将非常有用。 系统环境属性的前缀可以直接在SpringApplication.spring-doc.cadn.net.cn

例如,如果将前缀设置为input,则remote.timeout也将解析为input.remote.timeout在系统环境中。spring-doc.cadn.net.cn

2.8. 类型安全的配置属性

使用@Value("${property}")Annotation 来注入配置属性有时会很麻烦,特别是当你正在使用多个属性或者你的数据本质上是分层的。 Spring Boot 提供了一种使用属性的替代方法,该方法允许强类型 bean 管理和验证应用程序的配置。spring-doc.cadn.net.cn

2.8.1. JavaBean 属性绑定

可以绑定声明标准 JavaBean 属性的 Bean,如下例所示:spring-doc.cadn.net.cn

Java
import java.net.InetAddress;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

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

@ConfigurationProperties("my.service")
public class MyProperties {

    private boolean enabled;

    private InetAddress remoteAddress;

    private final Security security = new Security();

    // getters / setters...

    public boolean isEnabled() {
        return this.enabled;
    }

    public void setEnabled(boolean enabled) {
        this.enabled = enabled;
    }

    public InetAddress getRemoteAddress() {
        return this.remoteAddress;
    }

    public void setRemoteAddress(InetAddress remoteAddress) {
        this.remoteAddress = remoteAddress;
    }

    public Security getSecurity() {
        return this.security;
    }

    public static class Security {

        private String username;

        private String password;

        private List<String> roles = new ArrayList<>(Collections.singleton("USER"));

        // getters / setters...

        public String getUsername() {
            return this.username;
        }

        public void setUsername(String username) {
            this.username = username;
        }

        public String getPassword() {
            return this.password;
        }

        public void setPassword(String password) {
            this.password = password;
        }

        public List<String> getRoles() {
            return this.roles;
        }

        public void setRoles(List<String> roles) {
            this.roles = roles;
        }

    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import java.net.InetAddress

@ConfigurationProperties("my.service")
class MyProperties {

    var isEnabled = false

    var remoteAddress: InetAddress? = null

    val security = Security()

    class Security {

        var username: String? = null

        var password: String? = null

        var roles: List<String> = ArrayList(setOf("USER"))

    }

}

前面的 POJO 定义了以下属性:spring-doc.cadn.net.cn

映射到@ConfigurationPropertiesSpring Boot 中可用的类(通过属性文件、YAML 文件、环境变量和其他机制进行配置)是公共 API,但类本身的访问器(getter/setter)不能直接使用。

这种安排依赖于默认的空构造函数,并且 getter 和 setter 通常是强制性的,因为绑定是通过标准 Java Beans 属性描述符进行的,就像在 Spring MVC 中一样。 在以下情况下,可以省略 setter:spring-doc.cadn.net.cn

  • 只要 Map 被初始化,就需要一个 getter,但不一定是一个 setter,因为它们可以被 binders 改变。spring-doc.cadn.net.cn

  • 可以通过索引(通常使用 YAML)或使用单个逗号分隔值(properties)来访问集合和数组。 在后一种情况下,setter 是必需的。 我们建议始终为此类类型添加 setter。 如果初始化集合,请确保它不是不可变的(如前面的示例所示)。spring-doc.cadn.net.cn

  • 如果嵌套的 POJO 属性被初始化(如Security字段),则不需要 setter。 如果希望 Binders 使用其默认构造函数动态创建实例,则需要 setter。spring-doc.cadn.net.cn

有些人使用 Project Lombok 自动添加 getter 和 setter。 确保 Lombok 不会为此类类型生成任何特定的构造函数,因为容器会自动使用它来实例化对象。spring-doc.cadn.net.cn

最后,仅考虑标准 Java Bean 属性,不支持对静态属性进行绑定。spring-doc.cadn.net.cn

2.8.2. 构造函数绑定

上一节中的示例可以以不可变的方式重写,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.net.InetAddress;
import java.util.List;

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

@ConfigurationProperties("my.service")
public class MyProperties {

    // fields...

    private final boolean enabled;

    private final InetAddress remoteAddress;

    private final Security security;

    public MyProperties(boolean enabled, InetAddress remoteAddress, Security security) {
        this.enabled = enabled;
        this.remoteAddress = remoteAddress;
        this.security = security;
    }

    // getters...

    public boolean isEnabled() {
        return this.enabled;
    }

    public InetAddress getRemoteAddress() {
        return this.remoteAddress;
    }

    public Security getSecurity() {
        return this.security;
    }

    public static class Security {

        // fields...

        private final String username;

        private final String password;

        private final List<String> roles;

        public Security(String username, String password, @DefaultValue("USER") List<String> roles) {
            this.username = username;
            this.password = password;
            this.roles = roles;
        }

        // getters...

        public String getUsername() {
            return this.username;
        }

        public String getPassword() {
            return this.password;
        }

        public List<String> getRoles() {
            return this.roles;
        }

    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.bind.DefaultValue
import java.net.InetAddress

@ConfigurationProperties("my.service")
class MyProperties(val enabled: Boolean, val remoteAddress: InetAddress,
        val security: Security) {

    class Security(val username: String, val password: String,
            @param:DefaultValue("USER") val roles: List<String>)

}

在此设置中,存在单个参数化构造函数意味着应使用构造函数绑定。 这意味着 Binder 将找到一个构造函数,其中包含您希望绑定的参数。 如果您的类有多个构造函数,则@ConstructorBindingannotation 可用于指定要用于构造函数绑定的构造函数。 要选择退出具有单个参数化构造函数的类的构造函数绑定,必须为构造函数添加@Autowired或制造private. 构造函数绑定可以与记录一起使用。 除非您的记录具有多个构造函数,否则无需使用@ConstructorBinding.spring-doc.cadn.net.cn

构造函数绑定类的嵌套成员(例如Security在上面的示例中)也将通过其构造函数进行绑定。spring-doc.cadn.net.cn

默认值可以使用@DefaultValueon constructor parameters 和 record components. 转换服务将用于强制注释的Stringvalue 设置为缺失属性的目标类型。spring-doc.cadn.net.cn

参考前面的示例,如果没有属性绑定到SecurityMyProperties实例将包含一个null的值security. 要使其包含Security即使没有绑定到任何属性(使用 Kotlin 时,这也需要usernamepassword参数Security要声明为可为 null,因为它们没有默认值),请使用空的@DefaultValue注解:spring-doc.cadn.net.cn

Java
public MyProperties(boolean enabled, InetAddress remoteAddress, @DefaultValue Security security) {
    this.enabled = enabled;
    this.remoteAddress = remoteAddress;
    this.security = security;
}
Kotlin
class MyProperties(val enabled: Boolean, val remoteAddress: InetAddress,
        @DefaultValue val security: Security) {

    class Security(val username: String?, val password: String?,
            @param:DefaultValue("USER") val roles: List<String>)

}
要使用构造函数绑定,必须使用@EnableConfigurationProperties或配置属性 scanning。 你不能将构造函数绑定与由常规 Spring 机制创建的 bean 一起使用(例如@Componentbean, 使用 创建的 bean@Bean方法或 bean@Import)
要在本机映像中使用构造函数绑定,必须使用-parameters. 如果您使用 Spring Boot 的 Gradle 插件,或者如果您使用 Maven 和spring-boot-starter-parent.
的使用java.util.Optional@ConfigurationProperties不建议使用,因为它主要用作返回类型。 因此,它不太适合 configuration property injection。 为了与其他类型的属性保持一致,如果您确实声明了Optionalproperty 并且它没有值,null而不是空的Optional将被绑定。

2.8.3. 启用 @ConfigurationProperties 注解类型

Spring Boot 提供了用于绑定的基础设施@ConfigurationProperties类型并将它们注册为 Bean。 您可以逐个类启用配置属性,也可以启用配置属性扫描,其工作方式与组件扫描类似。spring-doc.cadn.net.cn

有时,用@ConfigurationProperties可能不适合扫描,例如,如果您正在开发自己的自动配置或想要有条件地启用它们。 在这些情况下,请使用@EnableConfigurationProperties注解。 这可以在任何@Configuration类,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties.class)
public class MyConfiguration {

}
Kotlin
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(SomeProperties::class)
class MyConfiguration
Java
import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("some.properties")
public class SomeProperties {

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties("some.properties")
class SomeProperties

要使用配置属性扫描,请添加@ConfigurationPropertiesScan注解添加到您的应用程序。 通常,它被添加到带有@SpringBootApplication但它可以添加到任何@Configuration类。 默认情况下,将从声明 Comments 的类的包中进行扫描。 如果要定义要扫描的特定包,可以按以下示例所示执行此作:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;

@SpringBootApplication
@ConfigurationPropertiesScan({ "com.example.app", "com.example.another" })
public class MyApplication {

}
Kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.context.properties.ConfigurationPropertiesScan

@SpringBootApplication
@ConfigurationPropertiesScan("com.example.app", "com.example.another")
class MyApplication

@ConfigurationProperties使用 Configuration Property scanning 或通过@EnableConfigurationProperties,该 bean 有一个约定俗成的名称:<prefix>-<fqn>哪里<prefix>是在@ConfigurationPropertiesannotation 和<fqn>是 Bean 的完全限定名称。 如果 Comments 未提供任何前缀,则仅使用 Bean 的完全限定名称。spring-doc.cadn.net.cn

假设它在com.example.apppackage 中,则SomeProperties上面的示例是some.properties-com.example.app.SomeProperties.spring-doc.cadn.net.cn

我们建议@ConfigurationProperties仅处理环境,特别是,不从上下文中注入其他 bean。 对于极端情况,可以使用 setter 注入或任何*Aware框架提供的接口(例如EnvironmentAware如果您需要访问Environment). 如果您仍然希望使用构造函数注入其他 bean,则必须使用@Component并使用基于 JavaBean 的属性绑定。spring-doc.cadn.net.cn

2.8.4. 使用 @ConfigurationProperties 注解类型

这种配置样式特别适用于SpringApplicationexternal YAML 配置,如以下示例所示:spring-doc.cadn.net.cn

my:
  service:
    remote-address: 192.168.1.1
    security:
      username: "admin"
      roles:
      - "USER"
      - "ADMIN"

使用@ConfigurationPropertiesbeans 中,你可以像注入任何其他 bean 一样注入它们,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.stereotype.Service;

@Service
public class MyService {

    private final MyProperties properties;

    public MyService(MyProperties properties) {
        this.properties = properties;
    }

    public void openConnection() {
        Server server = new Server(this.properties.getRemoteAddress());
        server.start();
        // ...
    }

    // ...

}
Kotlin
import org.springframework.stereotype.Service

@Service
class MyService(val properties: MyProperties) {

    fun openConnection() {
        val server = Server(properties.remoteAddress)
        server.start()
        // ...
    }

    // ...

}
@ConfigurationProperties还允许您生成元数据文件,IDE 可以使用这些文件为您自己的键提供自动完成功能。 有关详细信息,请参阅附录

2.8.5. 第三方配置

除了使用@ConfigurationProperties要对类进行注释,您还可以在 public 上使用它@Bean方法。 当您希望将属性绑定到不受控制的第三方组件时,这样做可能特别有用。spring-doc.cadn.net.cn

要从Environmentproperties (属性),添加@ConfigurationProperties添加到其 bean 注册中,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class ThirdPartyConfiguration {

    @Bean
    @ConfigurationProperties(prefix = "another")
    public AnotherComponent anotherComponent() {
        return new AnotherComponent();
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class ThirdPartyConfiguration {

    @Bean
    @ConfigurationProperties(prefix = "another")
    fun anotherComponent(): AnotherComponent = AnotherComponent()

}

使用anotherprefix 映射到该AnotherComponentbean 以类似于前面的方式SomeProperties例。spring-doc.cadn.net.cn

2.8.6. 松散绑定

Spring Boot 使用一些宽松的规则进行绑定Environmentproperties 设置为@ConfigurationPropertiesbeans,因此Environmentproperty name 和 bean property name 的 bean 属性名称。 这有用的常见示例包括以破折号分隔的环境属性(例如context-path绑定到contextPath) 和大写环境属性(例如PORT绑定到port).spring-doc.cadn.net.cn

例如,请考虑以下@ConfigurationProperties类:spring-doc.cadn.net.cn

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

@ConfigurationProperties(prefix = "my.main-project.person")
public class MyPersonProperties {

    private String firstName;

    public String getFirstName() {
        return this.firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties(prefix = "my.main-project.person")
class MyPersonProperties {

    var firstName: String? = null

}

使用上述代码,可以使用以下属性名称:spring-doc.cadn.net.cn

表 3.松绑
财产 注意

my.main-project.person.first-namespring-doc.cadn.net.cn

烤肉盒,推荐用于.properties和 YAML 文件。spring-doc.cadn.net.cn

my.main-project.person.firstNamespring-doc.cadn.net.cn

标准 Camel 大小写语法。spring-doc.cadn.net.cn

my.main-project.person.first_namespring-doc.cadn.net.cn

下划线表示法,这是.properties和 YAML 文件。spring-doc.cadn.net.cn

MY_MAINPROJECT_PERSON_FIRSTNAMEspring-doc.cadn.net.cn

大写格式,使用系统环境变量时推荐使用。spring-doc.cadn.net.cn

prefix必须采用 kebab 大小写(小写,并用 、 等-my.main-project.person).
表 4.每个属性源的松散绑定规则
Property Source 简单 列表

属性文件spring-doc.cadn.net.cn

驼峰式大小写、kebab 大小写或下划线表示法spring-doc.cadn.net.cn

使用 或 逗号分隔值的标准列表语法[ ]spring-doc.cadn.net.cn

YAML 文件spring-doc.cadn.net.cn

驼峰式大小写、kebab 大小写或下划线表示法spring-doc.cadn.net.cn

标准 YAML 列表语法或逗号分隔值spring-doc.cadn.net.cn

环境变量spring-doc.cadn.net.cn

大写格式,下划线作为分隔符(请参阅从环境变量绑定)。spring-doc.cadn.net.cn

用下划线括起来的数值(请参见从环境变量绑定)spring-doc.cadn.net.cn

系统属性spring-doc.cadn.net.cn

驼峰式大小写、kebab 大小写或下划线表示法spring-doc.cadn.net.cn

使用 或 逗号分隔值的标准列表语法[ ]spring-doc.cadn.net.cn

我们建议尽可能以小写 kebab 格式存储属性,例如my.person.first-name=Rod.
绑定映射

当绑定到Map属性中,你可能需要使用特殊的方括号表示法,以便原始的key值。 如果键未被 、 任何非字母数字字符括起来,或者[]-.被删除。spring-doc.cadn.net.cn

例如,考虑将以下属性绑定到Map<String,String>:spring-doc.cadn.net.cn

性能
my.map.[/key1]=value1
my.map.[/key2]=value2
my.map./key3=value3
Yaml
my:
  map:
    "[/key1]": "value1"
    "[/key2]": "value2"
    "/key3": "value3"
对于 YAML 文件,括号需要用引号括起来,以便正确解析键。

上面的属性将绑定到Map/key1,/key2key3作为映射中的键。 斜杠已从key3因为它没有被方括号包围。spring-doc.cadn.net.cn

当绑定到标量值时,带有.在它们中不需要被 . 标量值包括 enum 和[]java.lang包(除Object. 捆绑a.b=cMap<String, String>将保留.并返回一个 Map,并返回一个 Map,其中包含{"a.b"="c"}. 对于任何其他类型,如果你的key包含一个.. 例如,将a.b=cMap<String, Object>将返回一个 Map,其中包含{"a"={"b"="c"}}[a.b]=c将返回一个 Map,其中包含{"a.b"="c"}.spring-doc.cadn.net.cn

从环境变量绑定

大多数作系统对可用于环境变量的名称施加了严格的规则。 例如,Linux shell 变量只能包含字母 (azAZ)、数字 (09) 或下划线字符 ()。 按照惯例,Unix shell 变量的名称也将采用 UPPERCASE。_spring-doc.cadn.net.cn

Spring Boot 的宽松绑定规则尽可能地设计为与这些命名限制兼容。spring-doc.cadn.net.cn

要将 canonical-form 中的属性名称转换为环境变量名称,您可以遵循以下规则:spring-doc.cadn.net.cn

例如,configuration 属性spring.main.log-startup-info将是名为SPRING_MAIN_LOGSTARTUPINFO.spring-doc.cadn.net.cn

绑定到对象列表时,也可以使用环境变量。 要绑定到List,元素编号应在变量名称中用下划线括起来。spring-doc.cadn.net.cn

例如,configuration 属性my.service[0].other将使用名为MY_SERVICE_0_OTHER.spring-doc.cadn.net.cn

缓存

松散绑定使用缓存来提高性能。默认情况下,此缓存仅应用于不可变属性源。 要自定义此行为,例如为可变属性源启用缓存,请使用ConfigurationPropertyCaching.spring-doc.cadn.net.cn

2.8.7. 合并复杂类型

在多个位置配置列表时,覆盖的工作原理是替换整个列表。spring-doc.cadn.net.cn

例如,假设MyPojoobject 替换为namedescription属性null默认情况下。 以下示例公开了MyPojo对象MyProperties:spring-doc.cadn.net.cn

Java
import java.util.ArrayList;
import java.util.List;

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

@ConfigurationProperties("my")
public class MyProperties {

    private final List<MyPojo> list = new ArrayList<>();

    public List<MyPojo> getList() {
        return this.list;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties("my")
class MyProperties {

    val list: List<MyPojo> = ArrayList()

}

请考虑以下配置:spring-doc.cadn.net.cn

性能
my.list[0].name=my name
my.list[0].description=my description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name
Yaml
my:
  list:
  - name: "my name"
    description: "my description"
---
spring:
  config:
    activate:
      on-profile: "dev"
my:
  list:
  - name: "my another name"

如果devprofile 未激活,MyProperties.list包含一个MyPojo条目。 如果dev配置文件,但是,list 仍然只包含一个条目(名称为my another name以及null). 此配置不会添加第二个MyPojo实例添加到列表中,并且不会合并项。spring-doc.cadn.net.cn

List在多个配置文件中指定,则使用优先级最高的配置文件(并且仅使用该配置文件)。 请考虑以下示例:spring-doc.cadn.net.cn

性能
my.list[0].name=my name
my.list[0].description=my description
my.list[1].name=another name
my.list[1].description=another description
#---
spring.config.activate.on-profile=dev
my.list[0].name=my another name
Yaml
my:
  list:
  - name: "my name"
    description: "my description"
  - name: "another name"
    description: "another description"
---
spring:
  config:
    activate:
      on-profile: "dev"
my:
  list:
  - name: "my another name"

在前面的示例中,如果devprofile 处于活动状态,MyProperties.list包含一个 MyPojo条目(名称为my another name以及null). 对于 YAML,逗号分隔列表和 YAML 列表都可用于完全覆盖列表的内容。spring-doc.cadn.net.cn

Mapproperties 中,您可以与从多个来源提取的属性值绑定。 但是,对于多个来源中的同一属性,将使用优先级最高的属性。 以下示例公开了Map<String, MyPojo>MyProperties:spring-doc.cadn.net.cn

Java
import java.util.LinkedHashMap;
import java.util.Map;

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

@ConfigurationProperties("my")
public class MyProperties {

    private final Map<String, MyPojo> map = new LinkedHashMap<>();

    public Map<String, MyPojo> getMap() {
        return this.map;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties

@ConfigurationProperties("my")
class MyProperties {

    val map: Map<String, MyPojo> = LinkedHashMap()

}

请考虑以下配置:spring-doc.cadn.net.cn

性能
my.map.key1.name=my name 1
my.map.key1.description=my description 1
#---
spring.config.activate.on-profile=dev
my.map.key1.name=dev name 1
my.map.key2.name=dev name 2
my.map.key2.description=dev description 2
Yaml
my:
  map:
    key1:
      name: "my name 1"
      description: "my description 1"
---
spring:
  config:
    activate:
      on-profile: "dev"
my:
  map:
    key1:
      name: "dev name 1"
    key2:
      name: "dev name 2"
      description: "dev description 2"

如果devprofile 未激活,MyProperties.map包含一个带键的条目key1(名称为my name 1以及my description 1). 如果devprofile 已启用,但是,map包含两个带键的条目key1(名称为dev name 1以及my description 1) 和key2(名称为dev name 2以及dev description 2).spring-doc.cadn.net.cn

上述合并规则适用于所有属性源中的属性,而不仅仅是文件。

2.8.8. 属性转换

Spring Boot 在绑定到@ConfigurationProperties豆。 如果需要自定义类型转换,可以提供ConversionServicebean(带有一个名为conversionService) 或自定义属性编辑器(通过CustomEditorConfigurerBean) 或自定义Converters(bean 定义注释为@ConfigurationPropertiesBinding).spring-doc.cadn.net.cn

由于此 bean 是在应用程序生命周期的早期请求,因此请确保限制ConversionService正在使用。 通常,您需要的任何依赖项在创建时可能未完全初始化。 您可能希望重命名您的自定义ConversionService如果不需要配置键 强制,并且只依赖限定为@ConfigurationPropertiesBinding.
转换持续时间

Spring Boot 专门支持表示持续时间。 如果您公开了java.time.Duration属性,则应用程序属性中的以下格式可用:spring-doc.cadn.net.cn

请考虑以下示例:spring-doc.cadn.net.cn

Java
import java.time.Duration;
import java.time.temporal.ChronoUnit;

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

@ConfigurationProperties("my")
public class MyProperties {

    @DurationUnit(ChronoUnit.SECONDS)
    private Duration sessionTimeout = Duration.ofSeconds(30);

    private Duration readTimeout = Duration.ofMillis(1000);

    // getters / setters...

    public Duration getSessionTimeout() {
        return this.sessionTimeout;
    }

    public void setSessionTimeout(Duration sessionTimeout) {
        this.sessionTimeout = sessionTimeout;
    }

    public Duration getReadTimeout() {
        return this.readTimeout;
    }

    public void setReadTimeout(Duration readTimeout) {
        this.readTimeout = readTimeout;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.convert.DurationUnit
import java.time.Duration
import java.time.temporal.ChronoUnit

@ConfigurationProperties("my")
class MyProperties {

    @DurationUnit(ChronoUnit.SECONDS)
    var sessionTimeout = Duration.ofSeconds(30)

    var readTimeout = Duration.ofMillis(1000)

}

要指定 30 秒的会话超时,30,PT30S30s都是等效的。 可以采用以下任何形式指定 500 毫秒的读取超时:500,PT0.5S500ms.spring-doc.cadn.net.cn

您还可以使用任何受支持的单位。 这些是:spring-doc.cadn.net.cn

默认单位为毫秒,可以使用@DurationUnit如上面的示例所示。spring-doc.cadn.net.cn

如果您更喜欢使用构造函数绑定,则可以公开相同的属性,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.time.Duration;
import java.time.temporal.ChronoUnit;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.boot.convert.DurationUnit;

@ConfigurationProperties("my")
public class MyProperties {

    // fields...

    private final Duration sessionTimeout;

    private final Duration readTimeout;

    public MyProperties(@DurationUnit(ChronoUnit.SECONDS) @DefaultValue("30s") Duration sessionTimeout,
            @DefaultValue("1000ms") Duration readTimeout) {
        this.sessionTimeout = sessionTimeout;
        this.readTimeout = readTimeout;
    }

    // getters...

    public Duration getSessionTimeout() {
        return this.sessionTimeout;
    }

    public Duration getReadTimeout() {
        return this.readTimeout;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.bind.DefaultValue
import org.springframework.boot.convert.DurationUnit
import java.time.Duration
import java.time.temporal.ChronoUnit

@ConfigurationProperties("my")
class MyProperties(@param:DurationUnit(ChronoUnit.SECONDS) @param:DefaultValue("30s") val sessionTimeout: Duration,
        @param:DefaultValue("1000ms") val readTimeout: Duration)
如果要升级Long属性,请确保定义单位(使用@DurationUnit) 如果不是毫秒。 这样做提供了透明的升级路径,同时支持更丰富的格式。
转换期间

除了持续时间之外, Spring Boot 还可以使用java.time.Period类型。 应用程序属性中可以使用以下格式:spring-doc.cadn.net.cn

简单格式支持以下单位:spring-doc.cadn.net.cn

java.time.Periodtype 实际上从未存储过周数,它是一个表示“7 天”的快捷方式。
转换数据大小

Spring Framework 有一个DataSizevalue 类型,以字节为单位表示大小。 如果您公开了DataSize属性,则应用程序属性中的以下格式可用:spring-doc.cadn.net.cn

请考虑以下示例:spring-doc.cadn.net.cn

Java
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.convert.DataSizeUnit;
import org.springframework.util.unit.DataSize;
import org.springframework.util.unit.DataUnit;

@ConfigurationProperties("my")
public class MyProperties {

    @DataSizeUnit(DataUnit.MEGABYTES)
    private DataSize bufferSize = DataSize.ofMegabytes(2);

    private DataSize sizeThreshold = DataSize.ofBytes(512);

    // getters/setters...

    public DataSize getBufferSize() {
        return this.bufferSize;
    }

    public void setBufferSize(DataSize bufferSize) {
        this.bufferSize = bufferSize;
    }

    public DataSize getSizeThreshold() {
        return this.sizeThreshold;
    }

    public void setSizeThreshold(DataSize sizeThreshold) {
        this.sizeThreshold = sizeThreshold;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.convert.DataSizeUnit
import org.springframework.util.unit.DataSize
import org.springframework.util.unit.DataUnit

@ConfigurationProperties("my")
class MyProperties {

    @DataSizeUnit(DataUnit.MEGABYTES)
    var bufferSize = DataSize.ofMegabytes(2)

    var sizeThreshold = DataSize.ofBytes(512)

}

要指定 10 MB 的缓冲区大小,1010MB是等效的。 256 字节的大小阈值可以指定为256256B.spring-doc.cadn.net.cn

您还可以使用任何受支持的单位。 这些是:spring-doc.cadn.net.cn

默认单位为 bytes,可以使用@DataSizeUnit如上面的示例所示。spring-doc.cadn.net.cn

如果您更喜欢使用构造函数绑定,则可以公开相同的属性,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.boot.convert.DataSizeUnit;
import org.springframework.util.unit.DataSize;
import org.springframework.util.unit.DataUnit;

@ConfigurationProperties("my")
public class MyProperties {

    // fields...

    private final DataSize bufferSize;

    private final DataSize sizeThreshold;

    public MyProperties(@DataSizeUnit(DataUnit.MEGABYTES) @DefaultValue("2MB") DataSize bufferSize,
            @DefaultValue("512B") DataSize sizeThreshold) {
        this.bufferSize = bufferSize;
        this.sizeThreshold = sizeThreshold;
    }

    // getters...

    public DataSize getBufferSize() {
        return this.bufferSize;
    }

    public DataSize getSizeThreshold() {
        return this.sizeThreshold;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.bind.DefaultValue
import org.springframework.boot.convert.DataSizeUnit
import org.springframework.util.unit.DataSize
import org.springframework.util.unit.DataUnit

@ConfigurationProperties("my")
class MyProperties(@param:DataSizeUnit(DataUnit.MEGABYTES) @param:DefaultValue("2MB") val bufferSize: DataSize,
        @param:DefaultValue("512B") val sizeThreshold: DataSize)
如果要升级Long属性,请确保定义单位(使用@DataSizeUnit) 如果不是 bytes。 这样做提供了透明的升级路径,同时支持更丰富的格式。

2.8.9. @ConfigurationProperties 验证

Spring Boot 尝试验证@ConfigurationProperties类,只要它们用 Spring 的@Validated注解。 您可以使用 JSR-303jakarta.validationconstraint 注解。 为此,请确保 Classpath 上具有兼容的 JSR-303 实现,然后将约束 Comments 添加到字段中,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.net.InetAddress;

import jakarta.validation.constraints.NotNull;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@ConfigurationProperties("my.service")
@Validated
public class MyProperties {

    @NotNull
    private InetAddress remoteAddress;

    // getters/setters...

    public InetAddress getRemoteAddress() {
        return this.remoteAddress;
    }

    public void setRemoteAddress(InetAddress remoteAddress) {
        this.remoteAddress = remoteAddress;
    }

}
Kotlin
import jakarta.validation.constraints.NotNull
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.validation.annotation.Validated
import java.net.InetAddress

@ConfigurationProperties("my.service")
@Validated
class MyProperties {

    var remoteAddress: @NotNull InetAddress? = null

}
您还可以通过注释@Bean方法,该方法使用@Validated.

要确保始终为嵌套属性触发验证,即使未找到任何属性,也必须对关联的字段进行批注@Valid. 以下示例基于前面的MyProperties例:spring-doc.cadn.net.cn

Java
import java.net.InetAddress;

import jakarta.validation.Valid;
import jakarta.validation.constraints.NotEmpty;
import jakarta.validation.constraints.NotNull;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

@ConfigurationProperties("my.service")
@Validated
public class MyProperties {

    @NotNull
    private InetAddress remoteAddress;

    @Valid
    private final Security security = new Security();

    // getters/setters...

    public InetAddress getRemoteAddress() {
        return this.remoteAddress;
    }

    public void setRemoteAddress(InetAddress remoteAddress) {
        this.remoteAddress = remoteAddress;
    }

    public Security getSecurity() {
        return this.security;
    }

    public static class Security {

        @NotEmpty
        private String username;

        // getters/setters...

        public String getUsername() {
            return this.username;
        }

        public void setUsername(String username) {
            this.username = username;
        }

    }

}
Kotlin
import jakarta.validation.Valid
import jakarta.validation.constraints.NotEmpty
import jakarta.validation.constraints.NotNull
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.validation.annotation.Validated
import java.net.InetAddress

@ConfigurationProperties("my.service")
@Validated
class MyProperties {

    var remoteAddress: @NotNull InetAddress? = null

    @Valid
    val security = Security()

    class Security {

        @NotEmpty
        var username: String? = null

    }

}

您还可以添加自定义 SpringValidator通过创建一个名为configurationPropertiesValidator. 这@Beanmethod 应该声明static. 配置属性验证器是在应用程序生命周期的早期创建的,并声明@Bean方法作为 static,则无需实例化@Configuration类。 这样做可以避免早期实例化可能导致的任何问题。spring-doc.cadn.net.cn

spring-boot-actuatormodule 包含一个端点,该端点公开所有@ConfigurationProperties豆。 将 Web 浏览器指向/actuator/configprops或使用等效的 JMX 终端节点。 有关详细信息,请参阅“生产就绪功能”部分。

2.8.10. @ConfigurationProperties 与 @Value

@ValueAnnotation 是容器的核心功能,它不提供与类型安全配置属性相同的功能。 下表总结了 支持 的功能@ConfigurationProperties@Value:spring-doc.cadn.net.cn

特征 @ConfigurationProperties @Value

松散的装订spring-doc.cadn.net.cn

是的spring-doc.cadn.net.cn

受限(请参阅下面的注释)spring-doc.cadn.net.cn

元数据支持spring-doc.cadn.net.cn

是的spring-doc.cadn.net.cn

spring-doc.cadn.net.cn

SpEL评估spring-doc.cadn.net.cn

spring-doc.cadn.net.cn

是的spring-doc.cadn.net.cn

如果您确实想使用@Value,我们建议您使用属性名称的规范形式(kebab 大小写仅使用小写字母)来引用属性名称。 这将允许 Spring Boot 使用与松散绑定时相同的逻辑 @ConfigurationProperties.spring-doc.cadn.net.cn

例如@Value("${demo.item-price}")会接球demo.item-pricedemo.itemPrice表单中application.properties文件以及DEMO_ITEMPRICE从系统环境。 如果您使用了@Value("${demo.itemPrice}")相反demo.item-priceDEMO_ITEMPRICE不会被考虑。spring-doc.cadn.net.cn

如果您为自己的组件定义了一组配置键,我们建议您将它们分组到一个 POJO 中,并带有@ConfigurationProperties. 这样做将为您提供结构化的、类型安全的对象,您可以将其注入到自己的 bean 中。spring-doc.cadn.net.cn

SpEL在解析 Application 属性文件和填充环境时,不会处理这些文件中的表达式。 但是,可以编写SpEL表达式@Value. 如果应用程序属性文件中的属性值是SpELexpression 时,它将在 通过@Value.spring-doc.cadn.net.cn

3. 配置文件

Spring 配置文件提供了一种分离应用程序配置的各个部分并使其仅在某些环境中可用的方法。 任何@Component,@Configuration@ConfigurationProperties可以标有@Profile限制加载时间,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration(proxyBeanMethods = false)
@Profile("production")
public class ProductionConfiguration {

    // ...

}
Kotlin
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.Profile

@Configuration(proxyBeanMethods = false)
@Profile("production")
class ProductionConfiguration {

    // ...

}
如果@ConfigurationPropertiesbean 通过@EnableConfigurationProperties不是自动扫描,而是@Profileannotation 需要在@Configuration类中具有@EnableConfigurationProperties注解。 在以下情况下@ConfigurationProperties被扫描,@Profile可以在@ConfigurationProperties类本身。

您可以使用spring.profiles.active Environment属性以指定哪些配置文件处于活动状态。 您可以使用本章前面介绍的任何方式指定属性。 例如,您可以将其包含在application.properties,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.profiles.active=dev,hsqldb
Yaml
spring:
  profiles:
    active: "dev,hsqldb"

您还可以使用以下开关在命令行上指定它:--spring.profiles.active=dev,hsqldb.spring-doc.cadn.net.cn

如果没有配置文件处于活动状态,则启用默认配置文件。 默认配置文件的名称为default并且可以使用spring.profiles.default Environment属性,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.profiles.default=none
Yaml
spring:
  profiles:
    default: "none"

spring.profiles.activespring.profiles.default只能在非配置文件特定文档中使用。 这意味着它们不能包含在 spring.config.activate.on-profile.spring-doc.cadn.net.cn

例如,第二个文档配置无效:spring-doc.cadn.net.cn

性能
# this document is valid
spring.profiles.active=prod
#---
# this document is invalid
spring.config.activate.on-profile=prod
spring.profiles.active=metrics
Yaml
# this document is valid
spring:
  profiles:
    active: "prod"
---
# this document is invalid
spring:
  config:
    activate:
      on-profile: "prod"
  profiles:
    active: "metrics"

3.1. 添加活动配置文件

spring.profiles.activeproperty 遵循与其他 property 相同的排序规则:highestPropertySource赢了。 这意味着您可以在application.properties,然后使用命令行开关替换它们。spring-doc.cadn.net.cn

有时,将属性添加到活动配置文件中而不是替换它们非常有用。 这spring.profiles.include属性可用于在由spring.profiles.active财产。 这SpringApplicationentry point 还具有用于设置其他配置文件的 Java API。 请参阅setAdditionalProfiles()方法spring-doc.cadn.net.cn

例如,当运行具有以下属性的应用程序时,即使它使用--spring.profiles.active开关:spring-doc.cadn.net.cn

性能
spring.profiles.include[0]=common
spring.profiles.include[1]=local
Yaml
spring:
  profiles:
    include:
      - "common"
      - "local"
spring.profiles.active,spring.profiles.include只能在非配置文件特定文档中使用。 这意味着它不能包含在用户档案特定的文件spring.config.activate.on-profile.

如果给定配置文件处于活动状态,则下一节中介绍的配置文件组也可用于添加活动配置文件。spring-doc.cadn.net.cn

3.2. 配置文件组

有时,您在应用程序中定义和使用的配置文件过于精细,使用起来变得很麻烦。 例如,您可能有proddbprodmq用于单独启用数据库和消息传递功能的配置文件。spring-doc.cadn.net.cn

为了帮助解决这个问题, Spring Boot 允许你定义配置文件组。 配置文件组允许您为相关的配置文件组定义逻辑名称。spring-doc.cadn.net.cn

例如,我们可以创建一个productiongroup 的proddbprodmq配置 文件。spring-doc.cadn.net.cn

性能
spring.profiles.group.production[0]=proddb
spring.profiles.group.production[1]=prodmq
Yaml
spring:
  profiles:
    group:
      production:
      - "proddb"
      - "prodmq"

我们的应用程序现在可以开始使用--spring.profiles.active=production要激活production,proddbprodmq个人资料。spring-doc.cadn.net.cn

3.3. 以编程方式设置 Profile

您可以通过调用SpringApplication.setAdditionalProfiles(…​)在应用程序运行之前。 也可以使用 Spring 的ConfigurableEnvironment接口。spring-doc.cadn.net.cn

3.4. 特定于 Profile 的配置文件

两者的特定于配置文件的变体application.properties(或application.yaml) 和通过@ConfigurationProperties被视为文件并已加载。 有关详细信息,请参阅“分析特定文件”。spring-doc.cadn.net.cn

4. 日志记录

Spring Boot 使用 Commons Logging 进行所有内部日志记录,但将底层日志实现保持开放状态。 为 Java Util LoggingLog4j2Logback 提供了默认配置。 在每种情况下,记录器都预先配置为使用控制台输出,并提供可选的文件输出。spring-doc.cadn.net.cn

默认情况下,如果使用“Starters”,则使用 Logback 进行日志记录。 还包括适当的 Logback 路由,以确保使用 Java Util Logging、Commons Logging、Log4J 或 SLF4J 的依赖库都能正常工作。spring-doc.cadn.net.cn

有很多可用于 Java 的日志记录框架。 如果上面的列表看起来令人困惑,请不要担心。 通常,您不需要更改日志记录依赖项,并且 Spring Boot 默认值可以正常工作。
将应用程序部署到 servlet 容器或应用程序服务器时,使用 Java Util Logging API 执行的日志记录不会路由到应用程序的日志中。 这可以防止容器或已部署到容器的其他应用程序执行的日志记录显示在应用程序的日志中。

4.1. 日志格式

Spring Boot 的默认日志输出类似于以下示例:spring-doc.cadn.net.cn

2024-05-23T07:27:53.211Z  INFO 109693 --- [           main] o.s.b.d.f.logexample.MyApplication       : Starting MyApplication using Java 17.0.11 with PID 109693 (/opt/apps/myapp.jar started by myuser in /opt/apps/)
2024-05-23T07:27:53.215Z  INFO 109693 --- [           main] o.s.b.d.f.logexample.MyApplication       : No active profile set, falling back to 1 default profile: "default"
2024-05-23T07:27:55.862Z  INFO 109693 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2024-05-23T07:27:55.901Z  INFO 109693 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-05-23T07:27:55.901Z  INFO 109693 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.24]
2024-05-23T07:27:56.124Z  INFO 109693 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2024-05-23T07:27:56.129Z  INFO 109693 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 2702 ms
2024-05-23T07:27:56.976Z  INFO 109693 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2024-05-23T07:27:56.996Z  INFO 109693 --- [           main] o.s.b.d.f.logexample.MyApplication       : Started MyApplication in 5.062 seconds (process running for 6.255)

输出以下项目:spring-doc.cadn.net.cn

Logback 没有FATAL水平。 它被映射到ERROR.

4.2. 控制台输出

默认日志配置在写入消息时将消息回显到控制台。 默认情况下,ERROR-水平WARN-level 和INFO-级别的消息。 您还可以通过使用--debug旗。spring-doc.cadn.net.cn

$ java -jar myapp.jar --debug
您还可以指定debug=trueapplication.properties.

启用调试模式后,将配置一系列核心 Logger(嵌入式容器、Hibernate 和 Spring Boot)以输出更多信息。 启用调试模式不会将应用程序配置为使用DEBUG水平。spring-doc.cadn.net.cn

或者,您可以通过使用--traceflag(或trace=trueapplication.properties). 这样做可以为选定的核心 Logger(嵌入式容器、Hibernate 模式生成和整个 Spring 产品组合)启用跟踪日志记录。spring-doc.cadn.net.cn

4.2.1. 颜色编码输出

如果您的终端支持 ANSI,则使用颜色输出来提高可读性。 您可以设置spring.output.ansi.enabled设置为支持的值以覆盖自动检测。spring-doc.cadn.net.cn

颜色编码是使用%clr转换词。 在最简单的形式中,转换器根据对数级别对输出进行着色,如以下示例所示:spring-doc.cadn.net.cn

%clr(%5p)

下表描述了对数级别到颜色的映射:spring-doc.cadn.net.cn

水平 颜色

FATALspring-doc.cadn.net.cn

spring-doc.cadn.net.cn

ERRORspring-doc.cadn.net.cn

spring-doc.cadn.net.cn

WARNspring-doc.cadn.net.cn

黄色spring-doc.cadn.net.cn

INFOspring-doc.cadn.net.cn

绿spring-doc.cadn.net.cn

DEBUGspring-doc.cadn.net.cn

绿spring-doc.cadn.net.cn

TRACEspring-doc.cadn.net.cn

绿spring-doc.cadn.net.cn

或者,您可以通过将颜色或样式作为转换选项来指定应使用的颜色或样式。 例如,要使文本变为黄色,请使用以下设置:spring-doc.cadn.net.cn

%clr(%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX}){yellow}

支持以下颜色和样式:spring-doc.cadn.net.cn

4.3. 文件输出

默认情况下, Spring Boot 仅记录到控制台,不写入日志文件。 如果除了控制台输出之外还想写入日志文件,则需要设置logging.file.namelogging.file.path属性(例如,在application.properties).spring-doc.cadn.net.cn

下表显示了logging.*properties 可以一起使用:spring-doc.cadn.net.cn

表 5.日志记录属性
logging.file.name logging.file.path 描述

(无)spring-doc.cadn.net.cn

(无)spring-doc.cadn.net.cn

仅限控制台日志记录。spring-doc.cadn.net.cn

特定文件spring-doc.cadn.net.cn

(无)spring-doc.cadn.net.cn

my.logspring-doc.cadn.net.cn

写入指定的日志文件。 名称可以是确切的位置,也可以是相对于当前目录的 名称。spring-doc.cadn.net.cn

(无)spring-doc.cadn.net.cn

特定目录spring-doc.cadn.net.cn

/var/logspring-doc.cadn.net.cn

spring.log添加到指定的目录。 名称可以是确切的位置,也可以是相对于当前目录的 名称。spring-doc.cadn.net.cn

日志文件在达到 10 MB 时轮换,并且与控制台输出一样,ERROR-水平WARN-level 和INFO-level 消息。spring-doc.cadn.net.cn

日志记录属性独立于实际的日志记录基础结构。 因此,特定的配置键(例如logback.configurationFilefor Logback)不受 Spring Boot 管理。

4.4. 文件旋转

如果您使用的是 Logback,则可以使用application.propertiesapplication.yaml文件。 对于所有其他日志记录系统,您需要直接自己配置轮换设置(例如,如果您使用 Log4j2,则可以添加log4j2.xmllog4j2-spring.xml文件)。spring-doc.cadn.net.cn

支持以下轮换策略属性:spring-doc.cadn.net.cn

名字 描述

logging.logback.rollingpolicy.file-name-patternspring-doc.cadn.net.cn

用于创建日志存档的文件名模式。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.clean-history-on-startspring-doc.cadn.net.cn

是否应在应用程序启动时进行日志存档清理。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.max-file-sizespring-doc.cadn.net.cn

日志文件存档前的最大大小。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.total-size-capspring-doc.cadn.net.cn

日志存档在被删除之前可以占用的最大大小。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.max-historyspring-doc.cadn.net.cn

要保留的存档日志文件的最大数量(默认为 7)。spring-doc.cadn.net.cn

4.5. 日志级别

所有受支持的日志记录系统都可以在 Spring 中设置 Logger 级别Environment(例如,在application.properties) 使用logging.level.<logger-name>=<level>哪里level是 TRACE、DEBUG、INFO、WARN、ERROR、FATAL 或 OFF 之一。 这root可以使用logging.level.root.spring-doc.cadn.net.cn

以下示例显示了application.properties:spring-doc.cadn.net.cn

性能
logging.level.root=warn
logging.level.org.springframework.web=debug
logging.level.org.hibernate=error
Yaml
logging:
  level:
    root: "warn"
    org.springframework.web: "debug"
    org.hibernate: "error"

还可以使用环境变量设置日志记录级别。 例如LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_WEB=DEBUG将设置org.springframework.webDEBUG.spring-doc.cadn.net.cn

上述方法仅适用于包级日志记录。 由于松散绑定始终将环境变量转换为小写,因此无法以这种方式为单个类配置日志记录。 如果需要为类配置日志记录,可以使用SPRING_APPLICATION_JSON变量。

4.6. 日志组

能够将相关的 logger 分组在一起,以便可以同时配置它们通常很有用。 例如,您可能通常会更改所有与 Tomcat 相关的 Logger 的日志记录级别,但您无法轻松记住顶级包。spring-doc.cadn.net.cn

为了帮助解决这个问题,Spring Boot 允许您在 Spring 中定义日志记录组Environment. 例如,以下是如何通过将 “tomcat” 组添加到application.properties:spring-doc.cadn.net.cn

性能
logging.group.tomcat=org.apache.catalina,org.apache.coyote,org.apache.tomcat
Yaml
logging:
  group:
    tomcat: "org.apache.catalina,org.apache.coyote,org.apache.tomcat"

定义后,您可以使用一行更改组中所有 logger 的级别:spring-doc.cadn.net.cn

性能
logging.level.tomcat=trace
Yaml
logging:
  level:
    tomcat: "trace"

Spring Boot 包括以下预定义的日志记录组,这些组可以开箱即用:spring-doc.cadn.net.cn

名字 Logging

Webspring-doc.cadn.net.cn

org.springframework.core.codec,org.springframework.http,org.springframework.web,org.springframework.boot.actuate.endpoint.web,org.springframework.boot.web.servlet.ServletContextInitializerBeansspring-doc.cadn.net.cn

SQLspring-doc.cadn.net.cn

org.springframework.jdbc.core,org.hibernate.SQL,org.jooq.tools.LoggerListenerspring-doc.cadn.net.cn

4.7. 使用日志关闭钩子

为了在应用程序终止时释放日志记录资源,提供了一个关闭钩子,该钩子将在 JVM 退出时触发日志系统清理。 除非您的应用程序部署为 war 文件,否则会自动注册此关闭钩子。 如果您的应用程序具有复杂的上下文层次结构,则 shutdown 钩子可能无法满足您的需求。 如果没有,请禁用 shutdown 钩子并调查底层日志记录系统直接提供的选项。 例如,Logback 提供了上下文选择器,允许在自己的上下文中创建每个 Logger。 您可以使用logging.register-shutdown-hook属性来禁用 shutdown 钩子。 将其设置为false将禁用注册。 您可以在application.propertiesapplication.yaml文件:spring-doc.cadn.net.cn

性能
logging.register-shutdown-hook=false
Yaml
logging:
  register-shutdown-hook: false

4.8. 自定义日志配置

可以通过在 Classpath 中包含适当的库来激活各种日志记录系统,并且可以通过在 Classpath 的根目录中或以下 Spring 指定的位置提供合适的配置文件来进一步定制Environment财产:logging.config.spring-doc.cadn.net.cn

您可以通过使用org.springframework.boot.logging.LoggingSystemsystem 属性。 该值应为LoggingSystem实现。 你还可以通过使用none.spring-doc.cadn.net.cn

由于日志记录是在ApplicationContext时,无法从@PropertySources春季@Configuration文件。 更改日志记录系统或完全禁用它的唯一方法是通过 System properties。

根据您的日志记录系统,将加载以下文件:spring-doc.cadn.net.cn

测井系统 定制

Logback (日志返回)spring-doc.cadn.net.cn

logback-spring.xml,logback-spring.groovy,logback.xmllogback.groovyspring-doc.cadn.net.cn

日志 4j2spring-doc.cadn.net.cn

log4j2-spring.xmllog4j2.xmlspring-doc.cadn.net.cn

JDK(Java Util 日志记录)spring-doc.cadn.net.cn

logging.propertiesspring-doc.cadn.net.cn

如果可能,我们建议您使用-spring变体(例如logback-spring.xml而不是logback.xml). 如果使用标准配置位置, Spring 则无法完全控制日志初始化。
Java Util Logging 存在已知的类加载问题,这些问题会导致在从“可执行 jar”运行时出现问题。 我们建议您尽可能避免从“可执行 jar”运行时使用它。

为了帮助进行自定义,从 Spring 传输了一些其他属性Environment更改为 System properties。 这允许记录系统配置来使用属性。例如,将logging.file.nameapplication.propertiesLOGGING_FILE_NAME作为环境变量将导致LOG_FILESystem 属性。 下表描述了传输的属性:spring-doc.cadn.net.cn

Spring 环境 系统属性 评论

logging.exception-conversion-wordspring-doc.cadn.net.cn

LOG_EXCEPTION_CONVERSION_WORDspring-doc.cadn.net.cn

记录异常时使用的转换字。spring-doc.cadn.net.cn

logging.file.namespring-doc.cadn.net.cn

LOG_FILEspring-doc.cadn.net.cn

如果已定义,则在默认日志配置中使用它。spring-doc.cadn.net.cn

logging.file.pathspring-doc.cadn.net.cn

LOG_PATHspring-doc.cadn.net.cn

如果已定义,则在默认日志配置中使用它。spring-doc.cadn.net.cn

logging.pattern.consolespring-doc.cadn.net.cn

CONSOLE_LOG_PATTERNspring-doc.cadn.net.cn

要在控制台上使用的日志模式 (stdout)。spring-doc.cadn.net.cn

logging.pattern.dateformatspring-doc.cadn.net.cn

LOG_DATEFORMAT_PATTERNspring-doc.cadn.net.cn

日志日期格式的 Appender 模式。spring-doc.cadn.net.cn

logging.charset.consolespring-doc.cadn.net.cn

CONSOLE_LOG_CHARSETspring-doc.cadn.net.cn

用于控制台日志记录的字符集。spring-doc.cadn.net.cn

logging.threshold.consolespring-doc.cadn.net.cn

CONSOLE_LOG_THRESHOLDspring-doc.cadn.net.cn

用于控制台日志记录的日志级别阈值。spring-doc.cadn.net.cn

logging.pattern.filespring-doc.cadn.net.cn

FILE_LOG_PATTERNspring-doc.cadn.net.cn

要在文件中使用的日志模式(如果LOG_FILE已启用)。spring-doc.cadn.net.cn

logging.charset.filespring-doc.cadn.net.cn

FILE_LOG_CHARSETspring-doc.cadn.net.cn

用于文件日志记录的字符集(如果LOG_FILE已启用)。spring-doc.cadn.net.cn

logging.threshold.filespring-doc.cadn.net.cn

FILE_LOG_THRESHOLDspring-doc.cadn.net.cn

用于文件日志记录的日志级别阈值。spring-doc.cadn.net.cn

logging.pattern.levelspring-doc.cadn.net.cn

LOG_LEVEL_PATTERNspring-doc.cadn.net.cn

渲染日志级别(默认%5p).spring-doc.cadn.net.cn

PIDspring-doc.cadn.net.cn

PIDspring-doc.cadn.net.cn

当前进程 ID(如果可能且尚未定义为 OS 环境变量,则已发现)。spring-doc.cadn.net.cn

如果使用 Logback,则还会传输以下属性:spring-doc.cadn.net.cn

Spring 环境 系统属性 评论

logging.logback.rollingpolicy.file-name-patternspring-doc.cadn.net.cn

LOGBACK_ROLLINGPOLICY_FILE_NAME_PATTERNspring-doc.cadn.net.cn

滚动日志文件名的模式(默认${LOG_FILE}.%d{yyyy-MM-dd}.%i.gz).spring-doc.cadn.net.cn

logging.logback.rollingpolicy.clean-history-on-startspring-doc.cadn.net.cn

LOGBACK_ROLLINGPOLICY_CLEAN_HISTORY_ON_STARTspring-doc.cadn.net.cn

是否在启动时清理存档日志文件。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.max-file-sizespring-doc.cadn.net.cn

LOGBACK_ROLLINGPOLICY_MAX_FILE_SIZEspring-doc.cadn.net.cn

最大日志文件大小。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.total-size-capspring-doc.cadn.net.cn

LOGBACK_ROLLINGPOLICY_TOTAL_SIZE_CAPspring-doc.cadn.net.cn

要保留的日志备份的总大小。spring-doc.cadn.net.cn

logging.logback.rollingpolicy.max-historyspring-doc.cadn.net.cn

LOGBACK_ROLLINGPOLICY_MAX_HISTORYspring-doc.cadn.net.cn

要保留的存档日志文件的最大数量。spring-doc.cadn.net.cn

所有受支持的日志记录系统都可以在解析其配置文件时查阅 System properties。 请参阅spring-boot.jar例如:spring-doc.cadn.net.cn

如果要在日志记录属性中使用占位符,则应使用 Spring Boot 的语法,而不是底层框架的语法。 值得注意的是,如果您使用 Logback,则应使用:作为属性名称与其默认值之间的分隔符,而不使用:-.spring-doc.cadn.net.cn

您可以通过仅覆盖LOG_LEVEL_PATTERN(或logging.pattern.level与 Logback 一起使用)。 例如,如果您使用logging.pattern.level=user:%X{user} %5p,则默认日志格式包含 “user” 的 MDC 条目(如果存在),如以下示例所示。spring-doc.cadn.net.cn

2019-08-30 12:30:04.031 user:someone INFO 22174 --- [  nio-8080-exec-0] demo.Controller
Handling authenticated request

4.9. Logback 扩展

Spring Boot 包含许多 Logback 扩展,可以帮助进行高级配置。 您可以在logback-spring.xml配置文件。spring-doc.cadn.net.cn

因为标准logback.xml配置文件加载得太早,你不能在其中使用扩展名。 您需要使用logback-spring.xml或定义一个logging.config财产。
这些扩展不能与 Logback 的配置扫描一起使用。 如果尝试这样做,则对配置文件进行更改会导致记录类似于以下内容之一的错误:
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProperty], current ElementPath is [[configuration][springProperty]]
ERROR in ch.qos.logback.core.joran.spi.Interpreter@4:71 - no applicable action for [springProfile], current ElementPath is [[configuration][springProfile]]

4.9.1. 特定于 Profile 的配置

<springProfile>tag 允许您根据活动的 Spring 配置文件选择性地包含或排除配置部分。 Profile 部分在<configuration>元素。 使用name属性来指定哪个配置文件接受配置。 这<springProfile>标记可以包含配置文件名称(例如staging) 或配置文件表达式。 配置文件表达式允许表达更复杂的配置文件逻辑,例如production & (eu-central | eu-west). 有关更多详细信息,请查看 Spring Framework 参考指南。 以下清单显示了三个示例配置文件:spring-doc.cadn.net.cn

<springProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</springProfile>

<springProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</springProfile>

<springProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</springProfile>

4.9.2. 环境属性

<springProperty>标记允许您公开 Spring 中的属性Environment用于 Logback。 如果您想从application.properties文件。 该标签的工作方式与 Logback 的标准类似<property>标记。 但是,与其指定直接的value中,您可以指定source属性(从Environment). 如果您需要将属性存储在 以外的其他位置local范围内,您可以使用scope属性。 如果您需要一个回退值(如果未在Environment),您可以使用defaultValue属性。 以下示例显示了如何公开要在 Logback 中使用的属性:spring-doc.cadn.net.cn

<springProperty scope="context" name="fluentHost" source="myapp.fluentd.host"
        defaultValue="localhost"/>
<appender name="FLUENT" class="ch.qos.logback.more.appenders.DataFluentAppender">
    <remoteHost>${fluentHost}</remoteHost>
    ...
</appender>
source必须在 kebab 大小写中指定(例如my.property-name). 但是,可以将属性添加到Environment通过使用宽松的规则。

4.10. Log4j2 扩展

Spring Boot 包含许多对 Log4j2 的扩展,这些扩展可以帮助进行高级配置。 您可以在任何log4j2-spring.xml配置文件。spring-doc.cadn.net.cn

因为标准log4j2.xml配置文件加载得太早,你不能在其中使用扩展名。 您需要使用log4j2-spring.xml或定义一个logging.config财产。
这些扩展取代了 Log4J 提供的 Spring Boot 支持。 您应该确保不包含org.apache.logging.log4j:log4j-spring-boot模块中。

4.10.1. 特定于 Profile 的配置

<SpringProfile>tag 允许您根据活动的 Spring 配置文件选择性地包含或排除配置部分。 Profile 部分在<Configuration>元素。 使用name属性来指定哪个配置文件接受配置。 这<SpringProfile>标记可以包含配置文件名称(例如staging) 或配置文件表达式。 配置文件表达式允许表达更复杂的配置文件逻辑,例如production & (eu-central | eu-west). 有关更多详细信息,请查看 Spring Framework 参考指南。 以下清单显示了三个示例配置文件:spring-doc.cadn.net.cn

<SpringProfile name="staging">
    <!-- configuration to be enabled when the "staging" profile is active -->
</SpringProfile>

<SpringProfile name="dev | staging">
    <!-- configuration to be enabled when the "dev" or "staging" profiles are active -->
</SpringProfile>

<SpringProfile name="!production">
    <!-- configuration to be enabled when the "production" profile is not active -->
</SpringProfile>

4.10.2. 环境属性查找

如果要引用 Spring 中的属性Environment在 Log4j2 配置中,您可以使用spring:前缀查找。 如果您想从application.properties文件。spring-doc.cadn.net.cn

以下示例演示如何设置名为applicationName内容如下spring.application.name从Spring开始Environment:spring-doc.cadn.net.cn

<Properties>
    <Property name="applicationName">${spring:spring.application.name}</Property>
</Properties>
查找键应以 kebab 大小写指定(例如my.property-name).

4.10.3. Log4j2 系统属性

Log4j2 支持许多可用于配置各种项目的系统属性。 例如,log4j2.skipJansisystem 属性可用于配置ConsoleAppender将尝试在 Windows 上使用 Jansi 输出流。spring-doc.cadn.net.cn

Log4j2 初始化后加载的所有系统属性都可以从 Spring 获取Environment. 例如,您可以添加log4j2.skipJansi=false发送到您的application.properties文件,将ConsoleAppender在 Windows 上使用 Jansi。spring-doc.cadn.net.cn

SpringEnvironment仅当系统属性和 OS 环境变量不包含正在加载的值时,才考虑。
在早期 Log4j2 初始化期间加载的系统属性无法引用 SpringEnvironment. 例如,在 Spring Environment 可用之前,使用了 Log4j2 用于允许选择默认 Log4j2 实现的属性。

5. 国际化

Spring Boot 支持本地化消息,以便您的应用程序可以满足不同语言偏好的用户。 默认情况下, Spring Boot 会查找messagesresource bundle 位于 Classpath 的根目录中。spring-doc.cadn.net.cn

当已配置资源包的默认属性文件可用 (messages.properties默认情况下)。 如果您的资源包仅包含特定于语言的属性文件,则需要添加默认值。 如果未找到与任何已配置的基本名称匹配的属性文件,则不会自动配置MessageSource.

资源包的基本名称以及其他几个属性可以使用spring.messagesnamespace 中,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.messages.basename=messages,config.i18n.messages
spring.messages.fallback-to-system-locale=false
Yaml
spring:
  messages:
    basename: "messages,config.i18n.messages"
    fallback-to-system-locale: false
spring.messages.basename支持逗号分隔的位置列表,可以是 package 限定符或从 Classpath 根解析的资源。

MessageSourceProperties以获取更多支持的选项。spring-doc.cadn.net.cn

6. 面向方面的编程

Spring Boot 为面向方面的编程 (AOP) 提供自动配置。 您可以在 Spring Framework 参考文档中了解有关 AOP with Spring 的更多信息。spring-doc.cadn.net.cn

默认情况下,Spring Boot 的自动配置将 Spring AOP 配置为使用 CGLib 代理。 要改用 JDK 代理,请将configprop:spring.aop.proxy-target-classfalse.spring-doc.cadn.net.cn

如果 AspectJ 在 classpath 上,则 Spring Boot 的自动配置将自动启用 AspectJ 自动代理,以便@EnableAspectJAutoProxy不是必需的。spring-doc.cadn.net.cn

7. JSON

Spring Boot 提供与三个 JSON 映射库的集成:spring-doc.cadn.net.cn

Jackson 是首选和默认库。spring-doc.cadn.net.cn

7.1. Jackson

提供了 Jackson 的自动配置,Jackson 是其中的一部分spring-boot-starter-json. 当 Jackson 位于 Classpath 上时,一个ObjectMapperbean 会自动配置。 提供了几个配置属性自定义ObjectMapper.spring-doc.cadn.net.cn

7.1.1. 自定义序列化器和反序列化器

如果您使用 Jackson 序列化和反序列化 JSON 数据,则可能需要编写自己的 JSON 数据JsonSerializerJsonDeserializer类。 自定义序列化器通常通过模块向 Jackson 注册,但 Spring Boot 提供了另一种选择@JsonComponent注解,可以更轻松地直接注册 Spring Beans。spring-doc.cadn.net.cn

您可以使用@JsonComponent注解JsonSerializer,JsonDeserializerKeyDeserializer实现。 您还可以在包含序列化器/反序列化器作为内部类的类上使用它,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.io.IOException;

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.core.ObjectCodec;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonDeserializer;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.JsonSerializer;
import com.fasterxml.jackson.databind.SerializerProvider;

import org.springframework.boot.jackson.JsonComponent;

@JsonComponent
public class MyJsonComponent {

    public static class Serializer extends JsonSerializer<MyObject> {

        @Override
        public void serialize(MyObject value, JsonGenerator jgen, SerializerProvider serializers) throws IOException {
            jgen.writeStartObject();
            jgen.writeStringField("name", value.getName());
            jgen.writeNumberField("age", value.getAge());
            jgen.writeEndObject();
        }

    }

    public static class Deserializer extends JsonDeserializer<MyObject> {

        @Override
        public MyObject deserialize(JsonParser jsonParser, DeserializationContext ctxt) throws IOException {
            ObjectCodec codec = jsonParser.getCodec();
            JsonNode tree = codec.readTree(jsonParser);
            String name = tree.get("name").textValue();
            int age = tree.get("age").intValue();
            return new MyObject(name, age);
        }

    }

}
Kotlin
import com.fasterxml.jackson.core.JsonGenerator
import com.fasterxml.jackson.core.JsonParser
import com.fasterxml.jackson.core.JsonProcessingException
import com.fasterxml.jackson.databind.DeserializationContext
import com.fasterxml.jackson.databind.JsonDeserializer
import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.JsonSerializer
import com.fasterxml.jackson.databind.SerializerProvider
import org.springframework.boot.jackson.JsonComponent
import java.io.IOException

@JsonComponent
class MyJsonComponent {

    class Serializer : JsonSerializer<MyObject>() {
        @Throws(IOException::class)
        override fun serialize(value: MyObject, jgen: JsonGenerator, serializers: SerializerProvider) {
            jgen.writeStartObject()
            jgen.writeStringField("name", value.name)
            jgen.writeNumberField("age", value.age)
            jgen.writeEndObject()
        }
    }

    class Deserializer : JsonDeserializer<MyObject>() {
        @Throws(IOException::class, JsonProcessingException::class)
        override fun deserialize(jsonParser: JsonParser, ctxt: DeserializationContext): MyObject {
            val codec = jsonParser.codec
            val tree = codec.readTree<JsonNode>(jsonParser)
            val name = tree["name"].textValue()
            val age = tree["age"].intValue()
            return MyObject(name, age)
        }
    }

}

@JsonComponentbean 中的ApplicationContext将自动向 Jackson 注册。 因为@JsonComponent使用@Component,则通常的组件扫描规则适用。spring-doc.cadn.net.cn

Spring Boot 还提供JsonObjectSerializerJsonObjectDeserializer在序列化对象时为标准 Jackson 版本提供有用的替代方法的基类。 看JsonObjectSerializerJsonObjectDeserializer有关详细信息。spring-doc.cadn.net.cn

上面的示例可以重写以使用JsonObjectSerializer/JsonObjectDeserializer如下:spring-doc.cadn.net.cn

Java
import java.io.IOException;

import com.fasterxml.jackson.core.JsonGenerator;
import com.fasterxml.jackson.core.JsonParser;
import com.fasterxml.jackson.core.ObjectCodec;
import com.fasterxml.jackson.databind.DeserializationContext;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.SerializerProvider;

import org.springframework.boot.jackson.JsonComponent;
import org.springframework.boot.jackson.JsonObjectDeserializer;
import org.springframework.boot.jackson.JsonObjectSerializer;

@JsonComponent
public class MyJsonComponent {

    public static class Serializer extends JsonObjectSerializer<MyObject> {

        @Override
        protected void serializeObject(MyObject value, JsonGenerator jgen, SerializerProvider provider)
                throws IOException {
            jgen.writeStringField("name", value.getName());
            jgen.writeNumberField("age", value.getAge());
        }

    }

    public static class Deserializer extends JsonObjectDeserializer<MyObject> {

        @Override
        protected MyObject deserializeObject(JsonParser jsonParser, DeserializationContext context, ObjectCodec codec,
                JsonNode tree) throws IOException {
            String name = nullSafeValue(tree.get("name"), String.class);
            int age = nullSafeValue(tree.get("age"), Integer.class);
            return new MyObject(name, age);
        }

    }

}
Kotlin
`object`

import com.fasterxml.jackson.core.JsonGenerator
import com.fasterxml.jackson.core.JsonParser
import com.fasterxml.jackson.core.ObjectCodec
import com.fasterxml.jackson.databind.DeserializationContext
import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.SerializerProvider
import org.springframework.boot.jackson.JsonComponent
import org.springframework.boot.jackson.JsonObjectDeserializer
import org.springframework.boot.jackson.JsonObjectSerializer
import java.io.IOException

@JsonComponent
class MyJsonComponent {

    class Serializer : JsonObjectSerializer<MyObject>() {
        @Throws(IOException::class)
        override fun serializeObject(value: MyObject, jgen: JsonGenerator, provider: SerializerProvider) {
            jgen.writeStringField("name", value.name)
            jgen.writeNumberField("age", value.age)
        }
    }

    class Deserializer : JsonObjectDeserializer<MyObject>() {
        @Throws(IOException::class)
        override fun deserializeObject(jsonParser: JsonParser, context: DeserializationContext,
                codec: ObjectCodec, tree: JsonNode): MyObject {
            val name = nullSafeValue(tree["name"], String::class.java)
            val age = nullSafeValue(tree["age"], Int::class.java)
            return MyObject(name, age)
        }
    }

}

7.1.2. 混入

Jackson 支持 mixins,可用于将其他注释混合到目标类上已声明的注释中。 Spring Boot 的 Jackson 自动配置将扫描应用程序的包中带有 Comments 的类@JsonMixin并将其注册到自动配置的ObjectMapper. 注册由 Spring Boot 的JsonMixinModule.spring-doc.cadn.net.cn

7.2. Gson

提供了 Gson 的自动配置。 当 Gson 位于 Classpath 上时,会为 aGsonbean 会自动配置。 几个spring.gson.*提供了用于自定义配置的配置属性。 要获得更多控制权,请一个或多个GsonBuilderCustomizer可以使用 beans。spring-doc.cadn.net.cn

7.3. JSON-B

提供了 JSON-B 的自动配置。 当 JSON-B API 和实现位于类路径 a 上时Jsonbbean 将自动配置。 首选的 JSON-B 实现是 Eclipse Yasson,它为其提供了依赖项管理。spring-doc.cadn.net.cn

8. 任务执行和调度

在没有Executorbean 中,Spring Boot 会自动配置一个ThreadPoolTaskExecutor具有可自动与异步任务执行关联的合理默认值 (@EnableAsync) 和 Spring MVC 异步请求处理。spring-doc.cadn.net.cn

如果您定义了自定义Executor在上下文中,常规任务执行(即@EnableAsync)将透明地使用它,但不会配置 Spring MVC 支持,因为它需要AsyncTaskExecutorimplementation (名为applicationTaskExecutor). 根据您的目标排列方式,您可以更改Executor转换为ThreadPoolTaskExecutor或定义ThreadPoolTaskExecutor以及一个AsyncConfigurer包装您的自定义Executor.spring-doc.cadn.net.cn

自动配置的TaskExecutorBuilder允许您轻松创建实例,以重现自动配置默认执行的作。spring-doc.cadn.net.cn

线程池使用 8 个核心线程,这些线程可以根据负载进行扩展和收缩。 这些默认设置可以使用spring.task.executionnamespace 中,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.task.execution.pool.max-size=16
spring.task.execution.pool.queue-capacity=100
spring.task.execution.pool.keep-alive=10s
Yaml
spring:
  task:
    execution:
      pool:
        max-size: 16
        queue-capacity: 100
        keep-alive: "10s"

这会将线程池更改为使用有界队列,以便在队列已满(100 个任务)时,线程池增加到最多 16 个线程。 池的收缩更加激进,因为线程在空闲 10 秒(而不是默认 60 秒)时被回收。spring-doc.cadn.net.cn

一个ThreadPoolTaskScheduler如果需要与计划任务执行相关联,也可以自动配置(使用@EnableScheduling例如)。 默认情况下,线程池使用一个线程,其设置可以使用spring.task.schedulingnamespace 中,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.task.scheduling.thread-name-prefix=scheduling-
spring.task.scheduling.pool.size=2
Yaml
spring:
  task:
    scheduling:
      thread-name-prefix: "scheduling-"
      pool:
        size: 2

无论是TaskExecutorBuilderbean 和TaskSchedulerBuilderbean 在上下文中可用。spring-doc.cadn.net.cn

9. 测试

Spring Boot 提供了许多 Utilities 和 Comments,以帮助测试您的应用程序。 测试支持由两个模块提供:spring-boot-test包含核心物品,以及spring-boot-test-autoconfigure支持测试的自动配置。spring-doc.cadn.net.cn

大多数开发人员使用spring-boot-starter-test“Starter”,它导入 Spring Boot 测试模块以及 JUnit Jupiter、AssertJ、Hamcrest 和许多其他有用的库。spring-doc.cadn.net.cn

如果您有使用 JUnit 4 的测试,则可以使用 JUnit 5 的 vintage 引擎来运行它们。 要使用 vintage 引擎,请添加对junit-vintage-engine,如以下示例所示:spring-doc.cadn.net.cn

<dependency>
    <groupId>org.junit.vintage</groupId>
    <artifactId>junit-vintage-engine</artifactId>
    <scope>test</scope>
    <exclusions>
        <exclusion>
            <groupId>org.hamcrest</groupId>
            <artifactId>hamcrest-core</artifactId>
        </exclusion>
    </exclusions>
</dependency>

hamcrest-core被排除在外,以支持org.hamcrest:hamcrest那是spring-boot-starter-test.spring-doc.cadn.net.cn

9.1. 测试范围依赖项

spring-boot-starter-test“Starter”(在test scope) 包含以下提供的库:spring-doc.cadn.net.cn

我们通常会发现这些公共库在编写测试时很有用。 如果这些库不符合您的需求,您可以添加自己的其他测试依赖项。spring-doc.cadn.net.cn

9.2. 测试 Spring 应用程序

依赖项注入的主要优点之一是它应该使您的代码更易于进行单元测试。 您可以使用new运算符,甚至不涉及 Spring。 您还可以使用 mock 对象而不是真正的依赖项。spring-doc.cadn.net.cn

通常,您需要超越单元测试并开始集成测试(使用 SpringApplicationContext). 能够在不需要部署应用程序或不需要连接到其他基础设施的情况下执行集成测试非常有用。spring-doc.cadn.net.cn

Spring Framework 包括一个用于此类集成测试的专用测试模块。 您可以直接向org.springframework:spring-test或使用spring-boot-starter-test“Starter” 以传递方式将其拉入。spring-doc.cadn.net.cn

如果您尚未使用spring-test模块之前,你应该先阅读 Spring Framework 参考文档的相关部分spring-doc.cadn.net.cn

9.3. 测试 Spring Boot 应用程序

Spring Boot 应用程序是 SpringApplicationContext,因此不需要做任何非常特别的事情来测试它,而不仅仅是你通常对原版 Spring 上下文所做的测试。spring-doc.cadn.net.cn

默认情况下,Spring Boot 的外部属性、日志记录和其他功能仅在您使用SpringApplication以创建它。

Spring Boot 提供了一个@SpringBootTest注解,可以用作标准spring-test @ContextConfiguration注解。 注释的工作原理是创建ApplicationContext在测试中使用SpringApplication. 除了@SpringBootTest还提供了许多其他 Comments,用于测试应用程序的更具体切片spring-doc.cadn.net.cn

如果您使用的是 JUnit 4,请不要忘记同时添加@RunWith(SpringRunner.class)添加到您的测试中,否则将忽略 Annotations。 如果您使用的是 JUnit 5,则无需添加等效的@ExtendWith(SpringExtension.class)@SpringBootTest和另一个@…​Test注释已经用它进行了注释。

默认情况下,@SpringBootTest不会启动服务器。 您可以使用webEnvironment属性@SpringBootTest要进一步优化测试的运行方式,请执行以下作:spring-doc.cadn.net.cn

  • MOCK(默认) :加载 WebApplicationContext并提供模拟 Web 环境。 使用此注释时,嵌入式服务器不会启动。 如果 Web 环境在 Classpath 上不可用,则此模式透明地回退到创建常规的非 WebApplicationContext. 它可以与@AutoConfigureMockMvc@AutoConfigureWebTestClient用于 Web 应用程序的基于模拟的测试。spring-doc.cadn.net.cn

  • RANDOM_PORT:加载一个WebServerApplicationContext并提供真实的 Web 环境。 嵌入式服务器启动并侦听随机端口。spring-doc.cadn.net.cn

  • DEFINED_PORT:加载一个WebServerApplicationContext并提供真实的 Web 环境。 嵌入式服务器启动并侦听定义的端口(从application.properties) 或默认端口8080.spring-doc.cadn.net.cn

  • NONE:加载一个ApplicationContext通过使用SpringApplication但不提供任何 Web 环境(mock 或其他)。spring-doc.cadn.net.cn

如果您的测试是@Transactional,默认情况下,它会在每个测试方法结束时回滚事务。 但是,由于将此安排与RANDOM_PORTDEFINED_PORT隐式地提供了一个真实的 servlet 环境,HTTP 客户端和服务器在单独的线程中运行,因此,在单独的事务中运行。 在这种情况下,在服务器上启动的任何事务都不会回滚。
@SpringBootTestwebEnvironment = WebEnvironment.RANDOM_PORT如果您的应用程序对 Management Server 使用不同的端口,则还会在单独的随机端口上启动 Management Server。

9.3.1. 检测 Web 应用程序类型

如果 Spring MVC 可用,则配置基于常规 MVC 的应用程序上下文。 如果您只有 Spring WebFlux,我们将检测到该情况并配置基于 WebFlux 的应用程序上下文。spring-doc.cadn.net.cn

如果两者都存在,则 Spring MVC 优先。 如果要在此场景中测试反应式 Web 应用程序,则必须将spring.main.web-application-type财产:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest(properties = "spring.main.web-application-type=reactive")
class MyWebFluxTests {

    // ...

}
Kotlin
import org.springframework.boot.test.context.SpringBootTest

@SpringBootTest(properties = ["spring.main.web-application-type=reactive"])
class MyWebFluxTests {

    // ...

}

9.3.2. 检测测试配置

如果您熟悉 Spring Test Framework,您可能已经习惯了使用@ContextConfiguration(classes=…​)为了指定哪个 Spring@Configuration加载。 或者,您可能经常使用嵌套@Configuration类。spring-doc.cadn.net.cn

在测试 Spring Boot 应用程序时,这通常不是必需的。 Spring Boot 的@*Testannotations 会在您未明确定义 primary 配置时自动搜索 primary 配置。spring-doc.cadn.net.cn

搜索算法从包含测试的包开始向上工作,直到找到一个带有@SpringBootApplication@SpringBootConfiguration. 只要你以合理的方式构建你的代码,你的主要配置通常会被找到。spring-doc.cadn.net.cn

如果使用 test annotation 来测试应用程序的更具体部分,则应避免在 main 方法的 application 类上添加特定于特定区域的配置设置。spring-doc.cadn.net.cn

的底层组件扫描配置@SpringBootApplication定义 Exclude 过滤器,用于确保切片按预期工作。 如果您使用显式的@ComponentScan指令@SpringBootApplication-annotated 类中,请注意这些过滤器将被禁用。 如果您正在使用切片,则应再次定义它们。spring-doc.cadn.net.cn

如果要自定义主配置,可以使用嵌套的@TestConfiguration类。 与嵌套的@Configuration类,该类将用于代替应用程序的主要配置,即嵌套的@TestConfigurationclass 的 API 作为应用程序的主要配置。spring-doc.cadn.net.cn

Spring 的测试框架在测试之间缓存应用程序上下文。 因此,只要您的测试共享相同的配置(无论它是如何发现的),加载上下文的潜在耗时过程只会发生一次。

9.3.3. 使用测试配置 main 方法

通常,由@SpringBootTest将是你的主要@SpringBootApplication. 在大多数结构良好的应用程序中,此配置类还将包括main用于启动应用程序的方法。spring-doc.cadn.net.cn

例如,以下是典型 Spring Boot 应用程序的非常常见的 Code Pattern:spring-doc.cadn.net.cn

Java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }

}
Kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.docs.using.structuringyourcode.locatingthemainclass.MyApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}

在上面的示例中,mainmethod 除了 delegate to 之外不执行任何其他作SpringApplication.run. 但是,可以有一个更复杂的main在调用SpringApplication.run.spring-doc.cadn.net.cn

例如,下面是一个更改横幅模式并设置其他配置文件的应用程序:spring-doc.cadn.net.cn

Java
import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication application = new SpringApplication(MyApplication.class);
        application.setBannerMode(Banner.Mode.OFF);
        application.setAdditionalProfiles("myprofile");
        application.run(args);
    }

}
Kotlin
import org.springframework.boot.Banner
import org.springframework.boot.runApplication
import org.springframework.boot.autoconfigure.SpringBootApplication

@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args) {
        setBannerMode(Banner.Mode.OFF)
        setAdditionalProfiles("myprofile")
    }
}

由于main方法可能会影响生成的ApplicationContext,您可能还希望使用main方法创建ApplicationContext用于测试。 默认情况下,@SpringBootTest不会调用你的main方法,而是直接使用类本身来创建ApplicationContextspring-doc.cadn.net.cn

如果要更改此行为,可以更改useMainMethod属性@SpringBootTestUseMainMethod.ALWAYSUseMainMethod.WHEN_AVAILABLE. 当设置为ALWAYS,则测试将失败,如果为 nomain方法。 当设置为WHEN_AVAILABLEmainmethod (如果可用),否则将使用标准加载机制。spring-doc.cadn.net.cn

例如,以下测试将调用mainmethod 的MyApplication为了创建ApplicationContext. 如果 main 方法设置了其他配置文件,则当ApplicationContext开始。spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.UseMainMethod;

@SpringBootTest(useMainMethod = UseMainMethod.ALWAYS)
class MyApplicationTests {

    @Test
    void exampleTest() {
        // ...
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.context.SpringBootTest.UseMainMethod

@SpringBootTest(useMainMethod = UseMainMethod.ALWAYS)
class MyApplicationTests {

    @Test
    fun exampleTest() {
        // ...
    }

}

9.3.4. 排除测试配置

如果您的应用程序使用组件扫描(例如,如果您使用@SpringBootApplication@ComponentScan),你可能会发现你只为特定测试创建的顶级配置类会意外地被带到任何地方。spring-doc.cadn.net.cn

正如我们之前所看到的,@TestConfiguration可用于 test 的内部类以自定义 primary configuration。@TestConfiguration也可以在顶级类上使用。这样做表示不应通过扫描来选取该类。 然后,您可以在需要的地方显式导入该类,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.annotation.Import;

@SpringBootTest
@Import(MyTestsConfiguration.class)
class MyTests {

    @Test
    void exampleTest() {
        // ...
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.context.annotation.Import

@SpringBootTest
@Import(MyTestsConfiguration::class)
class MyTests {

    @Test
    fun exampleTest() {
        // ...
    }

}
如果你直接使用@ComponentScan(即,不是通过@SpringBootApplication),您需要注册TypeExcludeFilter与它。 有关详细信息,请参阅 Javadoc
一个进口的@TestConfiguration比内部类更早处理@TestConfiguration和导入的@TestConfiguration将在通过组件扫描找到任何配置之前进行处理。 一般来说,这种 Sequences 的差异没有明显的影响,但是如果你依赖于 bean 覆盖,则需要注意这一点。

9.3.5. 使用应用程序参数

如果您的应用程序需要参数,则可以 有@SpringBootTest使用args属性。spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.test.context.SpringBootTest;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(args = "--app.test=one")
class MyApplicationArgumentTests {

    @Test
    void applicationArgumentsPopulated(@Autowired ApplicationArguments args) {
        assertThat(args.getOptionNames()).containsOnly("app.test");
        assertThat(args.getOptionValues("app.test")).containsOnly("one");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.ApplicationArguments
import org.springframework.boot.test.context.SpringBootTest

@SpringBootTest(args = ["--app.test=one"])
class MyApplicationArgumentTests {

    @Test
    fun applicationArgumentsPopulated(@Autowired args: ApplicationArguments) {
        assertThat(args.optionNames).containsOnly("app.test")
        assertThat(args.getOptionValues("app.test")).containsOnly("one")
    }

}

9.3.6. 使用 Mock 环境进行测试

默认情况下,@SpringBootTest不启动服务器,而是设置用于测试 Web 端点的模拟环境。spring-doc.cadn.net.cn

借助 Spring MVC,我们可以使用MockMvcWebTestClient,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@AutoConfigureMockMvc
class MyMockMvcTests {

    @Test
    void testWithMockMvc(@Autowired MockMvc mvc) throws Exception {
        mvc.perform(get("/")).andExpect(status().isOk()).andExpect(content().string("Hello World"));
    }

    // If Spring WebFlux is on the classpath, you can drive MVC tests with a WebTestClient
    @Test
    void testWithWebTestClient(@Autowired WebTestClient webClient) {
        webClient
                .get().uri("/")
                .exchange()
                .expectStatus().isOk()
                .expectBody(String.class).isEqualTo("Hello World");
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.web.reactive.server.WebTestClient
import org.springframework.test.web.reactive.server.expectBody
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders
import org.springframework.test.web.servlet.result.MockMvcResultMatchers

@SpringBootTest
@AutoConfigureMockMvc
class MyMockMvcTests {

    @Test
    fun testWithMockMvc(@Autowired mvc: MockMvc) {
        mvc.perform(MockMvcRequestBuilders.get("/")).andExpect(MockMvcResultMatchers.status().isOk)
            .andExpect(MockMvcResultMatchers.content().string("Hello World"))
    }

    // If Spring WebFlux is on the classpath, you can drive MVC tests with a WebTestClient

    @Test
    fun testWithWebTestClient(@Autowired webClient: WebTestClient) {
        webClient
            .get().uri("/")
            .exchange()
            .expectStatus().isOk
            .expectBody<String>().isEqualTo("Hello World")
    }

}
如果您只想关注 Web 图层,而不启动完整的ApplicationContext考虑@WebMvcTest相反.

通过 Spring WebFlux 端点,您可以使用WebTestClient如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest
@AutoConfigureWebTestClient
class MyMockWebTestClientTests {

    @Test
    void exampleTest(@Autowired WebTestClient webClient) {
        webClient
            .get().uri("/")
            .exchange()
            .expectStatus().isOk()
            .expectBody(String.class).isEqualTo("Hello World");
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.web.reactive.server.WebTestClient
import org.springframework.test.web.reactive.server.expectBody

@SpringBootTest
@AutoConfigureWebTestClient
class MyMockWebTestClientTests {

    @Test
    fun exampleTest(@Autowired webClient: WebTestClient) {
        webClient
            .get().uri("/")
            .exchange()
            .expectStatus().isOk
            .expectBody<String>().isEqualTo("Hello World")
    }

}

在模拟环境中进行测试通常比使用完整的 servlet 容器运行更快。 但是,由于模拟发生在 Spring MVC 层,因此无法直接使用 MockMvc 测试依赖于较低级别 servlet 容器行为的代码。spring-doc.cadn.net.cn

例如, Spring Boot 的错误处理基于 servlet 容器提供的“错误页面”支持。 这意味着,虽然您可以测试 MVC 层是否按预期引发和处理异常,但不能直接测试是否呈现了特定的自定义错误页面。 如果需要测试这些较低级别的问题,可以按照下一节所述启动完全运行的服务器。spring-doc.cadn.net.cn

9.3.7. 使用正在运行的服务器进行测试

如果您需要启动一个完全运行的服务器,我们建议您使用随机端口。 如果您使用@SpringBootTest(webEnvironment=WebEnvironment.RANDOM_PORT),则每次运行测试时都会随机选择一个可用端口。spring-doc.cadn.net.cn

@LocalServerPortannotation 可用于将实际使用的端口注入到测试中。 为方便起见,需要对启动的服务器进行 REST 调用的测试还可以@Autowire一个WebTestClient,它解析到正在运行的服务器的相对链接,并附带一个用于验证响应的专用 API,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.test.web.reactive.server.WebTestClient;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortWebTestClientTests {

    @Test
    void exampleTest(@Autowired WebTestClient webClient) {
        webClient
            .get().uri("/")
            .exchange()
            .expectStatus().isOk()
            .expectBody(String.class).isEqualTo("Hello World");
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment
import org.springframework.test.web.reactive.server.WebTestClient
import org.springframework.test.web.reactive.server.expectBody

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortWebTestClientTests {

    @Test
    fun exampleTest(@Autowired webClient: WebTestClient) {
        webClient
            .get().uri("/")
            .exchange()
            .expectStatus().isOk
            .expectBody<String>().isEqualTo("Hello World")
    }

}
WebTestClient也可以与模拟环境一起使用,无需运行服务器,只需使用@AutoConfigureWebTestClient.

此设置需要spring-webflux在 Classpath 上。 如果你不能或不打算添加 webflux,Spring Boot 还会提供TestRestTemplate设备:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.web.client.TestRestTemplate;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortTestRestTemplateTests {

    @Test
    void exampleTest(@Autowired TestRestTemplate restTemplate) {
        String body = restTemplate.getForObject("/", String.class);
        assertThat(body).isEqualTo("Hello World");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment
import org.springframework.boot.test.web.client.TestRestTemplate

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyRandomPortTestRestTemplateTests {

    @Test
    fun exampleTest(@Autowired restTemplate: TestRestTemplate) {
        val body = restTemplate.getForObject("/", String::class.java)
        assertThat(body).isEqualTo("Hello World")
    }

}

9.3.8. 自定义 WebTestClient

要自定义WebTestClientBean 中,配置WebTestClientBuilderCustomizer豆。 任何此类 bean 都使用WebTestClient.Builder用于创建WebTestClient.spring-doc.cadn.net.cn

9.3.9. 使用 JMX

由于测试上下文框架会缓存上下文,因此默认情况下会禁用 JMX,以防止相同的组件在同一域上注册。 如果此类测试需要访问MBeanServer,也考虑将其标记为 dirty:spring-doc.cadn.net.cn

Java
import javax.management.MBeanServer;

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.annotation.DirtiesContext;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(properties = "spring.jmx.enabled=true")
@DirtiesContext
class MyJmxTests {

    @Autowired
    private MBeanServer mBeanServer;

    @Test
    void exampleTest() {
        assertThat(this.mBeanServer.getDomains()).contains("java.lang");
        // ...
    }

}
Kotlin
import javax.management.MBeanServer

import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.annotation.DirtiesContext

@SpringBootTest(properties = ["spring.jmx.enabled=true"])
@DirtiesContext
class MyJmxTests(@Autowired val mBeanServer: MBeanServer) {

    @Test
    fun exampleTest() {
        assertThat(mBeanServer.domains).contains("java.lang")
        // ...
    }

}

9.3.10. 使用度量

无论您的 Classpath 如何,在使用@SpringBootTest.spring-doc.cadn.net.cn

如果您需要将指标导出到其他后端作为集成测试的一部分,请使用@AutoConfigureObservability.spring-doc.cadn.net.cn

9.3.11. 使用跟踪

无论您的 Classpath 如何,在使用@SpringBootTest.spring-doc.cadn.net.cn

如果您需要将跟踪作为集成测试的一部分,请使用@AutoConfigureObservability.spring-doc.cadn.net.cn

9.3.12. Mocking 和 Spying Bean

运行测试时,有时需要模拟应用程序上下文中的某些组件。 例如,您可能在某些远程服务上有一个在开发过程中不可用的门面。 当您想要模拟在真实环境中可能难以触发的故障时,模拟也很有用。spring-doc.cadn.net.cn

Spring Boot 包括一个@MockBean注解,可用于为您的 bean 定义 Mockito mockApplicationContext. 您可以使用注释添加新的 bean 或替换单个现有的 bean 定义。 注解可以直接用于测试类、测试中的字段或@Configuration类和字段。 当用于字段时,创建的 mock 的实例也会被注入。 Mock bean 在每个测试方法之后都会自动重置。spring-doc.cadn.net.cn

如果你的测试使用 Spring Boot 的测试注释之一(例如@SpringBootTest),则会自动启用此功能。 要将此功能与不同的 arrangement 一起使用,必须显式添加侦听器,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.mock.mockito.MockitoTestExecutionListener;
import org.springframework.boot.test.mock.mockito.ResetMocksTestExecutionListener;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.TestExecutionListeners;

@ContextConfiguration(classes = MyConfig.class)
@TestExecutionListeners({ MockitoTestExecutionListener.class, ResetMocksTestExecutionListener.class })
class MyTests {

    // ...

}
Kotlin
import org.springframework.boot.test.mock.mockito.MockitoTestExecutionListener
import org.springframework.boot.test.mock.mockito.ResetMocksTestExecutionListener
import org.springframework.test.context.ContextConfiguration
import org.springframework.test.context.TestExecutionListeners

@ContextConfiguration(classes = [MyConfig::class])
@TestExecutionListeners(
    MockitoTestExecutionListener::class,
    ResetMocksTestExecutionListener::class
)
class MyTests {

    // ...

}

以下示例将现有的RemoteService具有 mock 实现的 bean:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.BDDMockito.given;

@SpringBootTest
class MyTests {

    @Autowired
    private Reverser reverser;

    @MockBean
    private RemoteService remoteService;

    @Test
    void exampleTest() {
        given(this.remoteService.getValue()).willReturn("spring");
        String reverse = this.reverser.getReverseValue(); // Calls injected RemoteService
        assertThat(reverse).isEqualTo("gnirps");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.mock.mockito.MockBean

@SpringBootTest
class MyTests(@Autowired val reverser: Reverser, @MockBean val remoteService: RemoteService) {

    @Test
    fun exampleTest() {
        given(remoteService.value).willReturn("spring")
        val reverse = reverser.reverseValue // Calls injected RemoteService
        assertThat(reverse).isEqualTo("gnirps")
    }

}
@MockBean不能用于模拟在应用程序上下文刷新期间执行的 bean 的行为。 执行测试时,应用程序上下文刷新已完成,配置模拟行为为时已晚。 我们建议使用@Bean方法来创建和配置 mock。

此外,您还可以使用@SpyBean使用 Mockito 包装任何现有的 beanspy. 有关完整详细信息,请参阅 Javadocspring-doc.cadn.net.cn

虽然 Spring 的测试框架在测试之间缓存应用程序上下文,并为共享相同配置的测试重用上下文,但使用@MockBean@SpyBean影响缓存键,这很可能会增加上下文的数量。
如果您正在使用@SpyBean监视 bean@Cacheable方法,则应用程序必须使用-parameters. 这可确保在监视 Bean 后,参数名称可用于缓存基础结构。
当您使用@SpyBean要监视由 Spring 代理的 bean,在某些情况下可能需要删除 Spring 的代理,例如在使用设置期望值时givenwhen. 用AopTestUtils.getTargetObject(yourProxiedSpy)执行此作。

9.3.13. 自动配置的测试

Spring Boot 的自动配置系统适用于应用程序,但有时对于测试来说可能有点太多了。 通常,仅加载测试应用程序的 “slice” 所需的配置部分会有所帮助。 例如,你可能想要测试 Spring MVC 控制器是否正确映射 URL,并且你不想在这些测试中涉及数据库调用,或者你可能想要测试 JPA 实体,并且你对这些测试运行时的 Web 层不感兴趣。spring-doc.cadn.net.cn

spring-boot-test-autoconfiguremodule 包含许多可用于自动配置此类 “slices” 的 Comments。 它们中的每一个都以类似的方式工作,提供@…​Test注解加载ApplicationContext和一个或多个@AutoConfigure…​可用于自定义自动配置设置的注释。spring-doc.cadn.net.cn

每个 slice 将组件扫描限制为适当的组件,并加载一组非常受限的 auto-configuration classes。 如果您需要排除其中之一,大多数@…​Testannotations 提供了一个excludeAutoConfiguration属性。 或者,您可以使用@ImportAutoConfiguration#exclude.
通过使用多个@…​Test不支持在一个测试中使用注释。 如果您需要多个 “切片”,请选择其中一个@…​Test注解中,并包含@AutoConfigure…​其他 “slices” 的注释。
也可以使用@AutoConfigure…​使用标准的@SpringBootTest注解。 如果您对 “切片” 应用程序不感兴趣,但想要一些自动配置的测试 bean,则可以使用此组合。

9.3.14. 自动配置的 JSON 测试

要测试对象 JSON 序列化和反序列化是否按预期工作,您可以使用@JsonTest注解。@JsonTest自动配置可用的受支持 JSON 映射器,该映射器可以是以下库之一:spring-doc.cadn.net.cn

@JsonTest可以在附录中找到

如果您需要配置自动配置的元素,可以使用@AutoConfigureJsonTesters注解。spring-doc.cadn.net.cn

Spring Boot 包括基于 AssertJ 的帮助程序,这些帮助程序与 JSONAssert 和 JsonPath 库一起使用,以检查 JSON 是否按预期显示。 这JacksonTester,GsonTester,JsonbTesterBasicJsonTester类可以分别用于 Jackson、Gson、Jsonb 和 Strings。 测试类上的任何帮助程序字段都可以是@Autowired使用@JsonTest. 以下示例显示了 Jackson 的 test 类:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.json.JsonTest;
import org.springframework.boot.test.json.JacksonTester;

import static org.assertj.core.api.Assertions.assertThat;

@JsonTest
class MyJsonTests {

    @Autowired
    private JacksonTester<VehicleDetails> json;

    @Test
    void serialize() throws Exception {
        VehicleDetails details = new VehicleDetails("Honda", "Civic");
        // Assert against a `.json` file in the same package as the test
        assertThat(this.json.write(details)).isEqualToJson("expected.json");
        // Or use JSON path based assertions
        assertThat(this.json.write(details)).hasJsonPathStringValue("@.make");
        assertThat(this.json.write(details)).extractingJsonPathStringValue("@.make").isEqualTo("Honda");
    }

    @Test
    void deserialize() throws Exception {
        String content = "{\"make\":\"Ford\",\"model\":\"Focus\"}";
        assertThat(this.json.parse(content)).isEqualTo(new VehicleDetails("Ford", "Focus"));
        assertThat(this.json.parseObject(content).getMake()).isEqualTo("Ford");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.json.JsonTest
import org.springframework.boot.test.json.JacksonTester

@JsonTest
class MyJsonTests(@Autowired val json: JacksonTester<VehicleDetails>) {

    @Test
    fun serialize() {
        val details = VehicleDetails("Honda", "Civic")
        // Assert against a `.json` file in the same package as the test
        assertThat(json.write(details)).isEqualToJson("expected.json")
        // Or use JSON path based assertions
        assertThat(json.write(details)).hasJsonPathStringValue("@.make")
        assertThat(json.write(details)).extractingJsonPathStringValue("@.make").isEqualTo("Honda")
    }

    @Test
    fun deserialize() {
        val content = "{\"make\":\"Ford\",\"model\":\"Focus\"}"
        assertThat(json.parse(content)).isEqualTo(VehicleDetails("Ford", "Focus"))
        assertThat(json.parseObject(content).make).isEqualTo("Ford")
    }

}
JSON 帮助程序类也可以直接在标准单元测试中使用。 为此,请调用initFields方法中的@Before方法(如果不使用@JsonTest.

如果使用 Spring Boot 基于 AssertJ 的帮助程序对给定 JSON 路径中的数字值进行断言,则可能无法使用isEqualTo取决于类型。 相反,您可以使用 AssertJ 的satisfies断言该值与给定条件匹配。 例如,以下示例断言实际数字是接近0.150.01.spring-doc.cadn.net.cn

Java
@Test
void someTest() throws Exception {
    SomeObject value = new SomeObject(0.152f);
    assertThat(this.json.write(value)).extractingJsonPathNumberValue("@.test.numberValue")
        .satisfies((number) -> assertThat(number.floatValue()).isCloseTo(0.15f, within(0.01f)));
}
Kotlin
@Test
fun someTest() {
    val value = SomeObject(0.152f)
    assertThat(json.write(value)).extractingJsonPathNumberValue("@.test.numberValue")
        .satisfies(ThrowingConsumer { number ->
            assertThat(number.toFloat()).isCloseTo(0.15f, within(0.01f))
        })
}

9.3.15. 自动配置的 Spring MVC 测试

要测试 Spring MVC 控制器是否按预期工作,请使用@WebMvcTest注解。@WebMvcTest自动配置 Spring MVC 基础设施并将扫描的 bean 限制为@Controller,@ControllerAdvice,@JsonComponent,Converter,GenericConverter,Filter,HandlerInterceptor,WebMvcConfigurer,WebMvcRegistrationsHandlerMethodArgumentResolver. 定期@Component@ConfigurationProperties@WebMvcTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@WebMvcTest可以在附录中找到
如果您需要注册额外的组件,例如 JacksonModule中,您可以使用@Import在你的测试中。

经常@WebMvcTest仅限于单个控制器,并与@MockBean为所需的协作者提供 mock 实现。spring-doc.cadn.net.cn

@WebMvcTest还可以自动配置MockMvc. Mock MVC 提供了一种强大的方法来快速测试 MVC 控制器,而无需启动完整的 HTTP 服务器。spring-doc.cadn.net.cn

您还可以自动配置MockMvc在非@WebMvcTest(例如@SpringBootTest) 使用@AutoConfigureMockMvc. 以下示例使用MockMvc:
Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.mockito.BDDMockito.given;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(UserVehicleController.class)
class MyControllerTests {

    @Autowired
    private MockMvc mvc;

    @MockBean
    private UserVehicleService userVehicleService;

    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot"))
            .willReturn(new VehicleDetails("Honda", "Civic"));
        this.mvc.perform(get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
            .andExpect(status().isOk())
            .andExpect(content().string("Honda Civic"));
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
import org.springframework.boot.test.mock.mockito.MockBean
import org.springframework.http.MediaType
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders
import org.springframework.test.web.servlet.result.MockMvcResultMatchers

@WebMvcTest(UserVehicleController::class)
class MyControllerTests(@Autowired val mvc: MockMvc) {

    @MockBean
    lateinit var userVehicleService: UserVehicleService

    @Test
    fun testExample() {
        given(userVehicleService.getVehicleDetails("sboot"))
            .willReturn(VehicleDetails("Honda", "Civic"))
        mvc.perform(MockMvcRequestBuilders.get("/sboot/vehicle").accept(MediaType.TEXT_PLAIN))
            .andExpect(MockMvcResultMatchers.status().isOk)
            .andExpect(MockMvcResultMatchers.content().string("Honda Civic"))
    }

}
如果需要配置自动配置的元素(例如,何时应应用 servlet 过滤器),则可以使用@AutoConfigureMockMvc注解。

如果您使用 HtmlUnit 和 Selenium,则自动配置还会提供 HtmlUnitWebClient豆和/或硒WebDriver豆。 下面的示例使用 HtmlUnit:spring-doc.cadn.net.cn

Java
import com.gargoylesoftware.htmlunit.WebClient;
import com.gargoylesoftware.htmlunit.html.HtmlPage;
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;

import static org.assertj.core.api.Assertions.assertThat;
import static org.mockito.BDDMockito.given;

@WebMvcTest(UserVehicleController.class)
class MyHtmlUnitTests {

    @Autowired
    private WebClient webClient;

    @MockBean
    private UserVehicleService userVehicleService;

    @Test
    void testExample() throws Exception {
        given(this.userVehicleService.getVehicleDetails("sboot")).willReturn(new VehicleDetails("Honda", "Civic"));
        HtmlPage page = this.webClient.getPage("/sboot/vehicle.html");
        assertThat(page.getBody().getTextContent()).isEqualTo("Honda Civic");
    }

}
Kotlin
import com.gargoylesoftware.htmlunit.WebClient
import com.gargoylesoftware.htmlunit.html.HtmlPage
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
import org.springframework.boot.test.mock.mockito.MockBean

@WebMvcTest(UserVehicleController::class)
class MyHtmlUnitTests(@Autowired val webClient: WebClient) {

    @MockBean
    lateinit var userVehicleService: UserVehicleService

    @Test
    fun testExample() {
        given(userVehicleService.getVehicleDetails("sboot")).willReturn(VehicleDetails("Honda", "Civic"))
        val page = webClient.getPage<HtmlPage>("/sboot/vehicle.html")
        assertThat(page.body.textContent).isEqualTo("Honda Civic")
    }

}
默认情况下,Spring Boot 将WebDriverbean 中的特殊“范围”,以确保驱动程序在每次测试后退出并注入新实例。 如果您不希望此行为,可以添加@Scope("singleton")发送到您的WebDriver @Bean定义。
webDriver由 Spring Boot 创建的范围将替换任何用户定义的同名范围。 如果您定义自己的webDriver范围,您可能会发现它在使用@WebMvcTest.

如果 class path 上有 Spring Security,则@WebMvcTest还将扫描WebSecurityConfigurer豆。 您可以使用 Spring Security 的测试支持,而不是完全禁用此类测试的安全性。 有关如何使用 Spring Security 的MockMvc支持可以在此 howto.html作方法部分找到。spring-doc.cadn.net.cn

有时编写 Spring MVC 测试是不够的;Spring Boot 可以帮助您使用实际服务器运行完整的端到端测试

9.3.16. 自动配置的 Spring WebFlux 测试

要测试 Spring WebFlux 控制器是否按预期工作,您可以使用@WebFluxTest注解。@WebFluxTest自动配置 Spring WebFlux 基础结构并将扫描的 bean 限制为@Controller,@ControllerAdvice,@JsonComponent,Converter,GenericConverter,WebFilterWebFluxConfigurer. 定期@Component@ConfigurationProperties@WebFluxTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@WebFluxTest可以在附录中找到
如果您需要注册额外的组件,例如 JacksonModule中,您可以使用@Import在你的测试中。

经常@WebFluxTest仅限于单个控制器,并与@MockBean注解为所需的协作者提供模拟实现。spring-doc.cadn.net.cn

@WebFluxTest还可以自动配置WebTestClient,它提供了一种强大的方法来快速测试 WebFlux 控制器,而无需启动完整的 HTTP 服务器。spring-doc.cadn.net.cn

您还可以自动配置WebTestClient在非@WebFluxTest(例如@SpringBootTest) 使用@AutoConfigureWebTestClient. 下面的示例演示一个同时使用@WebFluxTest以及WebTestClient:
Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.http.MediaType;
import org.springframework.test.web.reactive.server.WebTestClient;

import static org.mockito.BDDMockito.given;

@WebFluxTest(UserVehicleController.class)
class MyControllerTests {

    @Autowired
    private WebTestClient webClient;

    @MockBean
    private UserVehicleService userVehicleService;

    @Test
    void testExample() {
        given(this.userVehicleService.getVehicleDetails("sboot"))
            .willReturn(new VehicleDetails("Honda", "Civic"));
        this.webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN).exchange()
            .expectStatus().isOk()
            .expectBody(String.class).isEqualTo("Honda Civic");
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.mockito.BDDMockito.given
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest
import org.springframework.boot.test.mock.mockito.MockBean
import org.springframework.http.MediaType
import org.springframework.test.web.reactive.server.WebTestClient
import org.springframework.test.web.reactive.server.expectBody

@WebFluxTest(UserVehicleController::class)
class MyControllerTests(@Autowired val webClient: WebTestClient) {

    @MockBean
    lateinit var userVehicleService: UserVehicleService

    @Test
    fun testExample() {
        given(userVehicleService.getVehicleDetails("sboot"))
            .willReturn(VehicleDetails("Honda", "Civic"))
        webClient.get().uri("/sboot/vehicle").accept(MediaType.TEXT_PLAIN).exchange()
            .expectStatus().isOk
            .expectBody<String>().isEqualTo("Honda Civic")
    }

}
只有 WebFlux 应用程序支持此设置,因为使用WebTestClient目前仅适用于 WebFlux。
@WebFluxTest无法检测通过 Functional Web 框架注册的路由。 用于测试RouterFunctionbean 中,请考虑导入RouterFunction您自己使用@Import或使用@SpringBootTest.
@WebFluxTest无法检测注册为@Bean的类型SecurityWebFilterChain. 要将其包含在测试中,您需要使用@Import或使用@SpringBootTest.
有时编写 Spring WebFlux 测试是不够的;Spring Boot 可以帮助您使用实际服务器运行完整的端到端测试

9.3.17. 自动配置的 Spring GraphQL 测试

Spring GraphQL 提供了一个专用的测试支持模块;您需要将其添加到您的项目中:spring-doc.cadn.net.cn

Maven 系列
<dependencies>
  <dependency>
    <groupId>org.springframework.graphql</groupId>
    <artifactId>spring-graphql-test</artifactId>
    <scope>test</scope>
  </dependency>
  <!-- Unless already present in the compile scope -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
    <scope>test</scope>
  </dependency>
</dependencies>
Gradle
dependencies {
  testImplementation("org.springframework.graphql:spring-graphql-test")
  // Unless already present in the implementation configuration
  testImplementation("org.springframework.boot:spring-boot-starter-webflux")
}

此测试模块附带 GraphQlTester。 测试器在测试中被大量使用,因此请务必熟悉它的使用。 有GraphQlTester变体和 Spring Boot 将根据测试类型自动配置它们:spring-doc.cadn.net.cn

  • ExecutionGraphQlServiceTester在服务器端执行测试,无需客户端或传输spring-doc.cadn.net.cn

  • HttpGraphQlTester使用连接到服务器的客户端执行测试,无论是否有实时服务器spring-doc.cadn.net.cn

Spring Boot 可帮助您使用@GraphQlTest注解。@GraphQlTest自动配置 Spring GraphQL 基础设施,不涉及任何传输或服务器。 这会将扫描的 bean 限制为@Controller,RuntimeWiringConfigurer,JsonComponent,Converter,GenericConverter,DataFetcherExceptionResolver,InstrumentationGraphQlSourceBuilderCustomizer. 定期@Component@ConfigurationProperties@GraphQlTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@GraphQlTest可以在附录中找到

经常@GraphQlTest仅限于一组控制器,并与@MockBean注解为所需的协作者提供模拟实现。spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.docs.web.graphql.runtimewiring.GreetingController;
import org.springframework.boot.test.autoconfigure.graphql.GraphQlTest;
import org.springframework.graphql.test.tester.GraphQlTester;

@GraphQlTest(GreetingController.class)
class GreetingControllerTests {

    @Autowired
    private GraphQlTester graphQlTester;

    @Test
    void shouldGreetWithSpecificName() {
        this.graphQlTester.document("{ greeting(name: \"Alice\") } ")
            .execute()
            .path("greeting")
            .entity(String.class)
            .isEqualTo("Hello, Alice!");
    }

    @Test
    void shouldGreetWithDefaultName() {
        this.graphQlTester.document("{ greeting } ")
            .execute()
            .path("greeting")
            .entity(String.class)
            .isEqualTo("Hello, Spring!");
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.docs.web.graphql.runtimewiring.GreetingController
import org.springframework.boot.test.autoconfigure.graphql.GraphQlTest
import org.springframework.graphql.test.tester.GraphQlTester

@GraphQlTest(GreetingController::class)
internal class GreetingControllerTests {

    @Autowired
    lateinit var graphQlTester: GraphQlTester

    @Test
    fun shouldGreetWithSpecificName() {
        graphQlTester.document("{ greeting(name: \"Alice\") } ").execute().path("greeting").entity(String::class.java)
                .isEqualTo("Hello, Alice!")
    }

    @Test
    fun shouldGreetWithDefaultName() {
        graphQlTester.document("{ greeting } ").execute().path("greeting").entity(String::class.java)
                .isEqualTo("Hello, Spring!")
    }

}

@SpringBootTest测试是完整的集成测试,涉及整个应用程序。 使用随机端口或定义的端口时,会配置一个实时服务器,并且会配置一个HttpGraphQlTesterbean 是自动提供的,因此您可以使用它来测试您的服务器。 配置 MOCK 环境后,您还可以请求HttpGraphQlTesterBean 来注释您的测试类@AutoConfigureHttpGraphQlTester:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.graphql.tester.AutoConfigureHttpGraphQlTester;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.graphql.test.tester.HttpGraphQlTester;

@AutoConfigureHttpGraphQlTester
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
class GraphQlIntegrationTests {

    @Test
    void shouldGreetWithSpecificName(@Autowired HttpGraphQlTester graphQlTester) {
        HttpGraphQlTester authenticatedTester = graphQlTester.mutate()
            .webTestClient((client) -> client.defaultHeaders((headers) -> headers.setBasicAuth("admin", "ilovespring")))
            .build();
        authenticatedTester.document("{ greeting(name: \"Alice\") } ")
            .execute()
            .path("greeting")
            .entity(String.class)
            .isEqualTo("Hello, Alice!");
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.graphql.tester.AutoConfigureHttpGraphQlTester
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.graphql.test.tester.HttpGraphQlTester
import org.springframework.http.HttpHeaders
import org.springframework.test.web.reactive.server.WebTestClient

@AutoConfigureHttpGraphQlTester
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
class GraphQlIntegrationTests {

    @Test
    fun shouldGreetWithSpecificName(@Autowired graphQlTester: HttpGraphQlTester) {
        val authenticatedTester = graphQlTester.mutate()
            .webTestClient { client: WebTestClient.Builder ->
                client.defaultHeaders { headers: HttpHeaders ->
                    headers.setBasicAuth("admin", "ilovespring")
                }
            }.build()
        authenticatedTester.document("{ greeting(name: \"Alice\") } ").execute()
            .path("greeting").entity(String::class.java).isEqualTo("Hello, Alice!")
    }
}

9.3.18. 自动配置的 Data Cassandra 测试

您可以使用@DataCassandraTest以测试 Cassandra 应用程序。 默认情况下,它会配置CassandraTemplate,扫描@Table类,并配置 Spring Data Cassandra 存储库。 定期@Component@ConfigurationProperties@DataCassandraTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 Cassandra 与 Spring Boot 结合使用的更多信息,请参阅“data.html”。spring-doc.cadn.net.cn

@DataCassandraTest可以在附录中找到

以下示例显示了在 Spring Boot 中使用 Cassandra 测试的典型设置:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.cassandra.DataCassandraTest;

@DataCassandraTest
class MyDataCassandraTests {

    @Autowired
    private SomeRepository repository;

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.cassandra.DataCassandraTest

@DataCassandraTest
class MyDataCassandraTests(@Autowired val repository: SomeRepository)

9.3.19. 自动配置的数据 Couchbase 测试

您可以使用@DataCouchbaseTest测试 Couchbase 应用程序。 默认情况下,它会配置CouchbaseTemplateReactiveCouchbaseTemplate,扫描@Document类,并配置 Spring Data Couchbase 存储库。 定期@Component@ConfigurationProperties@DataCouchbaseTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 Couchbase 与 Spring Boot 结合使用的更多信息,请参阅本章前面的“data.html”。spring-doc.cadn.net.cn

@DataCouchbaseTest可以在附录中找到

以下示例显示了在 Spring Boot 中使用 Couchbase 测试的典型设置:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.couchbase.DataCouchbaseTest;

@DataCouchbaseTest
class MyDataCouchbaseTests {

    @Autowired
    private SomeRepository repository;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.couchbase.DataCouchbaseTest

@DataCouchbaseTest
class MyDataCouchbaseTests(@Autowired val repository: SomeRepository) {

    // ...

}

9.3.20. 自动配置的数据 Elasticsearch 测试

您可以使用@DataElasticsearchTest测试 Elasticsearch 应用程序。 默认情况下,它会配置ElasticsearchRestTemplate,扫描@Document类,并配置 Spring Data Elasticsearch 存储库。 定期@Component@ConfigurationProperties@DataElasticsearchTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 Elasticsearch 与 Spring Boot 结合使用的更多信息,请参阅本章前面的“data.html”。spring-doc.cadn.net.cn

@DataElasticsearchTest可以在附录中找到

以下示例显示了在 Spring Boot 中使用 Elasticsearch 测试的典型设置:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.elasticsearch.DataElasticsearchTest;

@DataElasticsearchTest
class MyDataElasticsearchTests {

    @Autowired
    private SomeRepository repository;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.elasticsearch.DataElasticsearchTest

@DataElasticsearchTest
class MyDataElasticsearchTests(@Autowired val repository: SomeRepository) {

    // ...

}

9.3.21. 自动配置的数据 JPA 测试

您可以使用@DataJpaTest注解来测试 JPA 应用程序。 默认情况下,它会扫描@Entity类并配置 Spring Data JPA 存储库。 如果 Classpath 上有嵌入式数据库可用,则它也会配置一个。 默认情况下,通过设置spring.jpa.show-sqlproperty 设置为true. 这可以使用showSql注解的属性。spring-doc.cadn.net.cn

定期@Component@ConfigurationProperties@DataJpaTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@DataJpaTest可以在附录中找到

默认情况下,数据 JPA 测试是事务性的,并在每次测试结束时回滚。 有关更多详细信息,请参阅 Spring Framework Reference Documentation 中的相关部分。 如果这不是您想要的,则可以禁用测试或整个类的事务 management,如下所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyNonTransactionalTests {

    // ...

}
Kotlin
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest
import org.springframework.transaction.annotation.Propagation
import org.springframework.transaction.annotation.Transactional

@DataJpaTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyNonTransactionalTests {

    // ...

}

数据 JPA 测试还可以注入TestEntityManagerbean,它为标准 JPA 提供了替代方案EntityManager专为测试而设计。spring-doc.cadn.net.cn

TestEntityManager也可以通过添加@AutoConfigureTestEntityManager. 执行此作时,请确保您的测试在事务中运行,例如,通过添加@Transactional在您的测试类或方法上。

一个JdbcTemplate如果需要,也可以使用。 以下示例显示了@DataJpaTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.boot.test.autoconfigure.orm.jpa.TestEntityManager;

import static org.assertj.core.api.Assertions.assertThat;

@DataJpaTest
class MyRepositoryTests {

    @Autowired
    private TestEntityManager entityManager;

    @Autowired
    private UserRepository repository;

    @Test
    void testExample() {
        this.entityManager.persist(new User("sboot", "1234"));
        User user = this.repository.findByUsername("sboot");
        assertThat(user.getUsername()).isEqualTo("sboot");
        assertThat(user.getEmployeeNumber()).isEqualTo("1234");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest
import org.springframework.boot.test.autoconfigure.orm.jpa.TestEntityManager

@DataJpaTest
class MyRepositoryTests(@Autowired val entityManager: TestEntityManager, @Autowired val repository: UserRepository) {

    @Test
    fun testExample() {
        entityManager.persist(User("sboot", "1234"))
        val user = repository.findByUsername("sboot")
        assertThat(user?.username).isEqualTo("sboot")
        assertThat(user?.employeeNumber).isEqualTo("1234")
    }

}

内存嵌入式数据库通常适用于测试,因为它们速度很快且不需要任何安装。 但是,如果您希望对真实数据库运行测试,则可以使用@AutoConfigureTestDatabaseannotation 中,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase.Replace;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;

@DataJpaTest
@AutoConfigureTestDatabase(replace = Replace.NONE)
class MyRepositoryTests {

    // ...

}
Kotlin
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
class MyRepositoryTests {

    // ...

}

9.3.22. 自动配置的 JDBC 测试

@JdbcTest类似于@DataJpaTest但适用于只需要DataSource并且不要使用 Spring Data JDBC。 默认情况下,它会配置一个内存嵌入式数据库和一个JdbcTemplate. 定期@Component@ConfigurationProperties@JdbcTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@JdbcTest可以在附录中找到

默认情况下,JDBC 测试是事务性的,并在每个测试结束时回滚。 有关更多详细信息,请参阅 Spring Framework Reference Documentation 中的相关部分。 如果这不是您想要的,则可以为测试或整个类禁用事务管理,如下所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@JdbcTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyTransactionalTests {

}
Kotlin
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest
import org.springframework.transaction.annotation.Propagation
import org.springframework.transaction.annotation.Transactional

@JdbcTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyTransactionalTests

如果您希望在真实数据库上运行测试,可以使用@AutoConfigureTestDatabase注解,与@DataJpaTest. (请参阅“自动配置的数据 JPA 测试”)spring-doc.cadn.net.cn

9.3.23. 自动配置的数据 JDBC 测试

@DataJdbcTest类似于@JdbcTest但适用于使用 Spring Data JDBC 存储库的测试。 默认情况下,它会配置一个内存中的嵌入式数据库JdbcTemplate和 Spring Data JDBC 存储库。 只AbstractJdbcConfiguration子类在@DataJdbcTestannotation 的@Component@ConfigurationProperties不扫描 bean。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@DataJdbcTest可以在附录中找到

默认情况下,数据 JDBC 测试是事务性的,并在每个测试结束时回滚。 有关更多详细信息,请参阅 Spring Framework Reference Documentation 中的相关部分。 如果这不是您想要的,则可以禁用测试或整个测试类的事务管理,如 JDBC 示例所示spring-doc.cadn.net.cn

如果您希望在真实数据库上运行测试,可以使用@AutoConfigureTestDatabase注解,与@DataJpaTest. (请参阅“自动配置的数据 JPA 测试”)spring-doc.cadn.net.cn

9.3.24. 自动配置的数据 R2DBC 测试

@DataR2dbcTest类似于@DataJdbcTest但适用于使用 Spring Data R2DBC 存储库的测试。 默认情况下,它会配置一个内存中的嵌入式数据库,即R2dbcEntityTemplate和 Spring Data R2DBC 存储库。 定期@Component@ConfigurationProperties@DataR2dbcTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@DataR2dbcTest可以在附录中找到

默认情况下,Data R2DBC 测试不是事务性的。spring-doc.cadn.net.cn

如果您希望在真实数据库上运行测试,可以使用@AutoConfigureTestDatabase注解,与@DataJpaTest. (请参阅“自动配置的数据 JPA 测试”)spring-doc.cadn.net.cn

9.3.25. 自动配置的 jOOQ 测试

您可以使用@JooqTest以类似的方式@JdbcTest但用于 jOOQ 相关的测试。 由于 jOOQ 严重依赖于与数据库架构相对应的基于 Java 的架构,因此现有的DataSource被使用。 如果要将其替换为内存中数据库,可以使用@AutoConfigureTestDatabase以覆盖这些设置。 (有关在 Spring Boot 中使用 jOOQ 的更多信息,请参阅“data.html”。 定期@Component@ConfigurationProperties@JooqTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@JooqTest可以在附录中找到

@JooqTest配置DSLContext. 以下示例显示了@JooqTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.jooq.DSLContext;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.jooq.JooqTest;

@JooqTest
class MyJooqTests {

    @Autowired
    private DSLContext dslContext;

    // ...

}
Kotlin
import org.jooq.DSLContext
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.jooq.JooqTest

@JooqTest
class MyJooqTests(@Autowired val dslContext: DSLContext) {

    // ...

}

默认情况下,JOOQ 测试是事务性的,并且在每个测试结束时回滚。 如果这不是您想要的,则可以禁用测试或整个测试类的事务管理,如 JDBC 示例所示spring-doc.cadn.net.cn

9.3.26. 自动配置的数据 MongoDB 测试

您可以使用@DataMongoTest测试 MongoDB 应用程序。 默认情况下,它会配置MongoTemplate,扫描@Document类,并配置 Spring Data MongoDB 存储库。 定期@Component@ConfigurationProperties@DataMongoTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 MongoDB 与 Spring Boot 结合使用的更多信息,请参阅“data.html”。spring-doc.cadn.net.cn

@DataMongoTest可以在附录中找到

下面的类显示了@DataMongoTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest;
import org.springframework.data.mongodb.core.MongoTemplate;

@DataMongoTest
class MyDataMongoDbTests {

    @Autowired
    private MongoTemplate mongoTemplate;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest
import org.springframework.data.mongodb.core.MongoTemplate

@DataMongoTest
class MyDataMongoDbTests(@Autowired val mongoTemplate: MongoTemplate) {

    // ...

}

9.3.27. 自动配置的数据 Neo4j 测试

您可以使用@DataNeo4jTest测试 Neo4j 应用程序。 默认情况下,它会扫描@Node类,并配置 Spring Data Neo4j 存储库。 定期@Component@ConfigurationProperties@DataNeo4jTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 Neo4J 与 Spring Boot 结合使用的更多信息,请参阅“data.html”。spring-doc.cadn.net.cn

@DataNeo4jTest可以在附录中找到

以下示例显示了在 Spring Boot 中使用 Neo4J 测试的典型设置:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest;

@DataNeo4jTest
class MyDataNeo4jTests {

    @Autowired
    private SomeRepository repository;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest

@DataNeo4jTest
class MyDataNeo4jTests(@Autowired val repository: SomeRepository) {

    // ...

}

默认情况下,Data Neo4j 测试是事务性的,并在每次测试结束时回滚。 有关更多详细信息,请参阅 Spring Framework Reference Documentation 中的相关部分。 如果这不是您想要的,则可以为测试或整个类禁用事务管理,如下所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

@DataNeo4jTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyDataNeo4jTests {

}
Kotlin
import org.springframework.boot.test.autoconfigure.data.neo4j.DataNeo4jTest
import org.springframework.transaction.annotation.Propagation
import org.springframework.transaction.annotation.Transactional

@DataNeo4jTest
@Transactional(propagation = Propagation.NOT_SUPPORTED)
class MyDataNeo4jTests
反应式访问不支持事务性测试。 如果使用此样式,则必须配置@DataNeo4jTest如上所述进行测试。

9.3.28. 自动配置的数据 Redis 测试

您可以使用@DataRedisTest以测试 Redis 应用程序。 默认情况下,它会扫描@RedisHash类和配置 Spring Data Redis 存储库。 定期@Component@ConfigurationProperties@DataRedisTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 Redis 与 Spring Boot 结合使用的更多信息,请参阅“data.html”。spring-doc.cadn.net.cn

@DataRedisTest可以在附录中找到

以下示例显示了@DataRedisTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.redis.DataRedisTest;

@DataRedisTest
class MyDataRedisTests {

    @Autowired
    private SomeRepository repository;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.redis.DataRedisTest

@DataRedisTest
class MyDataRedisTests(@Autowired val repository: SomeRepository) {

    // ...

}

9.3.29. 自动配置的数据 LDAP 测试

您可以使用@DataLdapTest测试 LDAP 应用程序。 默认情况下,它会配置内存中的嵌入式 LDAP(如果可用),将LdapTemplate,扫描@Entry类,并配置 Spring Data LDAP 存储库。 定期@Component@ConfigurationProperties@DataLdapTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。 (有关将 LDAP 与 Spring Boot 结合使用的更多信息,请参阅“data.html”。spring-doc.cadn.net.cn

@DataLdapTest可以在附录中找到

以下示例显示了@DataLdapTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest;
import org.springframework.ldap.core.LdapTemplate;

@DataLdapTest
class MyDataLdapTests {

    @Autowired
    private LdapTemplate ldapTemplate;

    // ...

}
Kotlin
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest
import org.springframework.ldap.core.LdapTemplate

@DataLdapTest
class MyDataLdapTests(@Autowired val ldapTemplate: LdapTemplate) {

    // ...

}

内存中嵌入式 LDAP 通常适用于测试,因为它速度很快,并且不需要任何开发人员安装。 但是,如果您希望针对实际 LDAP 服务器运行测试,则应排除嵌入式 LDAP 自动配置,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.ldap.embedded.EmbeddedLdapAutoConfiguration;
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest;

@DataLdapTest(excludeAutoConfiguration = EmbeddedLdapAutoConfiguration.class)
class MyDataLdapTests {

    // ...

}
Kotlin
import org.springframework.boot.autoconfigure.ldap.embedded.EmbeddedLdapAutoConfiguration
import org.springframework.boot.test.autoconfigure.data.ldap.DataLdapTest

@DataLdapTest(excludeAutoConfiguration = [EmbeddedLdapAutoConfiguration::class])
class MyDataLdapTests {

    // ...

}

9.3.30. 自动配置的 REST 客户端

您可以使用@RestClientTest注解来测试 REST 客户端。 默认情况下,它会自动配置 Jackson、GSON 和 Jsonb 支持,配置RestTemplateBuilder,并添加了对MockRestServiceServer. 定期@Component@ConfigurationProperties@RestClientTestannotation 的 intent 中。@EnableConfigurationProperties可用于包括@ConfigurationProperties豆。spring-doc.cadn.net.cn

@RestClientTest可以在附录中找到

要测试的特定 bean 应使用valuecomponents属性@RestClientTest,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.client.RestClientTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.client.MockRestServiceServer;

import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;

@RestClientTest(RemoteVehicleDetailsService.class)
class MyRestClientTests {

    @Autowired
    private RemoteVehicleDetailsService service;

    @Autowired
    private MockRestServiceServer server;

    @Test
    void getVehicleDetailsWhenResultIsSuccessShouldReturnDetails() {
        this.server.expect(requestTo("/greet/details")).andRespond(withSuccess("hello", MediaType.TEXT_PLAIN));
        String greeting = this.service.callRestService();
        assertThat(greeting).isEqualTo("hello");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.web.client.RestClientTest
import org.springframework.http.MediaType
import org.springframework.test.web.client.MockRestServiceServer
import org.springframework.test.web.client.match.MockRestRequestMatchers
import org.springframework.test.web.client.response.MockRestResponseCreators

@RestClientTest(RemoteVehicleDetailsService::class)
class MyRestClientTests(
    @Autowired val service: RemoteVehicleDetailsService,
    @Autowired val server: MockRestServiceServer) {

    @Test
    fun getVehicleDetailsWhenResultIsSuccessShouldReturnDetails() {
        server.expect(MockRestRequestMatchers.requestTo("/greet/details"))
            .andRespond(MockRestResponseCreators.withSuccess("hello", MediaType.TEXT_PLAIN))
        val greeting = service.callRestService()
        assertThat(greeting).isEqualTo("hello")
    }

}

9.3.31. 自动配置的 Spring REST Docs 测试

您可以使用@AutoConfigureRestDocs注解在带有 Mock MVC、REST Assure 或 WebTestClient 的测试中使用 Spring REST Docs。 它消除了 Spring REST Docs 中对 JUnit 扩展的需求。spring-doc.cadn.net.cn

@AutoConfigureRestDocs可用于覆盖默认输出目录 (target/generated-snippets如果您使用的是 Maven 或build/generated-snippets如果您使用的是 Gradle)。 它还可用于配置出现在任何记录的 URI 中的主机、方案和端口。spring-doc.cadn.net.cn

使用模拟 MVC 自动配置的 Spring REST 文档测试

@AutoConfigureRestDocs自定义MockMvcbean 在测试基于 servlet 的 Web 应用程序时使用 Spring REST Docs。 您可以使用@Autowired并像通常使用 Mock MVC 和 Spring REST Docs 时一样在测试中使用它,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest(UserController.class)
@AutoConfigureRestDocs
class MyUserDocumentationTests {

    @Autowired
    private MockMvc mvc;

    @Test
    void listUsers() throws Exception {
        this.mvc.perform(get("/users").accept(MediaType.TEXT_PLAIN))
            .andExpect(status().isOk())
            .andDo(document("list-users"));
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
import org.springframework.http.MediaType
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders
import org.springframework.test.web.servlet.result.MockMvcResultMatchers

@WebMvcTest(UserController::class)
@AutoConfigureRestDocs
class MyUserDocumentationTests(@Autowired val mvc: MockMvc) {

    @Test
    fun listUsers() {
        mvc.perform(MockMvcRequestBuilders.get("/users").accept(MediaType.TEXT_PLAIN))
            .andExpect(MockMvcResultMatchers.status().isOk)
            .andDo(MockMvcRestDocumentation.document("list-users"))
    }

}

如果你需要对 Spring REST Docs 配置的控制比@AutoConfigureRestDocs,您可以使用RestDocsMockMvcConfigurationCustomizerbean,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsMockMvcConfigurationCustomizer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentationConfigurer;
import org.springframework.restdocs.templates.TemplateFormats;

@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsMockMvcConfigurationCustomizer {

    @Override
    public void customize(MockMvcRestDocumentationConfigurer configurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
    }

}
Kotlin
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsMockMvcConfigurationCustomizer
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentationConfigurer
import org.springframework.restdocs.templates.TemplateFormats

@TestConfiguration(proxyBeanMethods = false)
class MyRestDocsConfiguration : RestDocsMockMvcConfigurationCustomizer {

    override fun customize(configurer: MockMvcRestDocumentationConfigurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown())
    }

}

如果你想利用 Spring REST Docs 对参数化输出目录的支持,你可以创建一个RestDocumentationResultHandler豆。 自动配置调用alwaysDo,从而导致每个MockMvc调用 以自动生成默认代码段。 以下示例显示了RestDocumentationResultHandler正在定义:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler;

@TestConfiguration(proxyBeanMethods = false)
public class MyResultHandlerConfiguration {

    @Bean
    public RestDocumentationResultHandler restDocumentation() {
        return MockMvcRestDocumentation.document("{method-name}");
    }

}
Kotlin
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.context.annotation.Bean
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation
import org.springframework.restdocs.mockmvc.RestDocumentationResultHandler

@TestConfiguration(proxyBeanMethods = false)
class MyResultHandlerConfiguration {

    @Bean
    fun restDocumentation(): RestDocumentationResultHandler {
        return MockMvcRestDocumentation.document("{method-name}")
    }

}
使用 WebTestClient 自动配置的 Spring REST Docs 测试

@AutoConfigureRestDocs也可与WebTestClient在测试反应式 Web 应用程序时。 您可以使用@Autowired并像通常使用@WebFluxTest和 Spring REST Docs,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest;
import org.springframework.test.web.reactive.server.WebTestClient;

import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

@WebFluxTest
@AutoConfigureRestDocs
class MyUsersDocumentationTests {

    @Autowired
    private WebTestClient webTestClient;

    @Test
    void listUsers() {
        this.webTestClient
            .get().uri("/")
        .exchange()
        .expectStatus()
            .isOk()
        .expectBody()
            .consumeWith(document("list-users"));
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
import org.springframework.boot.test.autoconfigure.web.reactive.WebFluxTest
import org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation
import org.springframework.test.web.reactive.server.WebTestClient

@WebFluxTest
@AutoConfigureRestDocs
class MyUsersDocumentationTests(@Autowired val webTestClient: WebTestClient) {

    @Test
    fun listUsers() {
        webTestClient
            .get().uri("/")
            .exchange()
            .expectStatus()
            .isOk
            .expectBody()
            .consumeWith(WebTestClientRestDocumentation.document("list-users"))
    }

}

如果你需要对 Spring REST Docs 配置的控制比@AutoConfigureRestDocs,您可以使用RestDocsWebTestClientConfigurationCustomizerbean,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsWebTestClientConfigurationCustomizer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.restdocs.webtestclient.WebTestClientRestDocumentationConfigurer;

@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsWebTestClientConfigurationCustomizer {

    @Override
    public void customize(WebTestClientRestDocumentationConfigurer configurer) {
        configurer.snippets().withEncoding("UTF-8");
    }

}
Kotlin
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsWebTestClientConfigurationCustomizer
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.restdocs.webtestclient.WebTestClientRestDocumentationConfigurer

@TestConfiguration(proxyBeanMethods = false)
class MyRestDocsConfiguration : RestDocsWebTestClientConfigurationCustomizer {

    override fun customize(configurer: WebTestClientRestDocumentationConfigurer) {
        configurer.snippets().withEncoding("UTF-8")
    }

}

如果你想利用 Spring REST Docs 对参数化输出目录的支持,你可以使用WebTestClientBuilderCustomizer为每个实体交换结果配置使用者。 以下示例显示了这样一个WebTestClientBuilderCustomizer正在定义:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.test.web.reactive.server.WebTestClientBuilderCustomizer;
import org.springframework.context.annotation.Bean;

import static org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.document;

@TestConfiguration(proxyBeanMethods = false)
public class MyWebTestClientBuilderCustomizerConfiguration {

    @Bean
    public WebTestClientBuilderCustomizer restDocumentation() {
        return (builder) -> builder.entityExchangeResultConsumer(document("{method-name}"));
    }

}
Kotlin
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.test.web.reactive.server.WebTestClientBuilderCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation
import org.springframework.test.web.reactive.server.WebTestClient

@TestConfiguration(proxyBeanMethods = false)
class MyWebTestClientBuilderCustomizerConfiguration {

    @Bean
    fun restDocumentation(): WebTestClientBuilderCustomizer {
        return WebTestClientBuilderCustomizer { builder: WebTestClient.Builder ->
            builder.entityExchangeResultConsumer(
                WebTestClientRestDocumentation.document("{method-name}")
            )
        }
    }

}
使用 REST Assured 自动配置的 Spring REST Docs 测试

@AutoConfigureRestDocs使RequestSpecificationbean,预配置为使用 Spring REST Docs,可用于您的测试。 您可以使用@Autowired并在测试中使用它,就像通常使用 REST Assured 和 Spring REST Docs 时一样,如以下示例所示:spring-doc.cadn.net.cn

Java
import io.restassured.specification.RequestSpecification;
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.web.server.LocalServerPort;

import static io.restassured.RestAssured.given;
import static org.hamcrest.Matchers.is;
import static org.springframework.restdocs.restassured.RestAssuredRestDocumentation.document;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestDocs
class MyUserDocumentationTests {

    @Test
    void listUsers(@Autowired RequestSpecification documentationSpec, @LocalServerPort int port) {
        given(documentationSpec)
            .filter(document("list-users"))
        .when()
            .port(port)
            .get("/")
        .then().assertThat()
            .statusCode(is(200));
    }

}
Kotlin
import io.restassured.RestAssured
import io.restassured.specification.RequestSpecification
import org.hamcrest.Matchers
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment
import org.springframework.boot.test.web.server.LocalServerPort
import org.springframework.restdocs.restassured.RestAssuredRestDocumentation

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestDocs
class MyUserDocumentationTests {

    @Test
    fun listUsers(@Autowired documentationSpec: RequestSpecification?, @LocalServerPort port: Int) {
        RestAssured.given(documentationSpec)
            .filter(RestAssuredRestDocumentation.document("list-users"))
            .`when`()
            .port(port)["/"]
            .then().assertThat()
            .statusCode(Matchers.`is`(200))
    }

}

如果你需要对 Spring REST Docs 配置的控制比@AutoConfigureRestDocs一个RestDocsRestAssuredConfigurationCustomizer可以使用 bean,如下例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsRestAssuredConfigurationCustomizer;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.restdocs.restassured.RestAssuredRestDocumentationConfigurer;
import org.springframework.restdocs.templates.TemplateFormats;

@TestConfiguration(proxyBeanMethods = false)
public class MyRestDocsConfiguration implements RestDocsRestAssuredConfigurationCustomizer {

    @Override
    public void customize(RestAssuredRestDocumentationConfigurer configurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown());
    }

}
Kotlin
import org.springframework.boot.test.autoconfigure.restdocs.RestDocsRestAssuredConfigurationCustomizer
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.restdocs.restassured.RestAssuredRestDocumentationConfigurer
import org.springframework.restdocs.templates.TemplateFormats

@TestConfiguration(proxyBeanMethods = false)
class MyRestDocsConfiguration : RestDocsRestAssuredConfigurationCustomizer {

    override fun customize(configurer: RestAssuredRestDocumentationConfigurer) {
        configurer.snippets().withTemplateFormat(TemplateFormats.markdown())
    }

}

9.3.32. 自动配置的 Spring Web 服务测试

自动配置的 Spring Web 服务客户端测试

您可以使用@WebServiceClientTest测试使用 Spring Web Services 项目调用 Web 服务的应用程序。 默认情况下,它会配置一个 mockWebServiceServerbean 并自动自定义您的WebServiceTemplateBuilder. (有关将 Web 服务与 Spring Boot 结合使用的更多信息,请参阅“io.html”。spring-doc.cadn.net.cn

@WebServiceClientTest可以在附录中找到

以下示例显示了@WebServiceClientTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.webservices.client.WebServiceClientTest;
import org.springframework.ws.test.client.MockWebServiceServer;
import org.springframework.xml.transform.StringSource;

import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.ws.test.client.RequestMatchers.payload;
import static org.springframework.ws.test.client.ResponseCreators.withPayload;

@WebServiceClientTest(SomeWebService.class)
class MyWebServiceClientTests {

    @Autowired
    private MockWebServiceServer server;

    @Autowired
    private SomeWebService someWebService;

    @Test
    void mockServerCall() {
        this.server
            .expect(payload(new StringSource("<request/>")))
            .andRespond(withPayload(new StringSource("<response><status>200</status></response>")));
        assertThat(this.someWebService.test())
            .extracting(Response::getStatus)
            .isEqualTo(200);
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.webservices.client.WebServiceClientTest
import org.springframework.ws.test.client.MockWebServiceServer
import org.springframework.ws.test.client.RequestMatchers
import org.springframework.ws.test.client.ResponseCreators
import org.springframework.xml.transform.StringSource

@WebServiceClientTest(SomeWebService::class)
class MyWebServiceClientTests(@Autowired val server: MockWebServiceServer, @Autowired val someWebService: SomeWebService) {

    @Test
    fun mockServerCall() {
        server
            .expect(RequestMatchers.payload(StringSource("<request/>")))
            .andRespond(ResponseCreators.withPayload(StringSource("<response><status>200</status></response>")))
        assertThat(this.someWebService.test()).extracting(Response::status).isEqualTo(200)
    }

}
自动配置的 Spring Web 服务服务器测试

您可以使用@WebServiceServerTest测试使用 Spring Web Services 项目实现 Web 服务的应用程序。 默认情况下,它会配置MockWebServiceClient可用于调用 Web 服务终端节点的 bean。 (有关将 Web 服务与 Spring Boot 结合使用的更多信息,请参阅“io.html”。spring-doc.cadn.net.cn

@WebServiceServerTest可以在附录中找到

以下示例显示了@WebServiceServerTest正在使用的注释:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.webservices.server.WebServiceServerTest;
import org.springframework.ws.test.server.MockWebServiceClient;
import org.springframework.ws.test.server.RequestCreators;
import org.springframework.ws.test.server.ResponseMatchers;
import org.springframework.xml.transform.StringSource;

@WebServiceServerTest(ExampleEndpoint.class)
class MyWebServiceServerTests {

    @Autowired
    private MockWebServiceClient client;

    @Test
    void mockServerCall() {
        this.client
            .sendRequest(RequestCreators.withPayload(new StringSource("<ExampleRequest/>")))
            .andExpect(ResponseMatchers.payload(new StringSource("<ExampleResponse>42</ExampleResponse>")));
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.webservices.server.WebServiceServerTest
import org.springframework.ws.test.server.MockWebServiceClient
import org.springframework.ws.test.server.RequestCreators
import org.springframework.ws.test.server.ResponseMatchers
import org.springframework.xml.transform.StringSource

@WebServiceServerTest(ExampleEndpoint::class)
class MyWebServiceServerTests(@Autowired val client: MockWebServiceClient) {

    @Test
    fun mockServerCall() {
        client
            .sendRequest(RequestCreators.withPayload(StringSource("<ExampleRequest/>")))
            .andExpect(ResponseMatchers.payload(StringSource("<ExampleResponse>42</ExampleResponse>")))
    }

}

9.3.33. 其他自动配置和切片

每个切片提供一个或多个@AutoConfigure…​注解,即定义应作为切片的一部分包含的自动配置。 可以通过创建自定义@AutoConfigure…​注解或通过添加@ImportAutoConfiguration添加到测试中,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
import org.springframework.boot.autoconfigure.integration.IntegrationAutoConfiguration;
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest;

@JdbcTest
@ImportAutoConfiguration(IntegrationAutoConfiguration.class)
class MyJdbcTests {

}
Kotlin
import org.springframework.boot.autoconfigure.ImportAutoConfiguration
import org.springframework.boot.autoconfigure.integration.IntegrationAutoConfiguration
import org.springframework.boot.test.autoconfigure.jdbc.JdbcTest

@JdbcTest
@ImportAutoConfiguration(IntegrationAutoConfiguration::class)
class MyJdbcTests
确保不要使用常规的@Import注解导入自动配置,因为它们是由 Spring Boot 以特定方式处理的。

或者,可以通过在存储在META-INF/spring如以下示例所示:spring-doc.cadn.net.cn

META-INF/spring/org.springframework.boot.test.autoconfigure.jdbc.JdbcTest.imports
com.example.IntegrationAutoConfiguration

在此示例中,com.example.IntegrationAutoConfiguration在每个注释有@JdbcTest.spring-doc.cadn.net.cn

您可以在此文件中使用 Comments。#
切片或@AutoConfigure…​annotation 可以通过这种方式进行自定义,只要它使用@ImportAutoConfiguration.

9.3.34. 用户配置和切片

如果您以合理的方式构建代码,则@SpringBootApplicationclass 默认用作测试的配置。spring-doc.cadn.net.cn

因此,重要的是不要在应用程序的主类中混淆特定于其特定功能区域的配置设置。spring-doc.cadn.net.cn

假设您使用的是 Spring Data MongoDB,您依赖于它的自动配置,并且您已启用审计。 您可以定义@SpringBootApplication如下:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.data.mongodb.config.EnableMongoAuditing;

@SpringBootApplication
@EnableMongoAuditing
public class MyApplication {

    // ...

}
Kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.data.mongodb.config.EnableMongoAuditing

@SpringBootApplication
@EnableMongoAuditing
class MyApplication {

    // ...

}

因为这个类是测试的源配置,所以任何切片测试实际上都会尝试启用 Mongo 审计,这绝对不是你想要的。 推荐的方法是将特定于区域的配置移动到单独的@Configuration类,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.context.annotation.Configuration;
import org.springframework.data.mongodb.config.EnableMongoAuditing;

@Configuration(proxyBeanMethods = false)
@EnableMongoAuditing
public class MyMongoConfiguration {

    // ...

}
Kotlin
import org.springframework.context.annotation.Configuration
import org.springframework.data.mongodb.config.EnableMongoAuditing

@Configuration(proxyBeanMethods = false)
@EnableMongoAuditing
class MyMongoConfiguration {

    // ...

}
根据应用程序的复杂程度,您可能有一个@Configurationclass (类) 或每个域区域一个类。 后一种方法允许您在其中一个测试中启用它,如有必要,使用@Import注解。 请参阅此作方法部分,了解有关何时可能需要启用特定@Configuration类。

测试切片排除@Configuration类。 例如,对于@WebMvcTest,则以下配置将不包含给定的WebMvcConfigurerbean 中:spring-doc.cadn.net.cn

Java
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration(proxyBeanMethods = false)
public class MyWebConfiguration {

    @Bean
    public WebMvcConfigurer testConfigurer() {
        return new WebMvcConfigurer() {
            // ...
        };
    }

}
Kotlin
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer

@Configuration(proxyBeanMethods = false)
class MyWebConfiguration {

    @Bean
    fun testConfigurer(): WebMvcConfigurer {
        return object : WebMvcConfigurer {
            // ...
        }
    }

}

但是,下面的配置将导致自定义WebMvcConfigurer由测试切片加载。spring-doc.cadn.net.cn

Java
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Component
public class MyWebMvcConfigurer implements WebMvcConfigurer {

    // ...

}
Kotlin
import org.springframework.stereotype.Component
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer

@Component
class MyWebMvcConfigurer : WebMvcConfigurer {

    // ...

}

另一个混淆的来源是 Classpath scanning。 假设您以合理的方式构建了代码,但需要扫描其他包。 您的应用程序可能类似于以下代码:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan({ "com.example.app", "com.example.another" })
public class MyApplication {

    // ...

}
Kotlin
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.context.annotation.ComponentScan

@SpringBootApplication
@ComponentScan("com.example.app", "com.example.another")
class MyApplication {

    // ...

}

这样做可以有效地覆盖默认的组件 scan 指令,其副作用是扫描这两个包,而不管你选择了哪个 slice。 例如,@DataJpaTest似乎突然扫描了应用程序的组件和用户配置。 同样,将 custom 指令移动到单独的类是解决此问题的好方法。spring-doc.cadn.net.cn

如果这不是您的选项,您可以创建一个@SpringBootConfiguration在测试层次结构中的某个位置,以便改用它。 或者,您可以为测试指定一个源,这将禁用查找默认源的行为。

9.3.35. 使用 Spock 测试 Spring Boot 应用程序

Spock 2.2 或更高版本可用于测试 Spring Boot 应用程序。 为此,请在-groovy-4.0Spock 的版本spock-springmodule 添加到应用程序的 build 中。spock-spring将 Spring 的测试框架集成到 Spock 中。 有关更多详细信息,请参阅 Spock 的 Spring 模块的文档spring-doc.cadn.net.cn

9.4. 测试容器

Testcontainers 库提供了一种管理在 Docker 容器中运行的服务的方法。 它与 JUnit 集成,允许您编写一个测试类,该类可以在任何测试运行之前启动容器。 Testcontainers 对于编写与实际后端服务(如 MySQL、MongoDB、Cassandra 等)通信的集成测试特别有用。spring-doc.cadn.net.cn

Testcontainers 可以在 Spring Boot 测试中使用,如下所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import org.springframework.boot.test.context.SpringBootTest;

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Container
    static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5");

    @Test
    void myTest() {
        // ...
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.boot.test.context.SpringBootTest
import org.testcontainers.containers.Neo4jContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Test
    fun myTest() {
        // ...
    }

    companion object {
        @Container
        val neo4j = Neo4jContainer("neo4j:5")
    }

}

这将在运行任何测试之前启动运行 Neo4j(如果 Docker 在本地运行)的 docker 容器。 在大多数情况下,您需要配置应用程序以连接到容器中运行的服务。spring-doc.cadn.net.cn

9.4.1. 服务连接

服务连接是与任何远程服务的连接。 Spring Boot 的自动配置可以使用服务连接的详细信息,并使用它们来建立与远程服务的连接。 执行此作时,连接详细信息优先于任何与连接相关的配置属性。spring-doc.cadn.net.cn

使用 Testcontainers 时,可以通过在 test 类中注释 container 字段,为容器中运行的服务自动创建连接详细信息。spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Container
    @ServiceConnection
    static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5");

    @Test
    void myTest() {
        // ...
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.testcontainers.containers.Neo4jContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Test
    fun myTest() {
        // ...
    }

    companion object {

        @Container
        @ServiceConnection
        val neo4j = Neo4jContainer("neo4j:5")

    }

}

由于@ServiceConnection,上述配置允许应用程序中与 Neo4j 相关的 bean 与在 Testcontainers 管理的 Docker 容器内运行的 Neo4j 进行通信。 这是通过自动定义Neo4jConnectionDetailsbean,然后由 Neo4j 自动配置使用,覆盖任何与连接相关的配置属性。spring-doc.cadn.net.cn

您需要添加spring-boot-testcontainersmodule 作为测试依赖项,以便将服务连接与 Testcontainers 一起使用。

服务连接注释由ContainerConnectionDetailsFactory注册的类spring.factories. 一个ContainerConnectionDetailsFactory可以创建一个ConnectionDetailsbean 基于特定的Container子类或 Docker 镜像名称。spring-doc.cadn.net.cn

以下服务连接工厂在spring-boot-testcontainers罐:spring-doc.cadn.net.cn

连接详细信息 匹配时间

CassandraConnectionDetailsspring-doc.cadn.net.cn

类型的容器CassandraContainerspring-doc.cadn.net.cn

CouchbaseConnectionDetailsspring-doc.cadn.net.cn

类型的容器CouchbaseContainerspring-doc.cadn.net.cn

ElasticsearchConnectionDetailsspring-doc.cadn.net.cn

类型的容器ElasticsearchContainerspring-doc.cadn.net.cn

FlywayConnectionDetailsspring-doc.cadn.net.cn

类型的容器JdbcDatabaseContainerspring-doc.cadn.net.cn

JdbcConnectionDetailsspring-doc.cadn.net.cn

类型的容器JdbcDatabaseContainerspring-doc.cadn.net.cn

KafkaConnectionDetailsspring-doc.cadn.net.cn

类型的容器KafkaContainerRedpandaContainerspring-doc.cadn.net.cn

LiquibaseConnectionDetailsspring-doc.cadn.net.cn

类型的容器JdbcDatabaseContainerspring-doc.cadn.net.cn

MongoConnectionDetailsspring-doc.cadn.net.cn

类型的容器MongoDBContainerspring-doc.cadn.net.cn

Neo4jConnectionDetailsspring-doc.cadn.net.cn

类型的容器Neo4jContainerspring-doc.cadn.net.cn

R2dbcConnectionDetailsspring-doc.cadn.net.cn

类型的容器MariaDBContainer,MSSQLServerContainer,MySQLContainer,OracleContainerPostgreSQLContainerspring-doc.cadn.net.cn

RabbitConnectionDetailsspring-doc.cadn.net.cn

类型的容器RabbitMQContainerspring-doc.cadn.net.cn

RedisConnectionDetailsspring-doc.cadn.net.cn

名为 “redis” 的容器spring-doc.cadn.net.cn

ZipkinConnectionDetailsspring-doc.cadn.net.cn

名为 “openzipkin/zipkin” 的容器spring-doc.cadn.net.cn

默认情况下,将为给定的 bean 创建所有适用的连接详细信息 beanContainer. 例如,PostgreSQLContainer将同时创建JdbcConnectionDetailsR2dbcConnectionDetails.spring-doc.cadn.net.cn

如果只想创建适用类型的子集,可以使用type属性@ServiceConnection.spring-doc.cadn.net.cn

默认情况下Container.getDockerImageName()用于获取用于查找连接详细信息的名称。 只要 Spring Boot 能够获取Container,当使用static字段。spring-doc.cadn.net.cn

如果您使用的是@Bean方法,Spring Boot 不会调用 bean 方法来获取 Docker 镜像名称,因为这会导致急切初始化问题。 相反,使用 bean 方法的返回类型来找出应该使用哪个连接详细信息。 只要你使用的是类型化容器,这就可以正常工作,例如Neo4jContainerRabbitMQContainer. 如果您正在使用GenericContainer,例如使用 Redis,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.testcontainers.containers.GenericContainer;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;

@TestConfiguration(proxyBeanMethods = false)
public class MyRedisConfiguration {

    @Bean
    @ServiceConnection(name = "redis")
    public GenericContainer<?> redisContainer() {
        return new GenericContainer<>("redis:7");
    }

}
Kotlin
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.springframework.context.annotation.Bean
import org.testcontainers.containers.GenericContainer

@TestConfiguration(proxyBeanMethods = false)
class MyRedisConfiguration {

    @Bean
    @ServiceConnection(name = "redis")
    fun redisContainer(): GenericContainer<*> {
        return GenericContainer("redis:7")
    }

}

Spring Boot 无法判断GenericContainer使用哪个容器镜像,那么name属性从@ServiceConnection必须用于提供该提示。spring-doc.cadn.net.cn

您还可以使用name属性@ServiceConnection覆盖将使用的连接详细信息,例如,在使用自定义图像时。 如果您使用的是 Docker 镜像registry.mycompany.com/mirror/myredis,您将使用@ServiceConnection(name="redis")确保RedisConnectionDetails创建。spring-doc.cadn.net.cn

9.4.2. 动态属性

与服务连接相比,一个稍微详细但更灵活的替代方案是@DynamicPropertySource. 静态@DynamicPropertySourcemethod 允许向 Spring Environment 添加动态属性值。spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Container
    static Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5");

    @Test
    void myTest() {
        // ...
    }

    @DynamicPropertySource
    static void neo4jProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.neo4j.uri", neo4j::getBoltUrl);
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.test.context.DynamicPropertyRegistry
import org.springframework.test.context.DynamicPropertySource
import org.testcontainers.containers.Neo4jContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers

@Testcontainers
@SpringBootTest
class MyIntegrationTests {

    @Test
    fun myTest() {
        // ...
    }

    companion object {

        @Container
        val neo4j = Neo4jContainer("neo4j:5")

        @DynamicPropertySource
        fun neo4jProperties(registry: DynamicPropertyRegistry) {
            registry.add("spring.neo4j.uri") { neo4j.boltUrl }
        }

    }

}

上述配置允许应用程序中与 Neo4j 相关的 bean 与在 Testcontainers 管理的 Docker 容器内运行的 Neo4j 进行通信。spring-doc.cadn.net.cn

9.5. 测试工具

在测试应用程序时通常有用的一些测试工具类打包为spring-boot.spring-doc.cadn.net.cn

9.5.1. ConfigDataApplicationContextInitializer

ConfigDataApplicationContextInitializer是一个ApplicationContextInitializer您可以将其应用于测试以加载 Spring Bootapplication.properties文件。 当您不需要@SpringBootTest,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.context.ConfigDataApplicationContextInitializer;
import org.springframework.test.context.ContextConfiguration;

@ContextConfiguration(classes = Config.class, initializers = ConfigDataApplicationContextInitializer.class)
class MyConfigFileTests {

    // ...

}
Kotlin
import org.springframework.boot.test.context.ConfigDataApplicationContextInitializer
import org.springframework.test.context.ContextConfiguration

@ContextConfiguration(classes = [Config::class], initializers = [ConfigDataApplicationContextInitializer::class])
class MyConfigFileTests {

    // ...

}
ConfigDataApplicationContextInitializer单独不支持@Value("${…​}")注射。 它唯一的工作是确保application.properties文件被加载到 Spring 的Environment. 为@Valuesupport 支持,您需要额外配置PropertySourcesPlaceholderConfigurer或使用@SpringBootTest,它会自动为您配置一个。

9.5.2. TestPropertyValues

TestPropertyValues允许您快速将属性添加到ConfigurableEnvironmentConfigurableApplicationContext. 你可以用key=value字符串,如下所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.boot.test.util.TestPropertyValues;
import org.springframework.mock.env.MockEnvironment;

import static org.assertj.core.api.Assertions.assertThat;

class MyEnvironmentTests {

    @Test
    void testPropertySources() {
        MockEnvironment environment = new MockEnvironment();
        TestPropertyValues.of("org=Spring", "name=Boot").applyTo(environment);
        assertThat(environment.getProperty("name")).isEqualTo("Boot");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.boot.test.util.TestPropertyValues
import org.springframework.mock.env.MockEnvironment

class MyEnvironmentTests {

    @Test
    fun testPropertySources() {
        val environment = MockEnvironment()
        TestPropertyValues.of("org=Spring", "name=Boot").applyTo(environment)
        assertThat(environment.getProperty("name")).isEqualTo("Boot")
    }

}

9.5.3. 输出捕获

OutputCapture是一个 JUnitExtension可用于捕获System.outSystem.err输出。 要使用它,请添加@ExtendWith(OutputCaptureExtension.class)并注入CapturedOutput作为测试类构造函数或测试方法的参数,如下所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

import org.springframework.boot.test.system.CapturedOutput;
import org.springframework.boot.test.system.OutputCaptureExtension;

import static org.assertj.core.api.Assertions.assertThat;

@ExtendWith(OutputCaptureExtension.class)
class MyOutputCaptureTests {

    @Test
    void testName(CapturedOutput output) {
        System.out.println("Hello World!");
        assertThat(output).contains("World");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.extension.ExtendWith
import org.springframework.boot.test.system.CapturedOutput
import org.springframework.boot.test.system.OutputCaptureExtension

@ExtendWith(OutputCaptureExtension::class)
class MyOutputCaptureTests {

    @Test
    fun testName(output: CapturedOutput?) {
        println("Hello World!")
        assertThat(output).contains("World")
    }

}

9.5.4. TestRestTemplate

TestRestTemplate是 Spring 的便捷替代品RestTemplate这在集成测试中很有用。 你可以获取一个 vanilla 模板或发送 Basic HTTP 身份验证的模板(带有用户名和密码)。 在任一情况下,模板都是容错的。 这意味着它的行为对测试友好,不会在 4xx 和 5xx 错误上引发异常。 相反,可以通过返回的ResponseEntity及其状态代码。spring-doc.cadn.net.cn

Spring Framework 5.0 提供了一个新的WebTestClient适用于 WebFlux 集成测试以及 WebFlux 和 MVC 端到端测试。 它为断言提供了流畅的 API,这与TestRestTemplate.

建议使用 Apache HTTP 客户端(版本 5.1 或更高版本),但并非强制性要求。 如果你的 Classpath 中有它,则TestRestTemplate通过适当配置客户端来响应。 如果您确实使用 Apache 的 HTTP 客户端,则会启用一些其他测试友好功能:spring-doc.cadn.net.cn

TestRestTemplate可以直接在集成测试中实例化,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.http.ResponseEntity;

import static org.assertj.core.api.Assertions.assertThat;

class MyTests {

    private final TestRestTemplate template = new TestRestTemplate();

    @Test
    void testRequest() {
        ResponseEntity<String> headers = this.template.getForEntity("https://myhost.example.com/example", String.class);
        assertThat(headers.getHeaders().getLocation()).hasHost("other.example.com");
    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.boot.test.web.client.TestRestTemplate

class MyTests {

    private val template = TestRestTemplate()

    @Test
    fun testRequest() {
        val headers = template.getForEntity("https://myhost.example.com/example", String::class.java)
        assertThat(headers.headers.location).hasHost("other.example.com")
    }

}

或者,如果您使用@SpringBootTestannotation 替换为WebEnvironment.RANDOM_PORTWebEnvironment.DEFINED_PORT中,您可以注入完全配置的TestRestTemplate并开始使用它。 如有必要,可以通过RestTemplateBuilder豆。 任何未指定主机和端口的 URL 都会自动连接到嵌入式服务器,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.time.Duration;

import org.junit.jupiter.api.Test;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.test.web.client.TestRestTemplate;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.http.HttpHeaders;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MySpringBootTests {

    @Autowired
    private TestRestTemplate template;

    @Test
    void testRequest() {
        HttpHeaders headers = this.template.getForEntity("/example", String.class).getHeaders();
        assertThat(headers.getLocation()).hasHost("other.example.com");
    }

    @TestConfiguration(proxyBeanMethods = false)
    static class RestTemplateBuilderConfiguration {

        @Bean
        RestTemplateBuilder restTemplateBuilder() {
            return new RestTemplateBuilder().setConnectTimeout(Duration.ofSeconds(1))
                .setReadTimeout(Duration.ofSeconds(1));
        }

    }

}
Kotlin
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.boot.test.context.SpringBootTest.WebEnvironment
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.test.web.client.TestRestTemplate
import org.springframework.boot.web.client.RestTemplateBuilder
import org.springframework.context.annotation.Bean
import java.time.Duration

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MySpringBootTests(@Autowired val template: TestRestTemplate) {

    @Test
    fun testRequest() {
        val headers = template.getForEntity("/example", String::class.java).headers
        assertThat(headers.location).hasHost("other.example.com")
    }

    @TestConfiguration(proxyBeanMethods = false)
    internal class RestTemplateBuilderConfiguration {

        @Bean
        fun restTemplateBuilder(): RestTemplateBuilder {
            return RestTemplateBuilder().setConnectTimeout(Duration.ofSeconds(1))
                .setReadTimeout(Duration.ofSeconds(1))
        }

    }

}

10. Docker Compose 支持

Docker Compose 是一种流行的技术,可用于为应用程序所需的服务定义和管理多个容器。 一个compose.yml文件通常在定义和配置服务容器的应用程序旁边创建。spring-doc.cadn.net.cn

Docker Compose 的典型工作流是运行docker compose up,在应用程序连接到已启动的服务的情况下处理应用程序,然后运行docker compose down当你完成时。spring-doc.cadn.net.cn

spring-boot-docker-compose模块可以包含在项目中,以支持使用 Docker Compose 处理容器。 将模块依赖项添加到您的构建中,如以下 Maven 和 Gradle 清单所示:spring-doc.cadn.net.cn

Maven 系列
<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-docker-compose</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>
Gradle
dependencies {
    developmentOnly("org.springframework.boot:spring-boot-docker-compose")
}

当此模块作为依赖项包含在内时, Spring Boot 将执行以下作:spring-doc.cadn.net.cn

如果在启动应用程序时 Docker Compose 服务已经在运行,则 Spring Boot 将仅为每个支持的容器创建服务连接 bean。 它不会调用docker compose up,它不会调用docker compose stop当应用程序关闭时。spring-doc.cadn.net.cn

默认情况下,Spring Boot 的 Docker Compose 支持在运行测试时处于禁用状态。 要启用它,请将spring.docker.compose.skip.in-testsfalse.
默认情况下,重新打包的存档不包含 Spring Boot 的 Docker Compose。 如果您想使用此支持,则需要包含它。 使用 Maven 插件时,将excludeDockerComposeproperty 设置为false. 使用 Gradle 插件时,配置任务的 Classpath 以包含developmentOnly配置.

10.1. 先决条件

您需要具有dockerdocker compose(或docker-compose) CLI 应用程序。 支持的最低 Docker Compose 版本为 2.2.0。spring-doc.cadn.net.cn

10.2. 服务连接

服务连接是与任何远程服务的连接。 Spring Boot 的自动配置可以使用服务连接的详细信息,并使用它们来建立与远程服务的连接。 执行此作时,连接详细信息优先于任何与连接相关的配置属性。spring-doc.cadn.net.cn

当使用 Spring Boot 的 Docker Compose 支持时,将建立与容器映射的端口的服务连接。spring-doc.cadn.net.cn

Docker Compose 的使用方式通常是将容器内的端口映射到计算机上的临时端口。 例如,Postgres 服务器可以使用端口 5432 在容器内运行,但在本地映射到完全不同的端口。 服务连接将始终发现并使用本地映射的端口。

使用容器的映像名称建立服务连接。 目前支持以下服务连接:spring-doc.cadn.net.cn

连接详细信息 匹配时间

CassandraConnectionDetailsspring-doc.cadn.net.cn

名为 “cassandra” 的容器spring-doc.cadn.net.cn

ElasticsearchConnectionDetailsspring-doc.cadn.net.cn

名为 “elasticsearch” 的容器spring-doc.cadn.net.cn

JdbcConnectionDetailsspring-doc.cadn.net.cn

名为 “gvenzl/oracle-xe”、“mariadb”、“mssql/server”、“mysql” 或 “postgres” 的容器spring-doc.cadn.net.cn

MongoConnectionDetailsspring-doc.cadn.net.cn

名为 “mongo” 的容器spring-doc.cadn.net.cn

R2dbcConnectionDetailsspring-doc.cadn.net.cn

名为 “gvenzl/oracle-xe”、“mariadb”、“mssql/server”、“mysql” 或 “postgres” 的容器spring-doc.cadn.net.cn

RabbitConnectionDetailsspring-doc.cadn.net.cn

名为 “rabbitmq” 的容器spring-doc.cadn.net.cn

RedisConnectionDetailsspring-doc.cadn.net.cn

名为 “redis” 的容器spring-doc.cadn.net.cn

ZipkinConnectionDetailsspring-doc.cadn.net.cn

名为 “openzipkin/zipkin” 的容器。spring-doc.cadn.net.cn

10.3. 自定义镜像

有时,您可能需要使用自己的映像版本来提供服务。 您可以使用任何自定义映像,只要其行为方式与标准映像相同即可。 具体而言,标准映像支持的任何环境变量也必须在自定义映像中使用。spring-doc.cadn.net.cn

如果您的图像使用不同的名称,您可以在compose.yml文件,以便 Spring Boot 可以提供服务连接。 使用名为org.springframework.boot.service-connection以提供服务名称。spring-doc.cadn.net.cn

services:
  redis:
    image: 'mycompany/mycustomredis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.service-connection: redis

10.4. 跳过特定容器

如果您在compose.yml,则不希望连接到您的应用程序,则可以使用标签来忽略它。 任何标有org.springframework.boot.ignore将被 Spring Boot 忽略。spring-doc.cadn.net.cn

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.ignore: true

10.5. 使用特定的 Compose 文件

如果您的 compose 文件与应用程序不在同一目录中,或者名称不同,则可以使用spring.docker.compose.fileapplication.propertiesapplication.yaml以指向其他文件。 属性可以定义为精确路径或相对于应用程序的路径。spring-doc.cadn.net.cn

性能
spring.docker.compose.file=../my-compose.yml
Yaml
spring:
  docker:
    compose:
      file: "../my-compose.yml"

10.6. 等待容器就绪

由 Docker Compose 启动的容器可能需要一些时间才能完全准备就绪。 检查就绪情况的推荐方法是添加healthcheck部分compose.yml文件。spring-doc.cadn.net.cn

由于这种情况并不少见healthcheck要省略的配置compose.yml文件,Spring Boot 还会直接检查服务就绪情况。 默认情况下,当可以与容器的映射端口建立 TCP/IP 连接时,容器被视为准备就绪。spring-doc.cadn.net.cn

您可以通过添加org.springframework.boot.readiness-check.tcp.disable标签中的compose.yml文件。spring-doc.cadn.net.cn

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.readiness-check.tcp.disable: true

您还可以在application.propertiesapplication.yaml文件:spring-doc.cadn.net.cn

性能
spring.docker.compose.readiness.tcp.connect-timeout=10s
spring.docker.compose.readiness.tcp.read-timeout=5s
Yaml
spring:
  docker:
    compose:
      readiness:
        tcp:
          connect-timeout: 10s
          read-timeout: 5s

总超时可以使用spring.docker.compose.readiness.timeout.spring-doc.cadn.net.cn

10.7. 控制 Docker Compose 生命周期

默认情况下,Spring Boot 调用docker compose up当您的应用程序启动时,以及docker compose stop当它关闭时。 如果您希望使用不同的生命周期管理,可以使用spring.docker.compose.lifecycle-management财产。spring-doc.cadn.net.cn

支持以下值:spring-doc.cadn.net.cn

此外,您还可以使用spring.docker.compose.start.command属性来更改docker compose updocker compose start被使用。 这spring.docker.compose.stop.command允许您配置 ifdocker compose downdocker compose stop被使用。spring-doc.cadn.net.cn

以下示例显示了如何配置生命周期管理:spring-doc.cadn.net.cn

性能
spring.docker.compose.lifecycle-management=start-and-stop
spring.docker.compose.start.command=start
spring.docker.compose.stop.command=down
spring.docker.compose.stop.timeout=1m
Yaml
spring:
  docker:
    compose:
      lifecycle-management: start-and-stop
      start:
        command: start
      stop:
        command: down
        timeout: 1m

10.8. 激活 Docker Compose 配置文件

Docker Compose 配置文件与 Spring 配置文件类似,因为它们允许您针对特定环境调整 Docker Compose 配置。 如果要激活特定的 Docker Compose 配置文件,可以使用spring.docker.compose.profiles.active属性包含在application.propertiesapplication.yaml文件:spring-doc.cadn.net.cn

性能
spring.docker.compose.profiles.active=myprofile
Yaml
spring:
  docker:
    compose:
      profiles:
        active: "myprofile"

11. Testcontainers 支持

除了使用 Testcontainers 进行集成测试外,还可以在开发时使用它们。 接下来的部分将提供有关这方面的更多详细信息。spring-doc.cadn.net.cn

11.1. 在开发时使用 Testcontainers

这种方法允许开发人员为应用程序所依赖的服务快速启动容器,无需手动预置数据库服务器等内容。 以这种方式使用 Testcontainers 可提供类似于 Docker Compose 的功能,但您的容器配置是 Java 而不是 YAML。spring-doc.cadn.net.cn

要在开发时使用 Testcontainers,您需要使用 “test” classpath 而不是 “main” 来启动应用程序。 这将允许您访问所有声明的测试依赖项,并为您提供一个自然的位置来编写测试配置。spring-doc.cadn.net.cn

要创建应用程序的测试可启动版本,您应该在src/test目录。 例如,如果您的主应用程序位于src/main/java/com/example/MyApplication.java,您应该创建src/test/java/com/example/TestMyApplication.javaspring-doc.cadn.net.cn

TestMyApplication类可以使用SpringApplication.from(…​)启动真实应用程序的方法:spring-doc.cadn.net.cn

Java
import org.springframework.boot.SpringApplication;

public class TestMyApplication {

    public static void main(String[] args) {
        SpringApplication.from(MyApplication::main).run(args);
    }

}
Kotlin
import org.springframework.boot.fromApplication

fun main(args: Array<String>) {
    fromApplication<MyApplication>().run(*args)
}

您还需要定义Container要与应用程序一起启动的实例。 为此,您需要确保spring-boot-testcontainersmodule 已添加为testDependency。 完成后,您可以创建一个@TestConfiguration类,该类声明@Bean方法。spring-doc.cadn.net.cn

您还可以注释@Bean方法与@ServiceConnection为了创建ConnectionDetails豆。 有关支持的技术的详细信息,请参阅服务连接部分。spring-doc.cadn.net.cn

典型的 Testcontainers 配置如下所示:spring-doc.cadn.net.cn

Java
import org.testcontainers.containers.Neo4jContainer;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;

@TestConfiguration(proxyBeanMethods = false)
public class MyContainersConfiguration {

    @Bean
    @ServiceConnection
    public Neo4jContainer<?> neo4jContainer() {
        return new Neo4jContainer<>("neo4j:5");
    }

}
Kotlin
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.springframework.context.annotation.Bean
import org.testcontainers.containers.Neo4jContainer

@TestConfiguration(proxyBeanMethods = false)
class MyContainersConfiguration {

    @Bean
    @ServiceConnection
    fun neo4jContainer(): Neo4jContainer<*> {
        return Neo4jContainer("neo4j:5")
    }

}
的生命周期Containerbean 由 Spring Boot 自动管理。 容器将自动启动和停止。

定义测试配置后,您可以使用with(…​)将其附加到测试Starters的方法:spring-doc.cadn.net.cn

Java
import org.springframework.boot.SpringApplication;

public class TestMyApplication {

    public static void main(String[] args) {
        SpringApplication.from(MyApplication::main).with(MyContainersConfiguration.class).run(args);
    }

}
Kotlin
import org.springframework.boot.fromApplication
import org.springframework.boot.with

fun main(args: Array<String>) {
    fromApplication<MyApplication>().with(MyContainersConfiguration::class).run(*args)
}

您现在可以启动TestMyApplication就像你对待任何常规 Java 一样mainmethod application 启动您的应用程序及其需要运行的容器。spring-doc.cadn.net.cn

您可以使用 Maven 目标spring-boot:test-run或 Gradle 任务bootTestRun以从命令行执行此作。

11.1.1. 在开发时贡献动态属性

如果您想在开发时从Container @Bean方法,您可以通过注入DynamicPropertyRegistry. 其工作方式与@DynamicPropertySource注解,您可以在测试中使用。 它允许您添加在容器启动后将变为可用的属性。spring-doc.cadn.net.cn

典型的配置如下所示:spring-doc.cadn.net.cn

Java
import org.testcontainers.containers.MongoDBContainer;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.test.context.DynamicPropertyRegistry;

@TestConfiguration(proxyBeanMethods = false)
public class MyContainersConfiguration {

    @Bean
    public MongoDBContainer mongoDbContainer(DynamicPropertyRegistry properties) {
        MongoDBContainer container = new MongoDBContainer("mongo:5.0");
        properties.add("spring.data.mongodb.host", container::getHost);
        properties.add("spring.data.mongodb.port", container::getFirstMappedPort);
        return container;
    }

}
Kotlin
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.context.annotation.Bean
import org.springframework.test.context.DynamicPropertyRegistry
import org.testcontainers.containers.MongoDBContainer

@TestConfiguration(proxyBeanMethods = false)
class MyContainersConfiguration {

    @Bean
    fun monogDbContainer(properties: DynamicPropertyRegistry): MongoDBContainer {
        var container = MongoDBContainer("mongo:5.0")
        properties.add("spring.data.mongodb.host", container::getHost)
        properties.add("spring.data.mongodb.port", container::getFirstMappedPort)
        return container
    }

}
使用@ServiceConnection,但是,对于尚无@ServiceConnection支持。

11.1.2. 导入 Testcontainer 声明类

使用 Testcontainers 时的一个常见模式是声明Container实例作为静态字段。 通常,这些字段直接在 test 类上定义。 它们也可以在父类或测试实现的接口上声明。spring-doc.cadn.net.cn

例如,以下MyContainersinterface 声明mongoneo4j器皿:spring-doc.cadn.net.cn

import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.containers.Neo4jContainer;
import org.testcontainers.junit.jupiter.Container;

import org.springframework.boot.testcontainers.service.connection.ServiceConnection;

public interface MyContainers {

    @Container
    @ServiceConnection
    MongoDBContainer mongoContainer = new MongoDBContainer("mongo:5.0");

    @Container
    @ServiceConnection
    Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:5");

}

如果你已经以这种方式定义了容器,或者你只是喜欢这种样式,你可以导入这些声明类,而不是将容器定义为@Bean方法。 为此,请添加@ImportTestcontainers注解添加到测试配置类中:spring-doc.cadn.net.cn

Java
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.context.ImportTestcontainers;

@TestConfiguration(proxyBeanMethods = false)
@ImportTestcontainers(MyContainers.class)
public class MyContainersConfiguration {

}
Kotlin
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.context.ImportTestcontainers

@TestConfiguration(proxyBeanMethods = false)
@ImportTestcontainers(MyContainers::class)
class MyContainersConfiguration
如果您不打算使用服务连接功能,但想要使用@DynamicPropertySource相反,请删除@ServiceConnection注解Container领域。 您还可以添加@DynamicPropertySourceannotated 方法添加到 Declaration 类中。

11.1.3. 在开发时将 DevTools 与 Testcontainers 一起使用

使用 devtools 时,您可以使用@RestartScope. 当 devtools 重新启动应用程序时,不会重新创建此类 bean。 这对于 Testcontainer 特别有用Containerbean,因为尽管应用程序重新启动,它们仍保持其状态。spring-doc.cadn.net.cn

Java
import org.testcontainers.containers.MongoDBContainer;

import org.springframework.boot.devtools.restart.RestartScope;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;

@TestConfiguration(proxyBeanMethods = false)
public class MyContainersConfiguration {

    @Bean
    @RestartScope
    @ServiceConnection
    public MongoDBContainer mongoDbContainer() {
        return new MongoDBContainer("mongo:5.0");
    }

}
Kotlin
import org.springframework.boot.devtools.restart.RestartScope
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.springframework.context.annotation.Bean
import org.testcontainers.containers.MongoDBContainer

@TestConfiguration(proxyBeanMethods = false)
class MyContainersConfiguration {

    @Bean
    @RestartScope
    @ServiceConnection
    fun monogDbContainer(): MongoDBContainer {
        return MongoDBContainer("mongo:5.0")
    }

}
如果你正在使用 Gradle 并希望使用此功能,则需要更改spring-boot-devtoolsdependency from (依赖项)developmentOnlytestImplementation. 默认范围developmentOnlybootTestRuntask 不会获取代码中的更改,因为 DevTools 未处于活动状态。

12. 创建您自己的自动配置

如果您在开发共享库的公司工作,或者如果您从事开源或商业库的工作,则可能需要开发自己的自动配置。 自动配置类可以捆绑在外部 jar 中,并且仍然由 Spring Boot 拾取。spring-doc.cadn.net.cn

Auto-configuration 可以与 “starter” 相关联,该 “starter” 提供 auto-configuration 代码以及您将与之一起使用的典型 libraries。 我们首先介绍构建自己的自动配置所需了解的内容,然后我们继续介绍创建自定义Starters所需的典型步骤spring-doc.cadn.net.cn

12.1. 了解自动配置的 bean

实现自动配置的类用@AutoConfiguration. 此注解本身使用@Configuration,使自动配置成为标准@Configuration类。 附加@Conditional注释用于限制何时应应用自动配置。 通常,自动配置类使用@ConditionalOnClass@ConditionalOnMissingBean附注。 这可确保仅在找到相关类且您尚未声明自己的类时应用自动配置@Configuration.spring-doc.cadn.net.cn

您可以浏览spring-boot-autoconfigure以查看@AutoConfiguration类(请参阅 Spring 提供的META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件)。spring-doc.cadn.net.cn

12.2. 查找 Auto-configuration Candidate

Spring Boot 检查是否存在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports文件。 该文件应列出您的配置类,每行一个类名,如以下示例所示:spring-doc.cadn.net.cn

com.mycorp.libx.autoconfigure.LibXAutoConfiguration
com.mycorp.libx.autoconfigure.LibXWebAutoConfiguration
您可以使用该字符向 imports 文件添加注释。#
自动配置只能通过在 imports 文件中命名来加载。 确保它们在特定的包空间中定义,并且它们永远不会成为组件扫描的目标。 此外,自动配置类不应启用组件扫描来查找其他组件。 特定@Import应改用 annotations。

如果您的配置需要按特定顺序应用,您可以使用before,beforeName,afterafterNameattributes 上的@AutoConfiguration注解或专用的@AutoConfigureBefore@AutoConfigureAfter附注。 例如,如果您提供特定于 Web 的配置,则可能需要在WebMvcAutoConfiguration.spring-doc.cadn.net.cn

如果您想订购某些不应直接了解彼此的自动配置,您还可以使用@AutoConfigureOrder. 该注解与常规@Order注解,但为自动配置类提供专用顺序。spring-doc.cadn.net.cn

与标准一样@Configuration类,则应用自动配置类的顺序仅影响其 bean 的定义顺序。 随后创建这些 bean 的顺序不受影响,并且由每个 bean 的依赖项和任何@DependsOn关系。spring-doc.cadn.net.cn

12.3. 条件注解

您几乎总是希望包含一个或多个@Conditionalannotations 的 auto-configuration 类。 这@ConditionalOnMissingBeanannotation 是一个常见的示例,用于允许开发人员在对您的默认值不满意时覆盖自动配置。spring-doc.cadn.net.cn

Spring Boot 包括许多@Conditional注解,您可以通过注解@Configuration类或个人@Bean方法。 这些注释包括:spring-doc.cadn.net.cn

12.3.1. 类条件

@ConditionalOnClass@ConditionalOnMissingClassannotations 让@Configuration根据特定类的存在与否来包含类。 由于注释元数据是使用 ASM 解析的,因此您可以使用value属性来引用实际类,即使该类实际上可能没有出现在正在运行的应用程序类路径上。 您还可以使用name属性(如果您希望使用String价值。spring-doc.cadn.net.cn

此机制不会以相同的方式应用于@Bean方法,其中返回类型通常是条件的目标:在方法的条件应用之前,JVM 将加载类和可能处理的方法引用,如果类不存在,则这些引用将失败。spring-doc.cadn.net.cn

为了处理这种情况,单独的@Configurationclass 可用于隔离条件,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@AutoConfiguration
// Some conditions ...
public class MyAutoConfiguration {

    // Auto-configured beans ...

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(SomeService.class)
    public static class SomeServiceConfiguration {

        @Bean
        @ConditionalOnMissingBean
        public SomeService someService() {
            return new SomeService();
        }

    }

}
Kotlin
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
// Some conditions ...
class MyAutoConfiguration {

    // Auto-configured beans ...
    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(SomeService::class)
    class SomeServiceConfiguration {

        @Bean
        @ConditionalOnMissingBean
        fun someService(): SomeService {
            return SomeService()
        }

    }

}
如果您使用@ConditionalOnClass@ConditionalOnMissingClass作为元注释的一部分来编写您自己的组合注释,您必须使用name,因为在这种情况下引用类不会被处理。

12.3.2. Bean 条件

@ConditionalOnBean@ConditionalOnMissingBean注释允许根据特定 bean 的存在与否来包含 bean。 您可以使用value属性按类型指定 bean,或者name按 name 指定 bean。 这search属性允许您限制ApplicationContext搜索 bean 时应考虑的层次结构。spring-doc.cadn.net.cn

当放置在@Beanmethod,则 target 类型默认为方法的返回类型,如以下示例所示:spring-doc.cadn.net.cn

Java
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
public class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public SomeService someService() {
        return new SomeService();
    }

}
Kotlin
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration(proxyBeanMethods = false)
class MyAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    fun someService(): SomeService {
        return SomeService()
    }

}

在前面的示例中,someService如果没有SomeService已包含在ApplicationContext.spring-doc.cadn.net.cn

您需要非常小心 bean 定义的添加顺序,因为这些条件是根据到目前为止已处理的内容进行评估的。 因此,我们建议仅使用@ConditionalOnBean@ConditionalOnMissingBean自动配置类上的注释(因为这些保证在添加任何用户定义的 bean 定义后加载)。
@ConditionalOnBean@ConditionalOnMissingBean不要阻止@Configuration类。 在类级别使用这些条件与将每个条件标记为包含@Bean方法的 Intent 是,前者会阻止注册@Configurationclass 作为 Bean 进行设置。
当声明@Bean方法,请在方法的 return 类型中提供尽可能多的类型信息。 例如,如果 Bean 的具体类实现了一个接口,则 Bean 方法的返回类型应该是具体类,而不是接口。 在@Bean方法在使用 bean 条件时尤其重要,因为它们的评估只能依赖于方法签名中可用的类型信息。

12.3.3. 属性条件

@ConditionalOnPropertyannotation 允许根据 Spring Environment 属性包含配置。 使用prefixnameattributes 来指定应检查的属性。 默认情况下,任何存在且不等于false匹配。 您还可以使用havingValuematchIfMissing属性。spring-doc.cadn.net.cn

如果在name属性,则所有属性都必须通过测试才能匹配条件。spring-doc.cadn.net.cn

12.3.4. 资源条件

@ConditionalOnResourceannotation 允许仅在存在特定资源时包含 configuration。 可以使用通常的 Spring 约定来指定资源,如以下示例所示:file:/home/user/test.dat.spring-doc.cadn.net.cn

12.3.5. Web 应用程序条件

@ConditionalOnWebApplication@ConditionalOnNotWebApplication注释允许根据应用程序是否为 Web 应用程序来包含配置。 基于 servlet 的 Web 应用程序是使用 Spring 的任何应用程序WebApplicationContext,定义session范围,或者具有ConfigurableWebEnvironment. 反应式 Web 应用程序是使用ReactiveWebApplicationContext或具有ConfigurableReactiveWebEnvironment.spring-doc.cadn.net.cn

@ConditionalOnWarDeployment@ConditionalOnNotWarDeployment注释允许根据应用程序是否是部署到 servlet 容器的传统 WAR 应用程序来包含配置。 对于使用嵌入式 Web 服务器运行的应用程序,此条件将不匹配。spring-doc.cadn.net.cn

12.3.6. SPEL 表达式条件

@ConditionalOnExpressionannotation 允许根据 SPEL 表达式的结果包含配置。spring-doc.cadn.net.cn

在表达式中引用 bean 将导致该 bean 在上下文刷新处理中非常早地初始化。 因此,bean 将不符合后处理条件(例如配置属性绑定),并且其状态可能不完整。

12.4. 测试您的 Auto-configuration

自动配置可能受多种因素影响:用户配置 (@Bean定义和Environment自定义)、条件评估(存在特定库)等。 具体来说,每个测试都应该创建一个定义明确的ApplicationContext,这表示这些自定义项的组合。ApplicationContextRunner提供了实现此目的的好方法。spring-doc.cadn.net.cn

ApplicationContextRunner在本机映像中运行测试时不起作用。

ApplicationContextRunner通常定义为 Test 类的字段,用于收集基本、通用的配置。 以下示例确保MyServiceAutoConfiguration始终调用:spring-doc.cadn.net.cn

Java
private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
    .withConfiguration(AutoConfigurations.of(MyServiceAutoConfiguration.class));
Kotlin
val contextRunner = ApplicationContextRunner()
    .withConfiguration(AutoConfigurations.of(MyServiceAutoConfiguration::class.java))
如果必须定义多个 auto-configurations,则无需对它们的声明进行排序,因为它们的调用顺序与运行应用程序时的顺序完全相同。

每个测试都可以使用运行程序来表示特定的使用案例。 例如,下面的示例调用用户配置 (UserConfiguration) 并检查自动配置是否正确退出。 调用run提供可与AssertJ.spring-doc.cadn.net.cn

Java
@Test
void defaultServiceBacksOff() {
    this.contextRunner.withUserConfiguration(UserConfiguration.class).run((context) -> {
        assertThat(context).hasSingleBean(MyService.class);
        assertThat(context).getBean("myCustomService").isSameAs(context.getBean(MyService.class));
    });
}

@Configuration(proxyBeanMethods = false)
static class UserConfiguration {

    @Bean
    MyService myCustomService() {
        return new MyService("mine");
    }

}
Kotlin
@Test
fun defaultServiceBacksOff() {
    contextRunner.withUserConfiguration(UserConfiguration::class.java)
        .run { context: AssertableApplicationContext ->
            assertThat(context).hasSingleBean(MyService::class.java)
            assertThat(context).getBean("myCustomService")
                .isSameAs(context.getBean(MyService::class.java))
        }
}

@Configuration(proxyBeanMethods = false)
internal class UserConfiguration {

    @Bean
    fun myCustomService(): MyService {
        return MyService("mine")
    }

}

还可以轻松自定义Environment,如以下示例所示:spring-doc.cadn.net.cn

Java
@Test
void serviceNameCanBeConfigured() {
    this.contextRunner.withPropertyValues("user.name=test123").run((context) -> {
        assertThat(context).hasSingleBean(MyService.class);
        assertThat(context.getBean(MyService.class).getName()).isEqualTo("test123");
    });
}
Kotlin
@Test
fun serviceNameCanBeConfigured() {
    contextRunner.withPropertyValues("user.name=test123").run { context: AssertableApplicationContext ->
        assertThat(context).hasSingleBean(MyService::class.java)
        assertThat(context.getBean(MyService::class.java).name).isEqualTo("test123")
    }
}

运行器还可用于显示ConditionEvaluationReport. 该报告可以在INFODEBUG水平。 以下示例演示如何使用ConditionEvaluationReportLoggingListener以在 Auto-Configuration Tests 中打印报告。spring-doc.cadn.net.cn

Java
import org.junit.jupiter.api.Test;

import org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener;
import org.springframework.boot.logging.LogLevel;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;

class MyConditionEvaluationReportingTests {

    @Test
    void autoConfigTest() {
        new ApplicationContextRunner()
            .withInitializer(ConditionEvaluationReportLoggingListener.forLogLevel(LogLevel.INFO))
            .run((context) -> {
                // Test something...
            });
    }

}
Kotlin
import org.junit.jupiter.api.Test
import org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportLoggingListener
import org.springframework.boot.logging.LogLevel
import org.springframework.boot.test.context.assertj.AssertableApplicationContext
import org.springframework.boot.test.context.runner.ApplicationContextRunner

class MyConditionEvaluationReportingTests {

    @Test
    fun autoConfigTest() {
        ApplicationContextRunner()
            .withInitializer(ConditionEvaluationReportLoggingListener.forLogLevel(LogLevel.INFO))
            .run { context: AssertableApplicationContext? -> }
    }

}

12.4.1. 模拟 Web 上下文

如果需要测试仅在 servlet 或反应式 Web 应用程序上下文中运行的自动配置,请使用WebApplicationContextRunnerReactiveWebApplicationContextRunner分别。spring-doc.cadn.net.cn

12.4.2. 覆盖 Classpath

还可以测试当特定类和/或包在运行时不存在时会发生什么。 Spring Boot 附带一个FilteredClassLoader这很容易被 runner 使用。 在下面的示例中,我们断言如果MyService不存在,则会自动配置已正确禁用:spring-doc.cadn.net.cn

Java
@Test
void serviceIsIgnoredIfLibraryIsNotPresent() {
    this.contextRunner.withClassLoader(new FilteredClassLoader(MyService.class))
        .run((context) -> assertThat(context).doesNotHaveBean("myService"));
}
Kotlin
@Test
fun serviceIsIgnoredIfLibraryIsNotPresent() {
    contextRunner.withClassLoader(FilteredClassLoader(MyService::class.java))
        .run { context: AssertableApplicationContext? ->
            assertThat(context).doesNotHaveBean("myService")
        }
}

12.5. 创建您自己的 Starter

典型的 Spring Boot Starters包含用于自动配置和自定义给定技术基础设施的代码,我们称之为 “acme”。 为了使其易于扩展,可以将专用命名空间中的许多 Configuration Key 公开给环境。 最后,提供了一个 “starter” 依赖项,以帮助用户尽可能轻松地入门。spring-doc.cadn.net.cn

具体来说,自定义Starters可以包含以下内容:spring-doc.cadn.net.cn

  • autoconfigure模块,其中包含 “acme” 的自动配置代码。spring-doc.cadn.net.cn

  • starter模块,该模块为autoconfiguremodule 以及 “acme” 和任何其他通常有用的依赖项。 简而言之,添加 starter 应该提供开始使用该库所需的一切。spring-doc.cadn.net.cn

这种分为两个模块的做法是完全没有必要的。 如果 “acme” 有多种风格、选项或可选功能,那么最好将自动配置分开,因为您可以清楚地表达某些功能是可选的。 此外,您还可以制作一个 starter 来提供有关这些可选依赖项的意见。 同时,其他人只能依靠autoconfigure模块并制作他们自己的具有不同观点的Starters。spring-doc.cadn.net.cn

如果自动配置相对简单且没有可选功能,那么在 starter 中合并两个模块绝对是一种选择。spring-doc.cadn.net.cn

12.5.1. 命名

您应该确保为 starter 提供适当的命名空间。 不要以模块名称开头spring-boot,即使您使用不同的 MavengroupId. 将来,我们可能会为您自动配置的事物提供官方支持。spring-doc.cadn.net.cn

根据经验,您应该在 starter 之后命名组合模块。 例如,假设您正在为 “acme” 创建一个Starters,并将 auto-configure 模块命名为acme-spring-boot和Startersacme-spring-boot-starter. 如果您只有一个模块将两者组合在一起,请为其命名acme-spring-boot-starter.spring-doc.cadn.net.cn

12.5.2. 配置键

如果您的 starter 提供 Configuration Key,请为它们使用唯一的命名空间。 特别是,不要在 Spring Boot 使用的名称空间中包含你的键(例如server,management,spring等)。 如果你使用相同的命名空间,我们将来可能会以破坏你的模块的方式修改这些命名空间。 根据经验,请在所有键前面加上您拥有的命名空间(例如acme).spring-doc.cadn.net.cn

通过为每个属性添加字段 javadoc 来确保记录配置键,如以下示例所示:spring-doc.cadn.net.cn

Java
import java.time.Duration;

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

@ConfigurationProperties("acme")
public class AcmeProperties {

    /**
     * Whether to check the location of acme resources.
     */
    private boolean checkLocation = true;

    /**
     * Timeout for establishing a connection to the acme server.
     */
    private Duration loginTimeout = Duration.ofSeconds(3);

    // getters/setters ...

    public boolean isCheckLocation() {
        return this.checkLocation;
    }

    public void setCheckLocation(boolean checkLocation) {
        this.checkLocation = checkLocation;
    }

    public Duration getLoginTimeout() {
        return this.loginTimeout;
    }

    public void setLoginTimeout(Duration loginTimeout) {
        this.loginTimeout = loginTimeout;
    }

}
Kotlin
import org.springframework.boot.context.properties.ConfigurationProperties
import java.time.Duration

@ConfigurationProperties("acme")
class AcmeProperties(

    /**
     * Whether to check the location of acme resources.
     */
    var isCheckLocation: Boolean = true,

    /**
     * Timeout for establishing a connection to the acme server.
     */
    var loginTimeout:Duration = Duration.ofSeconds(3))
您应该只使用@ConfigurationProperties字段 Javadoc,因为它们在添加到 JSON 之前不会进行处理。

以下是我们在内部遵循的一些规则,以确保描述一致:spring-doc.cadn.net.cn

确保触发元数据生成,以便 IDE 帮助也可用于您的密钥。 您可能需要查看生成的元数据 (META-INF/spring-configuration-metadata.json) 以确保您的密钥已正确记录。 在兼容的 IDE 中使用您自己的 starter 也是验证元数据质量的好主意。spring-doc.cadn.net.cn

12.5.3. “autoconfigure” 模块

autoconfiguremodule 包含开始使用该库所需的一切。 它还可能包含配置键定义(例如@ConfigurationProperties) 以及可用于进一步自定义组件初始化方式的任何回调接口。spring-doc.cadn.net.cn

您应该将库的依赖项标记为可选,以便您可以包含autoconfigure模块。 如果这样做,则不会提供库,并且默认情况下, Spring Boot 会退缩。

Spring Boot 使用注释处理器在元数据文件(META-INF/spring-autoconfigure-metadata.properties). 如果存在该文件,则使用它来紧急过滤不匹配的自动配置,这将缩短启动时间。spring-doc.cadn.net.cn

使用 Maven 构建时,建议在包含 auto-configurations 的模块中添加以下依赖项:spring-doc.cadn.net.cn

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

如果您直接在应用程序中定义了自动配置,请确保配置spring-boot-maven-plugin以防止repackage目标:spring-doc.cadn.net.cn

<project>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.springframework.boot</groupId>
                            <artifactId>spring-boot-autoconfigure-processor</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

使用 Gradle 时,应在annotationProcessor配置,如以下示例所示:spring-doc.cadn.net.cn

dependencies {
    annotationProcessor "org.springframework.boot:spring-boot-autoconfigure-processor"
}

12.5.4. Starter 模块

Starters真的是一个空罐子。 它的唯一目的是提供使用库所需的依赖项。 您可以将其视为对开始所需内容的固执己见的看法。spring-doc.cadn.net.cn

不要对添加起始项的项目做出假设。 如果要自动配置的库通常需要其他启动程序,请同时提及它们。 如果可选依赖项的数量很高,则可能很难提供一组适当的默认依赖项,因为您应该避免包含对于库的典型使用不必要的依赖项。 换句话说,您不应包含可选依赖项。spring-doc.cadn.net.cn

无论哪种方式,您的Starters都必须引用核心 Spring Boot Starters(spring-boot-starter) (如果您的 starter 依赖于另一个 starter,则无需添加它)。 如果项目是仅使用您的自定义Starters创建的,则 Spring Boot 的核心功能将因核心Starters的存在而得到尊重。

13. Kotlin 支持

Kotlin 是一种面向 JVM(和其他平台)的静态类型语言,它允许编写简洁优雅的代码,同时提供与用 Java 编写的现有库的互作性spring-doc.cadn.net.cn

Spring Boot 通过利用其他 Spring 项目(如 Spring Framework、Spring Data 和 Reactor)中的支持来提供 Kotlin 支持。 有关更多信息,请参阅 Spring Framework Kotlin 支持文档spring-doc.cadn.net.cn

开始使用 Spring Boot 和 Kotlin 的最简单方法是遵循此综合教程。 您可以使用 start.spring.io 创建新的 Kotlin 项目。 请随时加入 Kotlin Slack 的 #spring 频道,或使用springkotlin标签(如果您需要支持)。spring-doc.cadn.net.cn

13.1. 要求

Spring Boot 至少需要 Kotlin 1.7.x,并通过依赖项管理管理合适的 Kotlin 版本。 要使用 Kotlin,org.jetbrains.kotlin:kotlin-stdliborg.jetbrains.kotlin:kotlin-reflect必须存在于 Classpath 中。 这kotlin-stdlib变种kotlin-stdlib-jdk7kotlin-stdlib-jdk8也可以使用。spring-doc.cadn.net.cn

由于 Kotlin 类默认是 final,因此您可能希望配置 kotlin-spring 插件,以便自动打开 Spring 注释的类,以便可以代理它们。spring-doc.cadn.net.cn

在 Kotlin 中序列化/反序列化 JSON 数据需要 Jackson 的 Kotlin 模块。 在 Classpath 上找到它时,它会自动注册。 如果存在 Jackson 和 Kotlin,但不存在 Jackson Kotlin 模块,则会记录一条警告消息。spring-doc.cadn.net.cn

如果在 start.spring.io 上引导 Kotlin 项目,则默认提供这些依赖项和插件。

13.2. 空安全

Kotlin 的主要功能之一是 null 安全。 它涉及null值,而不是将问题推迟到运行时并遇到NullPointerException. 这有助于消除常见的错误来源,而无需支付包装器的成本,例如Optional. Kotlin 还允许使用具有可为 null 值的函数结构,如本 Kotlin 中的 null 安全性综合指南中所述。spring-doc.cadn.net.cn

尽管 Java 不允许在其类型系统中表达 null 安全性,但 Spring Framework、Spring Data 和 Reactor 现在通过工具友好的注释提供其 API 的 null 安全性。 默认情况下,Kotlin 中使用的 Java API 中的类型被识别为放宽了 null 检查的平台类型Kotlin 对 JSR 305 注释的支持与可为 null 性注释相结合,为 Kotlin 中的相关 Spring API 提供了空安全性。spring-doc.cadn.net.cn

JSR 305 检查可以通过添加-Xjsr305compiler 标志替换为以下选项:-Xjsr305={strict|warn|ignore}. 默认行为与-Xjsr305=warn. 这strictvalue 需要在从 Spring API 推断的 Kotlin 类型中考虑 null-safety ,但应该知道 Spring API 可空性声明甚至在次要版本之间也可能演变,并且将来可能会添加更多检查)。spring-doc.cadn.net.cn

尚不支持泛型类型参数、varargs 和数组元素可为 null 性。 有关最新信息,请参阅 SPR-15942。 另请注意,Spring Boot 自己的 API 尚未注释

13.3. Kotlin API

13.3.1. runApplication

Spring Boot 提供了一种惯用的方式来运行应用程序runApplication<MyApplication>(*args)如以下示例所示:spring-doc.cadn.net.cn

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class MyApplication

fun main(args: Array<String>) {
    runApplication<MyApplication>(*args)
}

这是SpringApplication.run(MyApplication::class.java, *args). 它还允许自定义应用程序,如以下示例所示:spring-doc.cadn.net.cn

runApplication<MyApplication>(*args) {
    setBannerMode(OFF)
}

13.3.2. 扩展

Kotlin 扩展提供了使用其他功能扩展现有类的功能。 Spring Boot Kotlin API 利用这些扩展为现有 API 添加新的 Kotlin 特定便利。spring-doc.cadn.net.cn

TestRestTemplate扩展,类似于 Spring Framework 为RestOperations在 Spring Framework 中。 此外,这些扩展还可以利用 Kotlin 具体化类型参数。spring-doc.cadn.net.cn

13.4. 依赖项管理

为了避免在 Classpath 上混合不同版本的 Kotlin 依赖项, Spring Boot 导入了 Kotlin BOM。spring-doc.cadn.net.cn

使用 Maven 时,可以通过设置kotlin.version属性和插件管理kotlin-maven-plugin. 使用 Gradle 时,Spring Boot 插件会自动将kotlin.version替换为 Kotlin 插件的版本。spring-doc.cadn.net.cn

Spring Boot 还通过导入 Kotlin Coroutines BOM 来管理 Coroutines 依赖项的版本。 可以通过设置kotlin-coroutines.version财产。spring-doc.cadn.net.cn

org.jetbrains.kotlinx:kotlinx-coroutines-reactor如果引导 Kotlin 项目时至少有一个对 start.spring.io 的反应式依赖项,则默认提供依赖项。

13.5. @ConfigurationProperties

@ConfigurationProperties当与构造函数结合使用时,Binding 支持具有 Immutable 的类val属性,如以下示例所示:spring-doc.cadn.net.cn

@ConfigurationProperties("example.kotlin")
data class KotlinExampleProperties(
        val name: String,
        val description: String,
        val myService: MyService) {

    data class MyService(
            val apiToken: String,
            val uri: URI
    )
}
要使用注释处理器生成您自己的元数据kapt应配置使用spring-boot-configuration-processorDependency。 请注意,由于 kapt 提供的模型的限制,某些功能(例如检测默认值或已弃用的项目)无法正常工作。

13.6. 测试

虽然可以使用 JUnit 4 来测试 Kotlin 代码,但 JUnit 5 是默认提供的,建议使用 JUnit 5。 JUnit 5 允许测试类实例化一次,并重复用于该类的所有测试。 这使得使用@BeforeAll@AfterAll非静态方法的注解,非常适合 Kotlin。spring-doc.cadn.net.cn

要模拟 Kotlin 类,建议使用 MockK。 如果您需要MockK相当于 Mockito 特定的@MockBean@SpyBean附注,你可以使用 SpringMockK,它提供类似的@MockkBean@SpykBean附注。spring-doc.cadn.net.cn

14. SSL认证

Spring Boot 提供了配置 SSL 信任材料的能力,该材料可以应用于多种类型的连接,以支持安全通信。 带有前缀的 Configuration 属性spring.ssl.bundle可用于指定命名的信任材料集和相关信息。spring-doc.cadn.net.cn

14.1. 使用 Java KeyStore 文件配置 SSL

带有前缀的 Configuration 属性spring.ssl.bundle.jks可用于配置使用 Java 创建的信任材料包keytool实用程序,并以 JKS 或 PKCS12 格式存储在 Java KeyStore 文件中。 每个捆绑包都有一个用户提供的名称,可用于引用捆绑包。spring-doc.cadn.net.cn

当用于保护嵌入式 Web 服务器时,keystore通常配置包含证书和私钥的 Java KeyStore,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.ssl.bundle.jks.mybundle.key.alias=application
spring.ssl.bundle.jks.mybundle.keystore.location=classpath:application.p12
spring.ssl.bundle.jks.mybundle.keystore.password=secret
spring.ssl.bundle.jks.mybundle.keystore.type=PKCS12
Yaml
spring:
  ssl:
    bundle:
      jks:
        mybundle:
          key:
            alias: "application"
          keystore:
            location: "classpath:application.p12"
            password: "secret"
            type: "PKCS12"

当用于保护客户端连接时,一个truststore通常配置包含服务器证书的 Java KeyStore,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.ssl.bundle.jks.mybundle.truststore.location=classpath:server.p12
spring.ssl.bundle.jks.mybundle.truststore.password=secret
Yaml
spring:
  ssl:
    bundle:
      jks:
        mybundle:
          truststore:
            location: "classpath:server.p12"
            password: "secret"

有关完整的受支持属性集,请参阅 JksSslBundlePropertiesspring-doc.cadn.net.cn

14.2. 使用 PEM 编码的证书配置 SSL

带有前缀的 Configuration 属性spring.ssl.bundle.pem可用于以 PEM 编码文本的形式配置信任材料包。 每个捆绑包都有一个用户提供的名称,可用于引用捆绑包。spring-doc.cadn.net.cn

当用于保护嵌入式 Web 服务器时,keystore通常配置证书和私钥,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.ssl.bundle.pem.mybundle.keystore.certificate=classpath:application.crt
spring.ssl.bundle.pem.mybundle.keystore.private-key=classpath:application.key
Yaml
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          keystore:
            certificate: "classpath:application.crt"
            private-key: "classpath:application.key"

当用于保护客户端连接时,一个truststore通常使用服务器证书进行配置,如以下示例所示:spring-doc.cadn.net.cn

性能
spring.ssl.bundle.pem.mybundle.truststore.certificate=classpath:server.crt
Yaml
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          truststore:
            certificate: "classpath:server.crt"

PEM 内容可以直接用于certificateprivate-key性能。 如果属性值包含BEGINEND标记,则它们将被视为 PEM 内容而不是资源位置。spring-doc.cadn.net.cn

以下示例显示了如何定义信任库证书:spring-doc.cadn.net.cn

性能
spring.ssl.bundle.pem.mybundle.truststore.certificate=\
-----BEGIN CERTIFICATE-----\n\
MIID1zCCAr+gAwIBAgIUNM5QQv8IzVQsgSmmdPQNaqyzWs4wDQYJKoZIhvcNAQEL\n\
BQAwezELMAkGA1UEBhMCWFgxEjAQBgNVBAgMCVN0YXRlTmFtZTERMA8GA1UEBwwI\n\
...\n\
V0IJjcmYjEZbTvpjFKznvaFiOUv+8L7jHQ1/Yf+9c3C8gSjdUfv88m17pqYXd+Ds\n\
HEmfmNNjht130UyjNCITmLVXyy5p35vWmdf95U3uEbJSnNVtXH8qRmN9oK9mUpDb\n\
ngX6JBJI7fw7tXoqWSLHNiBODM88fUlQSho8\n\
-----END CERTIFICATE-----\n
Yaml
spring:
  ssl:
    bundle:
      pem:
        mybundle:
          truststore:
            certificate: |
              -----BEGIN CERTIFICATE-----
              MIID1zCCAr+gAwIBAgIUNM5QQv8IzVQsgSmmdPQNaqyzWs4wDQYJKoZIhvcNAQEL
              BQAwezELMAkGA1UEBhMCWFgxEjAQBgNVBAgMCVN0YXRlTmFtZTERMA8GA1UEBwwI
              ...
              V0IJjcmYjEZbTvpjFKznvaFiOUv+8L7jHQ1/Yf+9c3C8gSjdUfv88m17pqYXd+Ds
              HEmfmNNjht130UyjNCITmLVXyy5p35vWmdf95U3uEbJSnNVtXH8qRmN9oK9mUpDb
              ngX6JBJI7fw7tXoqWSLHNiBODM88fUlQSho8
              -----END CERTIFICATE-----

有关完整的受支持属性集,请参阅 PemSslBundlePropertiesspring-doc.cadn.net.cn

14.3. 应用 SSL 捆绑包

使用属性配置后,可以在 Spring Boot 自动配置的各种类型的连接的配置属性中按名称引用 SSL 捆绑包。 有关详细信息,请参阅有关嵌入式 Web 服务器数据技术和 REST 客户端的部分。spring-doc.cadn.net.cn

14.4. 使用 SSL 捆绑包

Spring Boot 自动配置类型为SslBundles,提供对使用spring.ssl.bundle性能。spring-doc.cadn.net.cn

SslBundle可以从 auto-configuredSslBundlesbean 的 API 和对象,用于创建用于在客户端库中配置 SSL 连接的对象。 这SslBundle提供获取这些 SSL 对象的分层方法:spring-doc.cadn.net.cn

  • getStores()提供对密钥存储和信任存储的访问java.security.KeyStore实例以及任何必需的密钥存储密码。spring-doc.cadn.net.cn

  • getManagers()提供对java.net.ssl.KeyManagerFactoryjava.net.ssl.TrustManagerFactory实例以及java.net.ssl.KeyManagerjava.net.ssl.TrustManager数组。spring-doc.cadn.net.cn

  • createSslContext()提供了一种便捷的方式来获取新的java.net.ssl.SSLContext实例。spring-doc.cadn.net.cn

此外,SslBundle提供有关正在使用的密钥、要使用的协议以及应应用于 SSL 引擎的任何选项的详细信息。spring-doc.cadn.net.cn

以下示例显示了如何检索SslBundle并使用它来创建一个SSLContext:spring-doc.cadn.net.cn

Java
import javax.net.ssl.SSLContext;

import org.springframework.boot.ssl.SslBundle;
import org.springframework.boot.ssl.SslBundles;
import org.springframework.stereotype.Component;

@Component
public class MyComponent {

    public MyComponent(SslBundles sslBundles) {
        SslBundle sslBundle = sslBundles.getBundle("mybundle");
        SSLContext sslContext = sslBundle.createSslContext();
        // do something with the created sslContext
    }

}
Kotlin
import org.springframework.boot.ssl.SslBundles
import org.springframework.stereotype.Component

@Component
class MyComponent(sslBundles: SslBundles) {

    init {
        val sslBundle = sslBundles.getBundle("mybundle")
        val sslContext = sslBundle.createSslContext()
        // do something with the created sslContext
    }

}

15. 下一步要读什么

如果您想了解有关本节中讨论的任何类的更多信息,请参阅 Spring Boot API 文档,或者您可以直接浏览源代码。 如果您有具体问题,请参阅作方法部分。spring-doc.cadn.net.cn

如果您对 Spring Boot 的核心功能感到满意,则可以继续阅读有关生产就绪功能的信息。spring-doc.cadn.net.cn