開發時服務

開發時服務提供執行應用程式時所需的外部依賴項。它們僅用於開發期間，在部署應用程式時會停用。

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。

repackaged 的歸檔檔案預設不包含 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" 的容器

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

跳過特定容器

如果您的 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 Profiles

Docker Compose 的 profile 類似於 Spring 的 profile，它們允許您針對特定環境調整 Docker Compose 配置。如果您想啟用特定的 Docker Compose profile，可以在 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，您需要使用“測試”類路徑而不是“主”類路徑啟動應用程式。這將允許您訪問所有宣告的測試依賴項，併為您提供編寫測試配置的自然位置。

要建立應用程式的可測試啟動版本，您應該在 src/test 目錄中建立一個“應用程式”類。例如，如果您的主應用程式位於 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 未啟用。