集成测试容器化:从 H2 假测试到真实 MySQL/Redis/Kafka 的完整实验
1. 学完你能做什么
读完并做完本文的四个动手任务,你应当能做到下面四件事:
- 能判断一个测试用例该用真实容器还是纯 JUnit,并说出判断依据落在哪条数据库语义上。
- 能写出一个容器基座,让 Spring 测试上下文复用容器,而不是每次
stop()之后再被复用。 - 能解释
@ServiceConnection为什么不覆盖配置文件、以及配置文件为什么会被静默忽略。 - 能为一个集成测试类选择数据隔离方案,并说明另外两种方案为什么在你这儿不成立。
前置条件:本机可用 Docker daemon、JDK 21 及以上、Maven 3.9 及以上。版本基线为 Spring Boot 4.0.9,它管理的 Testcontainers 版本是 2.0.5;截至 2026 年 11 月稳定线已到 4.1.x,主版本内的 API 未变。
动手前先对齐大版本
Testcontainers 2.0.0 于 2025 年 10 月 14 日发布,带破坏性变更:模块名统一加 testcontainers- 前缀,容器类从 org.testcontainers.containers.* 迁到 org.testcontainers.<模块>.*,JUnit 4 支持被移除。网上能搜到的示例代码绝大多数是 1.x,把依赖升到 2.x 之后会直接编译不过。本文所有代码按 2.x 写。
2. 一次「全绿」的发布,与这篇的坐标
2025 年 8 月,某电商的订单服务在发布后第 11 分钟触发唯一索引冲突告警,写入全部失败,回滚耗时 23 分钟。发布前的测试报告是 812 个用例全绿。
根因在一行代码上:where email = ? 在 H2(MODE=MySQL)里区分大小写,在 MySQL 8.4 的 utf8mb4_0900_ai_ci 下不区分。测试数据里只有 a@x.com,线上来了一个 A@x.com,唯一索引拒绝插入。测试没有失败,它只是通过了一个不存在的场景。
现在提问:如果 812 个用例全搬进容器,这次事故能拦住,但 CI 从 2 分钟变成 20 分钟,团队开始习惯性 -DskipTests——这笔交易划算吗?答案不是「要真实」,而是「哪一层值得付容器的代价」。
图 2-1 容器化集成测试在测试分层中的位置
3. 概念拆解:四个词要分清
镜像与容器,先分清最基础的一组。镜像是不可变的分层文件,容器是镜像加一个可写层加一组进程。测试里冻结的必须是镜像 tag,容器每次都是新的——这一条决定了后面所有隔离方案的设计。
连接细节(ConnectionDetails)是 Spring Boot 3.1 引入的抽象:它描述「怎么连到一个服务」,由自动配置消费。@ServiceConnection 的作用是让容器 Bean 自动产出一个 JdbcConnectionDetails、DataRedisConnectionDetails 或 KafkaConnectionDetails。反例是 3.0 之前的写法:用 @DynamicPropertySource 手工拼 jdbc:mysql://localhost:32768/app,端口随机,配置里写不住。
测试上下文(TestContext)是 Spring Test 的缓存单元。缓存键由 @ActiveProfiles、@TestPropertySource、@MockitoBean 组合、@ContextConfiguration 等共同决定,默认上限 32 个。这个概念在第 6 节会变成主要矛盾。
最后是生命周期归属。它只有两种:容器的 start()/stop() 由 JUnit 扩展调用,或由 Spring 容器调用。两者对上下文缓存的影响完全不同,见下图。
图 2-2 两条注册路径的生命周期差异
图里两条路径的差别不是代码风格。只有走 Spring 管理这一侧,「容器已停但上下文还在缓存」这个时间窗才不存在;而 90% 的「偶发 Connection refused」都出自这个时间窗。
四个词串起来是一条因果链。镜像 tag 固定,容器才能被重复创建;连接细节由容器 Bean 产出,配置里才不用手拼随机端口;生命周期交给 Spring,上下文复用时连接池才不会指向死掉的容器;上下文能否复用,取决于你的注解组合有没有制造出第 33 个缓存键。
四步里任何一步走错,症状都不会出现在走错的那一步上。这是这一章最需要你记住的结构。
4. 动手一:跑起来,并看它报错
先加依赖。版本全部留给 BOM,一个 <version> 都不要写。
<!-- Spring Boot 4.0.9:Testcontainers 由 spring-boot-dependencies 管理到 2.0.5 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-testcontainers</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-mysql</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-kafka</artifactId>
<scope>test</scope>
</dependency>
<!-- com.redis:testcontainers-redis,Boot 4.0.9 管理到 2.2.4 -->
<dependency>
<groupId>com.redis</groupId>
<artifactId>testcontainers-redis</artifactId>
<scope>test</scope>
</dependency>容器写成 Bean,交给 Spring 管:
// Spring Boot 4.0.9 + Testcontainers 2.0.5
@TestConfiguration(proxyBeanMethods = false)
class ContainerConfig {
// 2.0 的 MySQLContainer 已不是泛型类,写 MySQLContainer<?> 编译失败
@Bean
@ServiceConnection
MySQLContainer mysql() {
return new MySQLContainer("mysql:9.3.0") // 与生产同大版本,锁 patch
.withDatabaseName("app")
.withUsername("app")
.withPassword("app")
// 数据目录挂 tmpfs,初始化快一个量级
.withTmpFs(Map.of("/var/lib/mysql", "rw"))
.withStartupTimeout(Duration.ofMinutes(3));
}
// 镜像参数是 apache/kafka 或 apache/kafka-native;
// 用 confluentinc/cp-kafka 要换 ConfluentKafkaContainer,两者参数语义不同
@Bean
@ServiceConnection
KafkaContainer kafka() {
return new KafkaContainer("apache/kafka-native:3.8.0");
}
}跑第一个用例,看真实输出。第一次会比较久,镜像要下载:
$ mvn -Dtest=OrderFlowIT test
# 预期输出(首次运行,节选)
[INFO] Container mysql:9.3.0 is starting
[INFO] Container mysql:9.3.0 started in PT8.412S
[INFO] Container apache/kafka-native:3.8.0 started in PT3.107S
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 24.6 s
[INFO] BUILD SUCCESS第二次跑同一个类,耗时应降到 8 秒上下(镜像已在本地,容器仍会重建)。如果第二次还是 24 秒,问题几乎一定在上下文的缓存键上,不是启动参数。
这里容易卡住
@SpringBootTest 上同时叠 @Testcontainers 和 @Import(ContainerConfig.class) 是常见的错误组合。它能跑通,但容器归 JUnit 管:测试类结束就 stop(),上下文却还在缓存里。表现是第二个测试类偶发连接失败,单独跑又永远正常。
5. 动手二:确认连接信息从哪来
@ServiceConnection 会注册 JdbcConnectionDetails 等 Bean,自动配置消费它们时优先级高于配置文件里的连接属性。这意味着 application-test.yml 里写死的 spring.datasource.url 会被静默忽略——不是报错,是忽略。
验证方法很直接。在 application-test.yml 里故意写一个不存在的库名,然后跑测试:
# src/test/resources/application-test.yml
spring:
datasource:
url: jdbc:mysql://127.0.0.1:3306/this_db_does_not_exist
username: wrong
password: wrong$ mvn -Dtest=OrderFlowIT test
# 预期输出
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
# 配置全错,测试仍全绿 → 说明连接信息来自 @ServiceConnection,不是你写的 yml这一步不要跳过。团队里出现「我改了配置但没生效」的排查,八成绕回这里。
接着跑第二个反例,把容器 Bean 与 @DynamicPropertySource 混用:
// 反例:容器还没启动就去取端口
@SpringBootTest
@Import(ContainerConfig.class)
class WrongOrderFlowIT {
@DynamicPropertySource // 在上下文创建期执行,早于 Bean 初始化
static void props(DynamicPropertyRegistry registry) {
registry.add("spring.datasource.url",
() -> ContainerConfigHolder.MYSQL.getJdbcUrl());
}
@Test
void ping() { }
}$ mvn -Dtest=WrongOrderFlowIT test
# 预期输出
[ERROR] java.lang.IllegalStateException:
Mapped port can only be obtained after the container is started这个异常文本只有真踩过的人才记得住。它出现的位置在上下文装配阶段,堆栈长得像框架 bug,实际原因是你绕过了 @ServiceConnection 自己拿端口。
正确的顺序是让容器 Bean 先存在,再让自动配置去问它要连接信息。你不需要知道容器映射到哪个宿主机端口,那是 @ServiceConnection 的事。
这个设计有一个副作用值得提前知道。一旦测试里出现第二个数据源,@ServiceConnection 的自动绑定会变得模糊,此时要给它加 name 属性指定 Bean 名,否则两个数据源的连接细节互相覆盖。症状是其中一个库的查询打到另一个库上——两套 schema 恰好相似时,很难发现。
6. 动手三:隔离数据,同时别让上下文爆炸
这两个目标天然冲突。能同时成立的组合只有一个:容器复用 + 上下文复用 + 数据按测试清理。绝不是「每个测试类重建容器」。
| 方案 | 覆盖范围 | 失效场景 | 代价 |
|---|---|---|---|
@Transactional 回滚 | 同线程、同连接 | REQUIRES_NEW、异步线程、Kafka 消费者看到的数据不回滚 | 最省事,自增 ID 不复位 |
@BeforeEach 清库 | 全量 | 外键顺序要手工处理 | TRUNCATE 隐式提交,不能与事务混用 |
| 每类独立 schema / topic | 全量 | 清理逻辑分散 | 上下文数量上升 |
// 每个测试方法前复位;TRUNCATE 隐式提交,别和外层事务混用
@BeforeEach
void resetState(@Autowired JdbcTemplate jdbc,
@Autowired StringRedisTemplate redis) {
jdbc.execute("SET FOREIGN_KEY_CHECKS = 0");
for (String table : List.of("order_items", "orders")) {
jdbc.execute("TRUNCATE TABLE " + table);
}
jdbc.execute("SET FOREIGN_KEY_CHECKS = 1");
try (RedisConnection connection = redis.getConnectionFactory().getConnection()) {
connection.serverCommands().flushDb(); // 不是 flushAll
}
}Redis 这里有个具体判断:共享实例上不要用 FLUSHALL,它会连你同事本地调试用的第 3 号库一起清掉。Kafka 更干脆——它没有「清空」能力,只能靠每个测试类独立 topic 加独立 consumer group,别指望删 topic 来清状态。
顺带给出本文唯一一条明确的不建议:不要把容器复用开关(testcontainers.reuse.enable=true)带进 CI。它在本地能把二次运行压到 3 秒以内,确实好用;但复用容器意味着测试之间的状态不再干净,本机残留数据会在下一次运行里变成难以复现的失败。
而且它的命中条件苛刻。镜像、端口映射、环境变量必须完全一致,改一个环境变量就静默地变成新建容器——你以为在跑复用,其实没有。
CI 上的正确做法是把镜像在前置步骤统一 docker pull,让每个测试 fork 都能命中本地镜像层。
启动耗时的大头往往不是容器。跑下面这条,看上下文到底起了几个:
$ mvn verify -DargLine="-Dlogging.level.org.springframework.test.context.cache=DEBUG -Dspring.test.context.cache.maxSize=64"
# 预期输出(节选)
[DEBUG] Spring test ApplicationContext cache statistics:
[DefaultContextCache@1b2c3d size = 7, maxSize = 64, parentContextCount = 0, hitCount = 41, missCount = 7]size 稳定在个位数才算正常。如果它逼近上限,说明每个测试类的注解组合都不一样,最老的上下文被淘汰,容器跟着重建——把差异收敛到一个抽象基类,比调任何容器参数都有效。另外 Surefire 保持 forkCount=1、reuseForks=true,JVM 一分叉,静态上下文缓存就清零。
7. 三个常见误解
很多人以为 H2 加 MODE=MySQL 就接近真实了,实际上它只是一个宽松的近似,因为 ONLY_FULL_GROUP_BY、隔离级别默认值、collation 三样它都不模拟。测试通过而线上报错,来源就在这三处。
很多人以为容器越真越好,实际上 DTO 序列化、参数校验、Controller 路由这类测试放容器纯属浪费,因为它们不依赖任何外部状态。
很多人以为本地 Compose 和测试容器可以共存,实际上 Spring Boot 的 Compose 支持在测试中默认关闭,强行打开 spring.docker.compose.skip.in-tests=false 会让测试先 docker compose up 再起一套 Testcontainers,端口打架、容器双份。多模块共享同一份 compose 时,还要把 spring.docker.compose.lifecycle-management 从默认的 start-and-stop 改成 start-only,否则先退出的应用会把别人还在依赖的服务一起停掉。
8. 留给你的三个场景
第一题。你有一个测试类,用 @Bean 注册 MySQL 容器,另有一个测试类只加了 @MockitoBean 一个字段。两者会命中同一个上下文缓存吗?如果把 @MockitoBean 挪到基类里,上下文数量会变成几个?
第二题。团队只允许你在 20 分钟 CI 预算里分给集成测试 6 分钟。现有 3 个测试类,分别依赖 MySQL、MySQL+Redis、MySQL+Redis+Kafka。你会怎么切分容器声明?
第三题。给一个只在 native 镜像上出现的连接失败写排查步骤——提示:先怀疑端口与架构,再怀疑代码。
9. 六个词的中英对照
| 中文 | 英文 | 一句话解释 |
|---|---|---|
| 连接细节 | ConnectionDetails | 描述「如何连到某服务」的抽象,由自动配置消费 |
| Ryuk | Ryuk | Testcontainers 的资源回收容器,测试 JVM 异常退出时兜底清理 |
| 上下文缓存 | ApplicationContext cache | Spring Test 复用上下文的机制,键由注解组合决定 |
| 分组 ID | consumer group | Kafka 消费位点的隔离单位,测试间互相串台的主因 |
| 就绪等待 | startup timeout | 容器启动的上限等待,CI 冷机要比本地放宽 |
| 分叉 | fork | Surefire 启动独立 JVM 跑测试,会清空静态缓存 |