Spring Boot 如何用 Testcontainers 做数据库集成测试？

用 Spring Boot 写测试时，最尴尬的莫过于单元测试全绿，一上生产就因数据库方言、事务隔离级别或 SQL 模式不一致而翻车。H2 之类的内嵌数据库虽然启动快，但它与 MySQL、PostgreSQL 在函数、索引、自增策略、锁行为上存在大量差异。Testcontainers 的思路很直接：测试启动时用 Docker 拉起一个目标数据库容器，让测试代码连接真实服务，跑完再销毁。这样测试环境不再是一个近似物，而是与生产同构的数据库实例。

Testcontainers 本质上是一个 Java 库，通过 Docker API 管理容器生命周期。它和 JUnit 5 集成后，使用 @Container 或 @Testcontainers 注解声明容器，测试运行前启动容器，测试结束后销毁。对于 Spring Boot 项目，如果使用 Spring Boot 3.1 及以上版本，可以使用 @ServiceConnection 支持，自动把容器连接信息注入到上下文；如果还在旧版本，则需要通过 @DynamicPropertySource 动态覆盖 spring.datasource.url 等属性。两种方式最终都能让 Spring 上下文拿到真实数据库的连接参数，只是配置复杂度不同。

一、为什么 Testcontainers 比内嵌数据库更接近真实环境

内嵌数据库通常为了追求启动速度和纯 Java 运行，会牺牲一部分兼容性。以 H2 的 MySQL 兼容模式为例，很多 DDL 语句、时间函数、全文索引、JSON 函数都无法完全对齐，开发阶段测试通过，上线后却可能触发语法错误或性能问题。更重要的是，事务隔离级别在 H2 与 MySQL InnoDB 下的表现不同，一些依赖锁竞争的代码逻辑很难被覆盖到。

Testcontainers 通过启动真实数据库镜像解决这个问题。测试代码连接的是一套完整的 PostgreSQL、MySQL、MariaDB 或 SQL Server 服务，数据库版本可以精确指定。比如生产环境使用 MySQL 8.0.36，测试就可以拉取 mysql:8.0.36，甚至连字符集、时区、SQL 模式都可以在容器启动参数中保持一致。这样一来，集成测试不仅能验证 SQL 是否正确，还能验证驱动版本、连接池参数以及存储引擎行为。

当然，真实容器也会带来额外成本。首次拉取镜像需要时间，容器启动通常比 H2 慢几秒到十几秒。不过这个成本可以通过容器复用、预拉取镜像和并行执行来摊薄。对于一个需要长期维护的业务系统来说，多花几秒换取更高的测试可信度，通常是值得的。

二、在 Spring Boot 中接入 Testcontainers 的两种方式

先看依赖。Maven 工程除了常规的 spring-boot-starter-test，还需要引入 Testcontainers 的 JUnit 5 扩展和目标数据库容器模块。如果使用 Spring Boot 3.1+ 的 @ServiceConnection，还要加上 spring-boot-testcontainers。

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</artifactId>
    <scope>test</scope>
</dependency>

Spring Boot 3.1 引入的 @ServiceConnection 可以把容器连接信息自动映射到 DataSource 配置上，不需要手动处理 JDBC URL。测试类中声明一个静态 PostgreSQLContainer，加上 @Container 和 @ServiceConnection，Spring Test 会在上下文刷新前启动容器，并把连接属性注入到 spring.datasource。下面是一个仓库层的集成测试示例。

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.util.List;

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
@Testcontainers
class OrderRepositoryTest {

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

    @Autowired
    private OrderRepository orderRepository;

    @Test
    void shouldSaveAndLoadOrder() {
        Order order = new Order("A1001", 3);
        orderRepository.save(order);

        List<Order> result = orderRepository.findBySku("A1001");

        assertThat(result).hasSize(1);
        assertThat(result.get(0).getQuantity()).isEqualTo(3);
    }
}

