Testcontainers for Java：完整指南与示例

1. 什么是 Testcontainers 及其用途

Testcontainers 是一个强大的 Java（及其他 JVM 语言）库，它允许您在集成测试中直接启动 Docker 容器。与其依赖可能在不同环境中不可用或配置不同的外部数据库、消息代理或其他服务，Testcontainers 会在测试前自动启动所需容器，并在测试完成后销毁它们。这确保了测试的纯净性和可重复性。

为什么需要它？传统的集成测试常常受困于“环境问题”：测试可能在开发者机器上通过，但在 CI 服务器上因数据库版本不同或缺少特定服务而失败。Testcontainers 一劳永逸地解决了这个问题。您直接在测试代码中描述所需的基础设施（例如，“启用了 uuid-ossp 扩展的 PostgreSQL 15”），库会保证在隔离的 Docker 容器中创建该基础设施。这使得测试真正可移植且可靠。

该库特别适用于测试 DAO 层、仓库、处理队列（RabbitMQ、Kafka）、缓存（Redis）的服务，甚至通过 WireMock 或 Nginx 容器测试 HTTP 客户端。Testcontainers 还为流行技术（PostgreSQL、MySQL、MongoDB、Redis、Kafka、LocalStack 等）提供了便捷模块，从而将配置工作降至最低。

2. 安装

Testcontainers 通过 Maven Central 分发。要将其添加到 Java 项目中，请在您的 pom.xml（Maven）或 build.gradle（Gradle）中添加以下依赖。

Maven (pom.xml)

<dependency>\n    <groupId>org.testcontainers</groupId>\n    <artifactId>testcontainers</artifactId>\n    <version>1.19.7</version> <!-- 请在 Maven Central 上查看最新版本 -->\n    <scope>test</scope>\n</dependency>\n\n<!-- 额外模块，例如用于 PostgreSQL -->\n<dependency>\n    <groupId>org.testcontainers</groupId>\n    <artifactId>postgresql</artifactId>\n    <version>1.19.7</version>\n    <scope>test</scope>\n</dependency>

Gradle (build.gradle)

testImplementation 'org.testcontainers:testcontainers:1.19.7'\ntestImplementation 'org.testcontainers:postgresql:1.19.7'

重要提示： 请确保您的机器（或 CI 代理）上已安装并运行 Docker Engine。Testcontainers 通过套接字与 Docker 交互。如果您在 macOS 或 Windows 上使用 Docker Desktop，它必须处于运行状态。在 Linux 上，请确保运行测试的用户具有操作 Docker 的权限（例如，通过 docker 组）。

3. 快速入门 — 最小工作示例

让我们编写一个最简单的测试，启动一个 PostgreSQL 容器，创建表，插入数据并验证它们。这是 Testcontainers 的经典“Hello, World!”示例。

import org.junit.jupiter.api.Test;\nimport org.testcontainers.containers.PostgreSQLContainer;\nimport org.testcontainers.junit.jupiter.Container;\nimport org.testcontainers.junit.jupiter.Testcontainers;\n\nimport java.sql.Connection;\nimport java.sql.DriverManager;\nimport java.sql.ResultSet;\nimport java.sql.Statement;\n\nimport static org.junit.jupiter.api.Assertions.assertEquals;\n\n@Testcontainers // 启用容器的自动生命周期管理\nclass QuickStartTest {\n\n    // @Container 指示需要管理该容器（测试前启动，测试后停止）\n    @Container\n    private PostgreSQLCon