Testcontainers 实战：用 Docker 容器跑可靠的 Java 集成测试

在 Java 项目里，Testcontainers 正成为编写集成测试的事实标准。它借助 Docker 在测试启动时拉起真实的 PostgreSQL、Redis、Kafka 等中间件容器，测试结束后自动回收。相比用 Mockito 硬造一个“假数据库”，用真容器跑出来的断言更贴近生产环境，却又不需要你手动维护一台常驻测试机。

一、为什么集成测试需要真实依赖

纯单元测试用 Mock 把依赖全部替掉，速度快、稳定，但它测不到“SQL 在真实数据库上的行为”“缓存过期策略”“消息序列化的边界”。这些恰恰是线上最容易翻车的地方。传统做法是搭一台共享测试库，但多分支并行、数据污染、版本漂移很快让测试变得不可信。Testcontainers 的思路是：每条测试（或每个测试类）按需起一个干净容器，用完即焚，环境永远一致。

二、Testcontainers 的核心机制

其底层是一个 GenericContainer 抽象：你指定镜像、端口、环境变量，它会调用本地 Docker API 创建容器，并把暴露端口随机映射到宿主机，再把地址注入到你的测试配置里。为了避免容器泄漏，Testcontainers 还会启动一个叫做 Ryuk 的回收容器，专门负责在 JVM 退出时清理残留资源。JDBC 模块更进一步，提供了“单例容器”能力——同一个测试套件里所有用例复用同一个数据库容器，大幅提升速度。

三、三步接入：引入依赖

以 Maven 为例，引入核心包与对应中间件的模块：

<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers</artifactId>
  <version>1.20.4</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>1.20.4</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>postgresql</artifactId>
  <version>1.20.4</version>
  <scope>test</scope>
</dependency>

注意版本号请对齐官方最新稳定版；本文示例基于 1.20.x 系列，API 在新版中保持向后兼容。Gradle 用户则使用 testImplementation "org.testcontainers:postgresql:1.20.4" 之类的写法即可。

四、实战：用 PostgreSQL 容器测试数据访问层

下面这个 JUnit 5 用例启动一个 PostgreSQL 容器，并用单例模式让它复用，避免每个测试类都重新拉镜像：

@Testcontainers
class UserRepositoryTest {

    @Container
    static final PostgreSQLContainer<?> pg =
        new PostgreSQLContainer<>("postgres:16-alpine")
            .withDatabaseName("testdb")
            .withUsername("u")
            .withPassword("p");

    private DataSource ds;

    @BeforeEach
    void setUp() {
        HikariConfig cfg = new HikariConfig();
        cfg.setJdbcUrl(pg.getJdbcUrl());
        cfg.setUsername(pg.getUsername());
        cfg.setPassword(pg.getPassword());
        ds = new HikariDataSource(cfg);
    }

    @Test
    void should_insert_and_query_user() throws Exception {
        try (Connection c = ds.getConnection();
             Statement s = c.createStatement()) {
            s.execute("create table users(id bigint, name varchar(50))");
            s.execute("insert into users values (1, 'Ada')");
            ResultSet rs = s.executeQuery("select name from users where id = 1");
            assertTrue(rs.next());
            assertEquals("Ada", rs.getString("name"));
        }
    }
}

代码中 pg.getJdbcUrl() 返回的是已映射到宿主机的真实连接串，你的连接池（如 HikariCP）或 JPA 配置直接消费即可，无需硬编码地址。PostgreSQL 的索引与查询 也能在这种真实环境里被完整验证，而不会像 Mock 那样悄悄放过类型或约束错误。

五、与 Spring Boot 集成

Spring Boot 3.1+ 提供了 @ServiceConnection 注解，能自动把容器连接信息注入 ApplicationContext，连 application-test.yml 都不用写：

@SpringBootTest
@Testcontainers
class OrderServiceIT {

    @Container
    @ServiceConnection
    static final PostgreSQLContainer<?> pg =
        new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired
    private OrderService orderService;

    @Test
    void creates_order_and_persists() {
        Order o = orderService.create("SKU-001", 2);
        assertNotNull(orderService.findById(o.id()));
    }
}

