开发时服务

开发时服务提供在开发应用程序时运行应用程序所需的外部依赖项。 它们应该只在开发时使用，并在部署应用程序时被禁用。spring-doc.cadn.net.cn

Spring Boot 支持两种开发时服务，即 Docker Compose 和 Testcontainers。 接下来的部分将提供有关它们的更多详细信息。spring-doc.cadn.net.cn

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

专家
<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。 如果要使用此支持，则需要包含它。 使用 Maven 插件时，将excludeDockerCompose属性设置为false. 使用 Gradle 插件时，配置任务的类路径以包含developmentOnly配置.

前提条件

您需要拥有docker和docker compose（或docker-compose） CLI 应用程序。 支持的最低 Docker Compose 版本为 2.2.0。spring-doc.cadn.net.cn

服务连接

服务连接是与任何远程服务的连接。 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

连接详细信息 匹配时间

ActiveMQConnectionDetailsspring-doc.cadn.net.cn

名为“symptoma/activemq”或“apache/activemq-classic”的容器spring-doc.cadn.net.cn

ArtemisConnectionDetailsspring-doc.cadn.net.cn

名为“apache/activemq-artemis”的容器spring-doc.cadn.net.cn

CassandraConnectionDetailsspring-doc.cadn.net.cn

名为“cassandra”或“bitnami/cassandra”的容器spring-doc.cadn.net.cn

ElasticsearchConnectionDetailsspring-doc.cadn.net.cn

名为“elasticsearch”或“bitnami/elasticsearch”的容器spring-doc.cadn.net.cn

HazelcastConnectionDetailsspring-doc.cadn.net.cn

名为“hazelcast/hazelcast”的容器。spring-doc.cadn.net.cn

JdbcConnectionDetailsspring-doc.cadn.net.cn

名为“clickhouse/clickhouse-server”、“bitnami/clickhouse”、“gvenzl/oracle-free”、“gvenzl/oracle-xe”、“mariadb”、“bitnami/mariadb”、“mssql/server”、“mysql”、“bitnami/mysql”、“postgres”或“bitnami/postgresql”的容器spring-doc.cadn.net.cn

LdapConnectionDetailsspring-doc.cadn.net.cn

名为“osixia/openldap”、“lldap/lldap”的容器spring-doc.cadn.net.cn

MongoConnectionDetailsspring-doc.cadn.net.cn

名为“mongo”或“bitnami/mongodb”的容器spring-doc.cadn.net.cn

Neo4jConnectionDetailsspring-doc.cadn.net.cn

名为“neo4j”或“bitnami/neo4j”的容器spring-doc.cadn.net.cn

OtlpLoggingConnectionDetailsspring-doc.cadn.net.cn

名为“otel/opentelemetry-collector-contrib”、“grafana/otel-lgtm”的容器spring-doc.cadn.net.cn

OtlpMetricsConnectionDetailsspring-doc.cadn.net.cn

名为“otel/opentelemetry-collector-contrib”、“grafana/otel-lgtm”的容器spring-doc.cadn.net.cn

OtlpTracingConnectionDetailsspring-doc.cadn.net.cn

名为“otel/opentelemetry-collector-contrib”、“grafana/otel-lgtm”的容器spring-doc.cadn.net.cn

PulsarConnectionDetailsspring-doc.cadn.net.cn

名为“apachepulsar/pulsar”的容器spring-doc.cadn.net.cn

R2dbcConnectionDetailsspring-doc.cadn.net.cn

名为“clickhouse/clickhouse-server”、“bitnami/clickhouse”、“gvenzl/oracle-free”、“gvenzl/oracle-xe”、“mariadb”、“bitnami/mariadb”、“mssql/server”、“mysql”、“bitnami/mysql”、“postgres”或“bitnami/postgresql”的容器spring-doc.cadn.net.cn

RabbitConnectionDetailsspring-doc.cadn.net.cn

名为“rabbitmq”或“bitnami/rabbitmq”的容器spring-doc.cadn.net.cn

RedisConnectionDetailsspring-doc.cadn.net.cn

名为“redis”、“bitnami/redis”、“redis/redis-stack”或“redis/redis-stack-server”的容器spring-doc.cadn.net.cn

ZipkinConnectionDetailsspring-doc.cadn.net.cn

名为“openzipkin/zipkin”的容器。spring-doc.cadn.net.cn

SSL 支持