对于 Spring Boot 3.0 及更早版本，或者不想依赖 spring-boot-testcontainers 模块时，可以使用 @DynamicPropertySource 手动注册连接参数。这种方式更通用，也能覆盖多数据源场景。

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.MySQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@SpringBootTest
@Testcontainers
class LegacyProductIntegrationTest {

    @Container
    static MySQLContainer<?> mysql =
            new MySQLContainer<>("mysql:8.0.36")
                    .withDatabaseName("shop")
                    .withUsername("admin")
                    .withPassword("secret");

    @DynamicPropertySource
    static void registerProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", mysql::getJdbcUrl);
        registry.add("spring.datasource.username", mysql::getUsername);
        registry.add("spring.datasource.password", mysql::getPassword);
        registry.add("spring.datasource.driver-class-name", mysql::getDriverClassName);
    }
}

两种方式的核心区别在于：@ServiceConnection 更贴近 Spring Boot 自动配置，代码更少；@DynamicPropertySource 更原始，适合需要自定义 URL 参数、连接多个数据库或使用非标准 DataSource 配置的项目。无论选择哪种，都要确保 Docker 守护进程可用，因为 Testcontainers 在运行时通过 Docker API 创建容器。

三、容器复用、数据初始化和测试提速

如果每个测试类都启动一个独立数据库容器，整个测试套件会变得很慢，而且容易耗尽 CI 机器资源。Testcontainers 支持容器复用，通过 withReuse(true) 可以让同一个镜像配置的容器在测试间复用，直到 JVM 退出。前提是需要配置 testcontainers.reuse.enable=true，可以放在用户目录下的 .testcontainers.properties 文件中。启用后，相同镜像、环境变量、暴露端口等条件的容器不会重复创建。

import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

@Testcontainers
abstract class AbstractPostgresContainer {

    @Container
    static final PostgreSQLContainer<?> POSTGRES =
            new PostgreSQLContainer<>("postgres:16-alpine")
                    .withDatabaseName("testdb")
                    .withUsername("test")
                    .withPassword("test")
                    .withReuse(true);

    static {
        POSTGRES.start();
    }
}

更常见的做法是使用单例容器模式：在一个抽象基类中启动一次静态容器，所有需要用数据库的测试类继承它。Spring Test 的上下文缓存机制会复用同一个 ApplicationContext，这样容器只启动一次，后续测试直接共享连接。需要注意的是，共享数据库意味着不同测试类之间的数据可能互相干扰，因此必须配合数据隔离策略。

数据初始化方面，Testcontainers 提供了 withInitScript，可以在容器启动后执行一段 SQL。对于复杂项目，更推荐直接让 Flyway 或 Liquibase 在应用启动时自动迁移，这样测试环境和生产环境走同一套迁移脚本，能顺便验证迁移本身的正确性。如果只想准备基础表，也可以在测试资源目录放置 schema.sql，再通过 withInitScript 引入。

@Container
static PostgreSQLContainer<?> postgres =
        new PostgreSQLContainer<>("postgres:16-alpine")
                .withDatabaseName("orders")
                .withUsername("test")
                .withPassword("test")
                .withInitScript("db/schema.sql");

最后一个常见问题是测试数据串扰。一种简单方案是给每个测试方法加 @Transactional，利用 Spring 事务在测试结束时回滚。但这只对常规 Service 层测试有效，如果测试代码自己提交了事务，或者使用了异步任务、存储过程，回滚就会失效。更稳的做法是在 @BeforeEach 中清空相关表，例如通过 JdbcTemplate 执行 TRUNCATE TABLE。也可以为每个测试类创建独立 schema，但这会增加启动和初始化成本。实践中通常是共享容器 + 事务回滚 + 有针对性的清理三类手段结合，才能在速度和隔离性之间取得平衡。

理解了容器生命周期、连接注入、初始化脚本和复用策略之后，Spring Boot 集成 Testcontainers 就不再是简单的测试工具替换，而是一套能稳定落地的数据库集成测试方案。上生产前，至少在真实数据库上把 SQL、事务和迁移都跑一遍，可以显著减少数据库相关的线上故障。

Spring BootTestcontainers数据库集成测试修改时间：2026-09-23 07:31:01