只要 classpath 上存在 Testcontainers 与对应 starter，@ServiceConnection 会在上下文启动时自动接管数据源、Redis、Kafka 等 Bean 的连接配置，测试代码几乎零侵入。Redis、Kafka 模块同理，把 PostgreSQLContainer 换成 RedisContainer 或 KafkaContainer 即可。

六、常见坑与最佳实践

落地时最容易踩的几个坑：

另外，不要把 Testcontainers 用在单元测试里——它天然偏重，应该放在 *IT 命名、由 Failsafe 插件在集成测试阶段执行的用例中，与 JUnit 5 单元测试 分层管理。这样本地日常 mvn test 依旧秒级，只有 mvn verify 才拉起容器。

七、在 CI 中跑起来

在 GitHub Actions 里只需保证 runner 具备 Docker 能力，例如用 ubuntu-latest 并加一步登录镜像仓库（如需私有基础镜像）。为加速，可在 workflow 中缓存 ~/.cache/testcontainers，并利用 TESTCONTAINERS_RYUK_DISABLED=false 确保回收正常。下面是一段最小可用的 workflow 片段：

name: integration
on: [push]
jobs:
  it:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
      - run: mvn -B verify

如果你在 Docker-in-Docker 受限的 runner 上运行，也可以改用 Testcontainers 的复用模式或第三方托管服务，避免在受限环境里反复拉镜像拖慢流水线。

八、小结

Testcontainers 用“真实容器 + 自动生命周期”补齐了 Java 集成测试最薄弱的一环：它让你在本地和 CI 里都能用和生产一致的数据库、缓存、消息队列做断言，又不必维护常驻测试环境。配合 Spring Boot 的 @ServiceConnection、JUnit 5 的分层命名与 CI 的 Docker 能力，你可以低侵入地把“可信集成测试”沉淀进日常开发流程。当你下次想用 Mock 假装一个数据库时，不妨先想想：用 Docker 起个真容器，可能只多写三行代码，却换来数倍的信心。

九、进阶：用 Docker Compose 编排多服务

当测试需要一整个依赖拓扑（比如应用 + 数据库 + 消息队列 + 缓存）时，可以用 Testcontainers 的 DockerComposeContainer 直接复用你已有的 docker-compose.yml，让测试环境与本地联调、生产部署保持同一份声明。这样既减少了“在我机器上是好的”这类扯皮，也让新同事一条命令就能跑通集成测试。

最后提醒一句：集成测试的价值在于“覆盖单元测试到不了的边界”，而不是把单元逻辑再测一遍。把真正依赖外部中间件的行为交给 Testcontainers，把纯逻辑留给快速 Mock，测试金字塔才不会倒置。

十、配合数据库迁移工具（Flyway）

集成测试最怕“表结构对不上代码”。把像 Flyway 这样的迁移工具与 Testcontainers 组合起来，可以在容器启动后自动执行 V1__init.sql 等迁移脚本，保证测试库 schema 与迁移历史完全一致。做法是在容器就绪后，用 Flyway 的 Java API 指向该数据源执行 migrate()，再开始用例：

@BeforeAll
static void migrate() {
    Flyway flyway = Flyway.configure()
        .dataSource(pg.getJdbcUrl(), pg.getUsername(), pg.getPassword())
        .load();
    flyway.migrate();
}

这样哪怕你改了字段类型或加错索引，测试也会第一时间报错，而不是等到预发环境才暴露，省下大量“本地能跑”的扯皮时间。

十一、并行执行与资源隔离

当模块变多，串行拉容器会拖慢整体时长。一个常见优化是给不同测试类复用同一个单例容器（设置 withReuse(true) 并开启 TESTCONTAINERS_REUSE=true），配合容器网络的随机端口映射，避免并行用例抢端口。若 CI runner 内存有限，也可以只保留最关键的几个依赖容器，其余用更轻的替代品或直接 Mock。记住：集成测试的目标是“验证跨边界行为”，而不是“把整条生产链路原样搬进测试”。