某些映像开箱即用地启用了 SSL，或者您可能希望为容器启用 SSL 以镜像您的生产设置。 Spring Boot 支持支持的服务连接的 SSL 配置。 请注意，您仍然必须自己在容器内运行的服务上启用 SSL，此功能仅在应用程序的客户端配置 SSL。spring-doc.cadn.net.cn

以下服务连接支持 SSL：spring-doc.cadn.net.cn

要为服务启用 SSL 支持，您可以使用服务标签。spring-doc.cadn.net.cn

对于基于 JKS 的密钥库和信任库，您可以使用以下容器标签：spring-doc.cadn.net.cn

这些标签镜像了 SSL 捆绑包的可用属性。spring-doc.cadn.net.cn

对于基于 PEM 的密钥库和信任库，您可以使用以下容器标签：spring-doc.cadn.net.cn

这些标签镜像了 SSL 捆绑包的可用属性。spring-doc.cadn.net.cn

以下示例为 redis 容器启用 SSL：spring-doc.cadn.net.cn

services:
  redis:
    image: 'redis:latest'
    ports:
      - '6379'
    secrets:
      - ssl-ca
      - ssl-key
      - ssl-cert
    command: 'redis-server --tls-port 6379 --port 0 --tls-cert-file /run/secrets/ssl-cert --tls-key-file /run/secrets/ssl-key --tls-ca-cert-file /run/secrets/ssl-ca'
    labels:
      - 'org.springframework.boot.sslbundle.pem.keystore.certificate=client.crt'
      - 'org.springframework.boot.sslbundle.pem.keystore.private-key=client.key'
      - 'org.springframework.boot.sslbundle.pem.truststore.certificate=ca.crt'
secrets:
  ssl-ca:
    file: 'ca.crt'
  ssl-key:
    file: 'server.key'
  ssl-cert:
    file: 'server.crt'

自定义图像

有时，您可能需要使用自己的映像版本来提供服务。 您可以使用任何自定义图像，只要其行为方式与标准图像相同即可。 具体而言，标准映像支持的任何环境变量也必须在自定义映像中使用。spring-doc.cadn.net.cn

如果您的图片使用不同的名称，您可以在compose.yml文件，以便 Spring Boot 可以提供服务连接。 使用名为org.springframework.boot.service-connection以提供服务名称。spring-doc.cadn.net.cn

例如：spring-doc.cadn.net.cn

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

跳过特定容器

如果您在compose.yml您不想连接到应用程序，您可以使用标签来忽略它。任何标记为org.springframework.boot.ignore将被 Spring Boot 忽略。spring-doc.cadn.net.cn

例如：spring-doc.cadn.net.cn

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

使用特定的撰写文件

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

例如：spring-doc.cadn.net.cn

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

等待容器准备就绪

由 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

例如：spring-doc.cadn.net.cn

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

您还可以更改application.properties或application.yaml文件：spring-doc.cadn.net.cn

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.spring-doc.cadn.net.cn

控制 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 up或docker compose start被使用。 这spring.docker.compose.stop.command允许您配置 ifdocker compose down或docker 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
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 配置文件，可以使用spring.docker.compose.profiles.active您的财产application.properties或application.yaml文件：spring-doc.cadn.net.cn

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

在测试中使用 Docker Compose

默认情况下，运行测试时禁用 Spring Boot 的 Docker Compose 支持。spring-doc.cadn.net.cn

要在测试中启用 Docker Compose 支持，请将spring.docker.compose.skip.in-tests自false.spring-doc.cadn.net.cn

使用 Gradle 时，您还需要更改spring-boot-docker-compose依赖项来自developmentOnly自testAndDevelopmentOnly:spring-doc.cadn.net.cn

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

测试容器支持

除了使用 Testcontainers 进行集成测试外，还可以在开发时使用它们。 接下来的部分将提供有关这方面的更多详细信息。spring-doc.cadn.net.cn

在开发时使用 Testcontainers

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

要在开发时使用 Testcontainers，您需要使用“test”类路径而不是“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

import org.springframework.boot.SpringApplication;

public class TestMyApplication {

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

}
import org.springframework.boot.fromApplication

fun main(args: Array<String>) {
	fromApplication<MyApplication>().run(*args)
}

您还需要定义Container要与应用程序一起启动的实例。为此，您需要确保spring-boot-testcontainers模块已添加为testDependency。 完成后，您可以创建一个@TestConfiguration声明@Bean方法。spring-doc.cadn.net.cn

您还可以注释您的@Bean方法@ServiceConnection为了创建ConnectionDetails豆。 有关支持技术的详细信息，请参阅服务连接部分。spring-doc.cadn.net.cn

