开发时服务

开发时服务提供运行应用程序时所需的外部依赖项。它们仅在开发期间使用，并在应用程序部署时禁用。

Spring Boot 支持两种开发时服务：Docker Compose 和 Testcontainers。接下来的部分将提供有关它们的更多详细信息。

Docker Compose 支持

Docker Compose 是一种流行的技术，可用于定义和管理应用程序所需的多个服务容器。通常会在应用程序旁边创建一个 compose.yml 文件，该文件定义并配置服务容器。

使用 Docker Compose 的典型工作流程是运行 docker compose up，使用它连接到已启动的服务来处理您的应用程序，然后在完成时运行 docker compose down。

spring-boot-docker-compose 模块可以包含在项目中，以提供对使用 Docker Compose 处理容器的支持。将模块依赖项添加到您的构建中，如下面的 Maven 和 Gradle 列表所示

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 将执行以下操作

  • 在您的工作目录中搜索 compose.yml 和其他常见的 compose 文件名

  • 使用发现的 compose.yml 调用 docker compose up

  • 为每个支持的容器创建服务连接 Bean

  • 应用程序关闭时调用 docker compose stop

如果在启动应用程序时 Docker Compose 服务已在运行，则 Spring Boot 将仅为每个支持的容器创建服务连接 Bean。它不会再次调用 docker compose up，也不会在应用程序关闭时调用 docker compose stop。

重新打包的归档文件默认不包含 Spring Boot 的 Docker Compose。如果您想使用此支持，则需要将其包含在内。使用 Maven 插件时，将excludeDockerCompose属性设置为false。使用 Gradle 插件时，配置任务的类路径以包含developmentOnly配置。

先决条件

您需要在路径中拥有docker和docker compose（或docker-compose）CLI 应用程序。支持的 Docker Compose 最低版本为 2.2.0。

服务连接

服务连接是到任何远程服务的连接。Spring Boot 的自动配置可以读取服务连接的详细信息，并使用它们来建立与远程服务的连接。在这种情况下，连接详细信息优先于任何与连接相关的配置属性。

使用 Spring Boot 的 Docker Compose 支持时，将建立到容器映射的端口的服务连接。

Docker Compose 通常以这样一种方式使用：容器内部的端口映射到计算机上的临时端口。例如，Postgres 服务器可能在使用端口 5432 的容器内运行，但本地映射到完全不同的端口。服务连接将始终发现并使用本地映射的端口。

服务连接是通过使用容器的镜像名称来建立的。当前支持以下服务连接

连接详细信息 匹配项

ActiveMQConnectionDetails

名为“symptoma/activemq”或“apache/activemq-classic”的容器

ArtemisConnectionDetails

名为“apache/activemq-artemis”的容器

CassandraConnectionDetails

名为“cassandra”或“bitnami/cassandra”的容器

ElasticsearchConnectionDetails

名为“elasticsearch”或“bitnami/elasticsearch”的容器

JdbcConnectionDetails

名为“gvenzl/oracle-free”，“gvenzl/oracle-xe”，“mariadb”，“bitnami/mariadb”，“mssql/server”，“mysql”，“bitnami/mysql”，“postgres”或“bitnami/postgresql”的容器

LdapConnectionDetails

名为“osixia/openldap”的容器

MongoConnectionDetails

名为“mongo”或“bitnami/mongodb”的容器

Neo4jConnectionDetails

名为“neo4j”或“bitnami/neo4j”的容器

OtlpMetricsConnectionDetails

名为“otel/opentelemetry-collector-contrib”的容器

OtlpTracingConnectionDetails

名为“otel/opentelemetry-collector-contrib”的容器

PulsarConnectionDetails

名为“apachepulsar/pulsar”的容器

R2dbcConnectionDetails

名为“gvenzl/oracle-free”，“gvenzl/oracle-xe”，“mariadb”，“bitnami/mariadb”，“mssql/server”，“mysql”，“bitnami/mysql”，“postgres”或“bitnami/postgresql”的容器

RabbitConnectionDetails

名为“rabbitmq”或“bitnami/rabbitmq”的容器

RedisConnectionDetails

名为“redis”或“bitnami/redis”的容器

ZipkinConnectionDetails

