开发时服务

DeepSeek V3 中英对照 Development-time Services

开发时服务提供在开发应用程序时所需的外部依赖项。这些服务仅在开发过程中使用，并在应用程序部署时被禁用。

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 的清单如下：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-docker-compose</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

xml

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

gradle

当此模块作为依赖项包含时，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）命令行工具。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" 的容器
Elasticsearch 连接详情	名为 “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"
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"。

自定义镜像

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

如果你的镜像使用了不同的名称，你可以在 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

yaml

跳过特定容器

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

例如：

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

yaml

使用特定的 Compose 文件

如果你的 Compose 文件不在与应用程序相同的目录中，或者它的命名不同，你可以在 application.properties 或 application.yaml 中使用 spring.docker.compose.file 来指向一个不同的文件。属性可以定义为绝对路径或相对于应用程序的路径。

例如：

Properties

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

properties

YAML

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

yaml

等待容器就绪

由 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

yaml

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

Properties

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

properties

YAML

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

yaml

可以使用 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

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

properties

YAML

spring:
  docker:
    compose:
      lifecycle-management: start-and-stop
      start:
        command: start
      stop:
        command: down
        timeout: 1m

yaml

激活 Docker Compose 配置文件

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

Properties

spring.docker.compose.profiles.active=myprofile

properties

YAML

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

yaml

在测试中使用 Docker Compose

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

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

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

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

gradle

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

}

java

你还需要定义你想要与应用程序一起启动的 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");
    }

}

java

备注

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

现在，你可以像启动任何常规的 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);
        };
    }

}

java

备注

尽可能使用 @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");

}

java

如果您已经以这种方式定义了容器，或者您更喜欢这种风格，您可以导入这些声明类，而不是将容器定义为 @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 {

}

java

提示

如果你不打算使用服务连接功能，而是想使用@DynamicPropertySource，请从Container字段中移除@ServiceConnection注解。你也可以在声明类中添加@DynamicPropertySource注解的方法。

在开发时使用 DevTools 与 Testcontainers

在使用 devtools 时，你可以使用 @RestartScope 注解来标注 bean 和 bean 方法。这样的 bean 在 devtools 重启应用程序时不会被重新创建。这对于 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");
    }

}

java

注意

如果你正在使用 Gradle 并且想使用此功能，你需要将 spring-boot-devtools 依赖项的配置从 developmentOnly 更改为 testAndDevelopmentOnly。在默认的 developmentOnly 作用域下，bootTestRun 任务将不会检测到代码中的更改，因为开发工具未处于激活状态。