当前位置：首页 > 文章列表 > 文章 > java教程 > Spring Boot 集成测试别再只靠 H2：Testcontainers 落地踩坑复盘

Spring Boot 集成测试别再只靠 H2：Testcontainers 落地踩坑复盘

来源：17golang Java频道原创 2026-06-04 14:00:54 0浏览收藏

这篇写 Java 后端测试里一个很常见的坑：本地 H2 单测全绿，CI 或预发一连 PostgreSQL/MySQL 就翻车。字段默认值、SQL 方言、唯一约束、事务隔离、索引行为，全都可能和你想的不一样。Testcontainers 的价值不是“更时髦”，而是让集成测试尽早面对真实依赖。

本文适用于 Java 17/21、Spring Boot 3.x、JUnit 5、Testcontainers。资料只用于核对事实：Spring Boot 支持 Testcontainers service connection，Testcontainers 提供 JUnit Jupiter 集成。正文按工程落地写，不复述官方文档。

Testcontainers 集成测试思维导图 — 脑图：从场景、机制、数据、性能到 CI 门禁，把集成测试做成稳定资产。

业务场景：Repository 测试全绿，线上 SQL 却报错

订单服务有一批 Repository 测试，使用 H2 跑得很快。一次新增 JSON 字段和部分索引后，本地测试没问题，预发连 PostgreSQL 直接报 SQL 语法错误。问题不在业务代码，而在测试环境替你撒了一个温柔的谎：它根本不是生产数据库。

我不是说 H2 不能用。纯粹 DAO 映射、简单 CRUD、非常轻量的单元测试可以继续用。但只要你验证的是数据库方言、迁移脚本、约束、索引、事务行为，就应该尽量用真实容器。

问题复现：CI 偶发失败通常不是偶然

Testcontainers 刚接入时，团队最容易遇到三类问题：容器启动慢，测试数据互相污染，Spring Context 和容器生命周期混在一起导致偶发失败。表面看像 CI 不稳定，本质通常是测试边界没设计好。

比如 A 测试插入了固定手机号，B 测试也插入同一个手机号；本地按顺序跑没事，CI 并行后就撞唯一索引。真实数据库帮你暴露了问题，但测试代码必须负责隔离和清理。

Spring Boot Testcontainers 落地流程 — 落地流程：真实依赖、Spring 注入、迁移脚本、数据隔离和 CI 固化。

踩坑原因：只把容器跑起来还不够

很多文章停在“启动一个 PostgreSQLContainer”，但生产项目真正麻烦的是生命周期。容器是每个类一个，还是整个测试套件共用？数据库 schema 谁初始化？测试数据谁清？CI 没有 Docker 缓存怎么办？这些问题不回答，测试会越来越慢，最后被团队关掉。

我的原则是：少数核心集成测试用真实容器，覆盖最容易和生产不一致的路径；普通业务分支仍然用单元测试和 slice test 保持速度。不要把所有测试都塞进容器，也不要完全不用容器。

代码案例：Spring Boot 3 的 ServiceConnection 很香

Spring Boot 3.1 之后，@ServiceConnection 可以减少很多手写 JDBC URL 的样板代码。下面这个 Repository 测试会启动 PostgreSQL 容器，并把连接信息注入 Spring 测试上下文。

Spring Boot Testcontainers 代码对比 — 重点不是为了炫容器，而是让测试数据库行为和生产更接近。

@DataJpaTest
@Testcontainers
class OrderRepositoryTest {
    @Container
    @ServiceConnection
    static PostgreSQLContainer postgres =
        new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired OrderRepository repository;

    @Test
    void shouldRejectDuplicateOrderNo() {
        repository.save(new OrderEntity("NO-1001"));
        assertThatThrownBy(() -> repository.saveAndFlush(new OrderEntity("NO-1001")))
            .isInstanceOf(DataIntegrityViolationException.class);
    }
}

如果项目还没升级到支持 @ServiceConnection 的版本，可以用 @DynamicPropertySource 手动注入 spring.datasource.url、用户名和密码。关键是不要把容器端口写死，Testcontainers 会映射动态端口。