名为“openzipkin/zipkin”的容器。

自定义镜像

有时您可能需要使用您自己的镜像版本来提供服务。您可以使用任何自定义镜像，只要它的行为与标准镜像相同即可。具体来说，标准镜像支持的任何环境变量也必须在您的自定义镜像中使用。

如果您的镜像使用不同的名称，您可以在compose.yml文件中使用标签，以便 Spring Boot 可以提供服务连接。使用名为org.springframework.boot.service-connection的标签来提供服务名称。

例如

services:
  redis:
    image: 'mycompany/mycustomredis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.service-connection: redis

跳过特定容器

如果您在compose.yml中定义了一个不想连接到应用程序的容器镜像，则可以使用标签将其忽略。任何使用org.springframework.boot.ignore标记的容器都将被 Spring Boot 忽略。

例如

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.ignore: true

使用特定的 Compose 文件

如果您的 Compose 文件不在与应用程序相同的目录中，或者名称不同，则可以在application.properties或application.yaml中使用spring.docker.compose.file指向不同的文件。属性可以定义为精确路径或相对于应用程序的路径。

例如

  • 属性

  • YAML

spring.docker.compose.file=../my-compose.yml
spring:
  docker:
    compose:
      file: "../my-compose.yml"

等待容器就绪

Docker Compose 启动的容器可能需要一些时间才能完全准备就绪。检查就绪状态的推荐方法是在compose.yml文件中服务定义下添加healthcheck部分。

由于compose.yml文件中通常会省略healthcheck配置，因此 Spring Boot 还会直接检查服务是否已准备好。默认情况下，当可以建立到其映射端口的 TCP/IP 连接时，容器被认为已准备好。

您可以通过在compose.yml文件中添加org.springframework.boot.readiness-check.tcp.disable标签来禁用每个容器的此功能。

例如

services:
  redis:
    image: 'redis:7.0'
    ports:
      - '6379'
    labels:
      org.springframework.boot.readiness-check.tcp.disable: true

您也可以在application.properties或application.yaml文件中更改超时值

  • 属性

  • YAML

spring.docker.compose.readiness.tcp.connect-timeout=10s
spring.docker.compose.readiness.tcp.read-timeout=5s
spring:
  docker:
    compose:
      readiness:
        tcp:
          connect-timeout: 10s
          read-timeout: 5s

可以使用spring.docker.compose.readiness.timeout配置整体超时。

控制 Docker Compose 生命周期

默认情况下，Spring Boot 在应用程序启动时调用docker compose up，并在应用程序关闭时调用docker compose stop。如果您希望使用不同的生命周期管理，则可以使用spring.docker.compose.lifecycle-management属性。

支持以下值

  • none - 不启动或停止 Docker Compose

  • start-only - 在应用程序启动时启动 Docker Compose 并保持运行状态

  • start-and-stop - 在应用程序启动时启动 Docker Compose，并在 JVM 退出时停止它

此外，您可以使用spring.docker.compose.start.command属性更改是否使用docker compose up或docker compose start。spring.docker.compose.stop.command允许您配置是否使用docker compose down或docker compose stop。

以下示例显示了如何配置生命周期管理

  • 属性

  • YAML

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
spring:
  docker:
    compose:
      lifecycle-management: start-and-stop
      start:
        command: start
      stop:
        command: down
        timeout: 1m

激活 Docker Compose 配置文件

Docker Compose 配置文件类似于 Spring 配置文件，它们允许您为特定环境调整 Docker Compose 配置。如果要激活特定的 Docker Compose 配置文件，则可以在application.properties或application.yaml文件中使用spring.docker.compose.profiles.active属性

  • 属性

  • YAML

spring.docker.compose.profiles.active=myprofile
spring:
  docker:
    compose:
      profiles:
        active: "myprofile"

在测试中使用 Docker Compose

默认情况下，在运行测试时禁用 Spring Boot 的 Docker Compose 支持。

要在测试中启用 Docker Compose 支持，请将spring.docker.compose.skip.in-tests设置为false。

使用 Gradle 时，还需要将spring-boot-docker-compose依赖项的配置从developmentOnly更改为testAndDevelopmentOnly