典型的 Testcontainers 配置如下所示：spring-doc.cadn.net.cn

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

}
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 自动管理。容器将自动启动和停止。
您可以使用spring.testcontainers.beans.startup属性来更改容器的启动方式。默认情况下sequential使用启动，但您也可以选择parallel如果您希望并行启动多个容器。

定义测试配置后，您可以使用with(…​)将其附加到测试Starters的方法：spring-doc.cadn.net.cn

import org.springframework.boot.SpringApplication;

public class TestMyApplication {

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

}
import org.springframework.boot.fromApplication
import org.springframework.boot.with

fun main(args: Array<String>) {
	fromApplication<MyApplication>().with(MyContainersConfiguration::class).run(*args)
}

您现在可以启动TestMyApplication就像你对待任何普通 Java 一样main方法应用程序来启动应用程序及其需要运行的容器。spring-doc.cadn.net.cn

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

在开发时贡献动态属性

如果要在开发时从Container @Bean方法，定义一个额外的DynamicPropertyRegistrar豆。 注册商应使用@Bean方法，将属性的来源作为参数注入容器。这种安排可确保在使用属性之前启动容器。spring-doc.cadn.net.cn

典型的配置如下所示：spring-doc.cadn.net.cn

import org.testcontainers.containers.MongoDBContainer;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.test.context.DynamicPropertyRegistrar;

@TestConfiguration(proxyBeanMethods = false)
public class MyContainersConfiguration {

	@Bean
	public MongoDBContainer mongoDbContainer() {
		return new MongoDBContainer("mongo:5.0");
	}

	@Bean
	public DynamicPropertyRegistrar mongoDbProperties(MongoDBContainer container) {
		return (properties) -> {
			properties.add("spring.data.mongodb.host", container::getHost);
			properties.add("spring.data.mongodb.port", container::getFirstMappedPort);
		};
	}

}
import org.springframework.boot.test.context.TestConfiguration
import org.springframework.context.annotation.Bean
import org.springframework.test.context.DynamicPropertyRegistrar;
import org.testcontainers.containers.MongoDBContainer

@TestConfiguration(proxyBeanMethods = false)
class MyContainersConfiguration {

	@Bean
	fun mongoDbContainer(): MongoDBContainer {
		return MongoDBContainer("mongo:5.0")
	}
	
	@Bean
	fun mongoDbProperties(container: MongoDBContainer): DynamicPropertyRegistrar {
		return DynamicPropertyRegistrar { properties ->
			properties.add("spring.data.mongodb.host") { container.host }
			properties.add("spring.data.mongodb.port") { container.firstMappedPort }
		}
	}

}
使用@ServiceConnection建议尽可能使用，但是，对于尚未具有动态属性的技术来说，动态属性可能是一个有用的回退@ServiceConnection支持。

导入 Testcontainers 声明类

使用 Testcontainers 时的常见模式是声明Container实例作为静态字段。通常，这些字段直接在测试类上定义。它们也可以在父类或测试实现的接口上声明。spring-doc.cadn.net.cn

例如，以下内容MyContainers接口声明mongo和neo4j器皿：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");

}
import org.springframework.boot.testcontainers.service.connection.ServiceConnection
import org.testcontainers.containers.MongoDBContainer
import org.testcontainers.containers.Neo4jContainer
import org.testcontainers.junit.jupiter.Container

interface MyContainers {

	companion object {

		@Container
		@ServiceConnection
		@JvmField
		val mongoContainer = MongoDBContainer("mongo:5.0")

		@Container
		@ServiceConnection
		@JvmField
		val neo4jContainer = Neo4jContainer("neo4j:5")

	}

}

如果您已经以这种方式定义了容器，或者您只是更喜欢这种样式，则可以导入这些声明类，而不是将容器定义为@Bean方法。 为此，请添加@ImportTestcontainersComments 添加到您的测试配置类中：spring-doc.cadn.net.cn

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

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

}
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领域。 您还可以添加@DynamicPropertySource带注释的方法添加到您的声明类中。

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

使用 devtools 时，您可以使用@RestartScope. 当 devtools 重新启动应用程序时，不会重新创建此类 Bean。 这对于Containerbean，因为尽管应用程序重新启动，它们仍保持其状态。spring-doc.cadn.net.cn

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

}
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 mongoDbContainer(): MongoDBContainer {
		return MongoDBContainer("mongo:5.0")
	}

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