开发时服务

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

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 插件时，配置任务的 classpath 以包含 developmentOnly 配置。

前提条件

你需要在路径中安装 docker 和 docker compose（或 docker-compose）命令行工具。 支持的最低 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"

HazelcastConnectionDetails

容器名称为 "hazelcast/hazelcast"

JdbcConnectionDetails

容器名称为 "clickhouse/clickhouse-server", "bitnami/clickhouse", "gvenzl/oracle-free", "gvenzl/oracle-xe", "mariadb", "bitnami/mariadb", "mssql/server", "mysql", "bitnami/mysql", "postgres", 或 "bitnami/postgresql"

LdapConnectionDetails

容器名称为 "osixia/openldap", "lldap/lldap"

MongoConnectionDetails

容器名称为 "mongo" 或 "bitnami/mongodb"

Neo4jConnectionDetails

容器名称为 "neo4j" 或 "bitnami/neo4j"

OtlpLoggingConnectionDetails

容器名称为 "otel/opentelemetry-collector-contrib", "grafana/otel-lgtm"

OtlpMetricsConnectionDetails

容器名称为 "otel/opentelemetry-collector-contrib", "grafana/otel-lgtm"

OtlpTracingConnectionDetails

容器名称为 "otel/opentelemetry-collector-contrib", "grafana/otel-lgtm"

PulsarConnectionDetails

容器名称为 "apachepulsar/pulsar"

R2dbcConnectionDetails

容器名称为 "clickhouse/clickhouse-server", "bitnami/clickhouse", "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", "redis/redis-stack" 或 "redis/redis-stack-server"

ZipkinConnectionDetails

容器名称为 "openzipkin/zipkin"

SSL 支持

一些镜像默认启用了 SSL，或者你可能希望为容器启用 SSL 以镜像你的生产环境设置。 Spring Boot 支持为支持的服务连接配置 SSL。 请注意，你仍需在容器内运行的服务上自行启用 SSL，此功能仅在你的应用程序客户端配置 SSL。

以下服务连接支持 SSL：

  • Cassandra

  • Couchbase

  • Elasticsearch

  • Kafka

  • MongoDB

  • RabbitMQ

  • Redis

要为服务启用 SSL 支持，你可以使用 服务标签。

对于基于 JKS 的密钥库和信任库，你可以使用以下容器标签：

  • org.springframework.boot.sslbundle.jks.key.alias

  • org.springframework.boot.sslbundle.jks.key.password

  • org.springframework.boot.sslbundle.jks.options.ciphers

  • org.springframework.boot.sslbundle.jks.options.enabled-protocols

  • org.springframework.boot.sslbundle.jks.protocol

  • org.springframework.boot.sslbundle.jks.keystore.type

  • org.springframework.boot.sslbundle.jks.keystore.provider

  • org.springframework.boot.sslbundle.jks.keystore.location

  • org.springframework.boot.sslbundle.jks.keystore.password

  • org.springframework.boot.sslbundle.jks.truststore.type

  • org.springframework.boot.sslbundle.jks.truststore.provider

  • org.springframework.boot.sslbundle.jks.truststore.location

  • org.springframework.boot.sslbundle.jks.truststore.password

这些标签对应于 SSL 捆绑包 可用的属性。

对于基于 PEM 的密钥库和信任库，你可以使用以下容器标签：

  • org.springframework.boot.sslbundle.pem.key.alias

  • org.springframework.boot.sslbundle.pem.key.password

  • org.springframework.boot.sslbundle.pem.options.ciphers

  • org.springframework.boot.sslbundle.pem.options.enabled-protocols

  • org.springframework.boot.sslbundle.pem.protocol

  • org.springframework.boot.sslbundle.pem.keystore.type

  • org.springframework.boot.sslbundle.pem.keystore.certificate

  • org.springframework.boot.sslbundle.pem.keystore.private-key

  • org.springframework.boot.sslbundle.pem.keystore.private-key-password

  • org.springframework.boot.sslbundle.pem.truststore.type

  • org.springframework.boot.sslbundle.pem.truststore.certificate

  • org.springframework.boot.sslbundle.pem.truststore.private-key

  • org.springframework.boot.sslbundle.pem.truststore.private-key-password

这些标签对应于 SSL 捆绑包 可用的属性。

以下示例为 redis 容器启用 SSL：

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'

自定义镜像

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

如果你的镜像使用不同的名称，你可以在 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 指向不同的文件。 属性可以定义为绝对路径或相对于应用程序的路径。

例如：

  • Properties

  • 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 文件中更改超时值：

  • Properties

  • 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。

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

  • Properties

  • 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 属性：

  • Properties

  • 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 方法，以创建 ConnectionDetails bean。 有关支持的技术详情，请参见 服务连接 部分。

典型的 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 方法中贡献动态属性，请定义一个额外的 DynamicPropertyRegistrar bean。 该注册器应使用 @Bean 方法定义，该方法将从中获取属性的容器作为参数注入。 这种安排确保在属性使用之前容器已启动。

典型的配置如下所示：

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

}
建议尽可能使用 @ServiceConnection，但对于尚未支持 @ServiceConnection 的技术，动态属性是一个有用的备选方案。

导入 Testcontainers 声明类

使用 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 方法。 这些 bean 在 DevTools 重启应用程序时不会被重新创建。 这对 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 未激活。