Gradle
dependencies {
	testAndDevelopmentOnly("org.springframework.boot:spring-boot-docker-compose")
}

Testcontainers 支持

除了使用 Testcontainers 进行集成测试之外，还可以在开发时使用它们。接下来的部分将提供更多关于此的信息。

在开发时使用 Testcontainers

这种方法允许开发人员快速启动应用程序依赖的服务的容器，从而无需手动配置数据库服务器等内容。以这种方式使用 Testcontainers 提供的功能类似于 Docker Compose，只是您的容器配置在 Java 中而不是 YAML 中。

要在开发时使用 Testcontainers，您需要使用“test”类路径而不是“main”来启动应用程序。这将允许您访问所有声明的测试依赖项，并为您提供一个编写测试配置的自然位置。

要创建应用程序的可测试启动版本，您应该在src/test目录中创建一个“Application”类。例如，如果您的主应用程序位于src/main/java/com/example/MyApplication.java中，则应创建src/test/java/com/example/TestMyApplication.java

TestMyApplication类可以使用SpringApplication.from(…​)方法来启动真正的应用程序

import org.springframework.boot.SpringApplication;

public class TestMyApplication {

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

}

您还需要定义您希望与应用程序一起启动的Container实例。为此，您需要确保已将spring-boot-testcontainers模块添加为test依赖项。完成此操作后，您可以创建一个@TestConfiguration类，该类为要启动的容器声明@Bean方法。

您还可以使用@ServiceConnection注释您的@Bean方法，以创建ConnectionDetailsbean。有关支持技术的详细信息，请参阅服务连接部分。

典型的 Testcontainers 配置如下所示

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

}
Container bean 的生命周期由 Spring Boot 自动管理。容器将自动启动和停止。
您可以使用spring.testcontainers.beans.startup属性来更改容器的启动方式。默认情况下，使用sequential启动，但如果您希望并行启动多个容器，也可以选择parallel。

定义测试配置后，您可以使用with(…​)方法将其附加到测试启动器

import org.springframework.boot.SpringApplication;

public class TestMyApplication {

	public static void main(String[] args) {
		SpringApplication.from(MyApplication::main).with(MyContainersConfiguration.class).run(args);
	}

}

您现在可以像启动任何常规 Java main方法应用程序一样启动TestMyApplication，以启动您的应用程序及其运行所需的容器。

您可以使用 Maven 目标spring-boot:test-run或 Gradle 任务bootTestRun从命令行执行此操作。

在开发时提供动态属性

如果要在开发时从您的Container @Bean方法提供动态属性，您可以通过注入DynamicPropertyRegistry来实现。这与您在测试中可以使用@DynamicPropertySource注释的方式类似。它允许您添加在容器启动后可用的属性。

典型的配置如下所示

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

}
尽可能推荐使用@ServiceConnection，但是，对于尚不支持@ServiceConnection的技术，动态属性可以作为有用的后备方案。

导入 Testcontainer 声明类

使用 Testcontainers 时，一种常见的模式是将Container实例声明为静态字段。通常，这些字段直接在测试类上定义。它们也可以在父类或测试实现的接口上声明。

例如，以下MyContainers接口声明了mongo和neo4j容器

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注释添加到您的测试配置类

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.context.ImportTestcontainers;

@TestConfiguration(proxyBeanMethods = false)
@ImportTestcontainers(MyContainers.class)
public class MyContainersConfiguration {

}
如果您不打算使用服务连接功能，但希望使用@DynamicPropertySource，请从Container字段中删除@ServiceConnection注释。您还可以将@DynamicPropertySource注释的方法添加到您的声明类。

在开发时将 DevTools 与 Testcontainers 结合使用

使用 DevTools 时，您可以使用@RestartScope注解 Bean 和 Bean 方法。当 DevTools 重启应用程序时，此类 Bean 不会被重新创建。这对于 Testcontainer 的Container Bean 特别有用，因为即使应用程序重启，它们也能保持其状态。

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

}
如果您使用的是 Gradle 并希望使用此功能，则需要将spring-boot-devtools依赖项的配置从developmentOnly更改为testAndDevelopmentOnly。使用默认范围developmentOnly，bootTestRun任务将不会获取代码中的更改，因为 DevTools 未处于活动状态。