開發時期服務

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

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 區段。

由於 healthcheck 組態通常會從 compose.yml 檔案中省略，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，您需要使用「測試」類別路徑而不是「主要」類別路徑來啟動您的應用程式。這將允許您存取所有宣告的測試依賴項，並為您提供編寫測試組態的自然位置。

若要建立應用程式的可測試啟動版本，您應該在 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 方法貢獻動態屬性，您可以透過注入 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 未處於活動狀態。