作者:谢星河-288|测试开发|15 年,关注工程规范与可维护性 栈:Java 17 + JUnit 5.10.2 + Mockito 5.11.0 + Spring Boot 3.1.5,CI 用 GitLab Runner(2 台 4C8G),并行度 4(
junit.jupiter.execution.parallel.config.fixed.parallelism=4)
一、现象与背景:单跑必绿、全量偶红,重跑顺序一变就搬家
先给一组数字。我维护一条结算链路的接口测试套件,1400 个用例,2025 年 Q1 三个月里:
- 全量回归每周 8–14 次「单跑通过、全量失败」的偶现,其中 7 类失败签名反复出现(金额格式化串位、时区偏移 8 小时、某静态 mock 返回上一个用例的 stub 值、临时目录文件残留导致
FileAlreadyExistsException等); - 最贵的一次:一条「汇率换算」用例在周一红、周二绿、周三又在另一个用例上红——失败点会「搬家」,团队当时归因是「用例顺序依赖」,排查了 3 天没定位;
- 累计人工排查成本 200+ 分钟/月,且 2 次真回归被「重跑变绿」掩盖,直到线上报警才回头补用例。
关键判断:这些失败与用例执行顺序强相关,但根因不是用例之间的数据依赖(数据依赖我们上一轮已经用 schema 隔离 + 事务回滚治掉了),而是测试代码本身在 JVM 进程内制造了「副作用泄漏」——前一个用例改了全局状态,后一个用例在不知情的前提下读到了脏值。
二、根因分析:为什么一个 JVM 进程里会「串味」
JUnit 5 默认把整个测试模块跑在同一个 JVM、同一批 ClassLoader 里,所有用例共享四块「全局内存」:
- 系统属性(
System.getProperties())——任何线程、任何时刻改,全进程可见; - Locale / TimeZone 默认值(
Locale.setDefault、TimeZone.setDefault)——被SimpleDateFormat、NumberFormat、DateTimeFormatter隐式消费; - 静态字段与静态 mock(
Mockito.mockStatic、单例的 static 成员)——生命周期 = 类加载期到 JVM 退出; - ThreadLocal 与线程池——并行执行时,工作线程被复用于不同用例。
叠加两个放大器,泄漏就从「逻辑 bug」变成「概率性 flaky」:
- JVM 启动顺序非确定:surefire 在 CI 上的类加载顺序受文件系统、并行调度影响,同一套代码,周一和周三的「谁先谁后」可以不同——这就是失败点「搬家」的机制;
- JIT + GC 停顿:4C8G 的 runner 上 1400 个用例的老年代在跑到 800 用例左右会触发 Full GC(实测 STW 峰值 210ms),此时正在
Thread.sleep或轮询等待的用例,窗口被整体平移,原本 200ms 能等到、变成 250ms 才等到——sleep 型断言对 GC 停顿天然敏感。
一句话:测试代码里任何一处「写全局、读全局」,都在把「用例独立」这个前提悄悄打破;JIT 与调度只是让打破的时机变得不可预测。
三、六类泄漏清单 + 可复现的扫描与修复
3.1 泄漏清单(按我们踩中频率排序)
| # | 泄漏源 | 典型症状 | 修复 |
|---|--------|---------|------|
| 1 | Locale.setDefault / TimeZone.setDefault 无恢复 | 金额小数点变逗号、日期偏移 ±8h | 用 Extension 快照/恢复 |
| 2 | System.setProperty 无恢复 | 后一个用例读到前一个的配置 | 同上,快照 Map |
| 3 | Mockito.mockStatic 未 close | 静态方法返回上用例 stub 值 | try-with-resources + 全局扫描 |
| 4 | ThreadLocal.set 未 remove | 并行下跨用例串值 | 统一 wrapper + @AfterEach remove |
| 5 | 临时目录/文件残留 | FileAlreadyExistsException | @TempDir 或唯一 UUID 前缀 |
| 6 | 静态单例内部状态(缓存、计数器) | 计数类断言差 1 | 提供 resetForTest() 并在 @BeforeAll 调用 |
3.2 用 ArchUnit 把「禁止写全局」变成编译期规则
@AnalyzeClasses(packages = "com.example.it")
class TestHygieneRules {
@ArchTest
static final ArchRule tests_must_not_set_default_locale =
noClasses().that().resideInAPackage("..it..")
.should().callMethod(Locale.class, "setDefault", Locale.class)
.as("用例禁止直接调用 Locale.setDefault,请用 LocaleGuardExtension");
@ArchTest
static final ArchRule tests_must_not_set_system_property =
noClasses().that().resideInAPackage("..it..")
.should().callMethodWhere(
target().isRawType(System.class)
.and().name().anyOf("setProperty", "clearProperty"))
.as("用例禁止改 System property,请用 PropertyGuardExtension");
@ArchTest
static final ArchRule static_mock_must_be_scoped =
noClasses().should().callMethodWhere(
target().isRawType(Mockito.class).and().name().isEqualTo("mockStatic"))
.allowingChildren(0)
.as("mockStatic 只允许出现在白名单类(如 Clock 门面)");
}
实测:这三条规则在 1400 个用例里一次性揪出 11 处违规(8 处 Locale.setDefault、2 处 setProperty、1 处裸 mockStatic),其中 2 处正是周一/周三「搬家」失败的元凶。
3.3 两个「快照-恢复」Extension(可直接抄)
public class LocaleGuardExtension implements BeforeEachCallback, AfterEachCallback {
private Locale locale; private TimeZone tz;
@Override public void beforeEach(ExtensionContext ctx) {
locale = Locale.getDefault(); tz = TimeZone.getDefault();
Locale.setDefault(Locale.ROOT); TimeZone.setTimeZone("UTC"); // 统一基线
}
@Override public void afterEach(ExtensionContext ctx) {
Locale.setDefault(locale); TimeZone.setTimeZone(tz);
}
}
PropertyGuardExtension 同理:beforeEach 里 System.getProperties().entrySet().stream().filter(e -> e.getKey().startsWith("app.")) 快照,afterEach 逐条 put 回原值、clearProperty 删新增项。注意恢复的是「原值」而不是「删除」——生产默认值本来就可能存在,删了反而引入新泄漏。
3.4 ThreadLocal 的统一出口
public final class BizContext {
private static final ThreadLocal<UserRef> H = new ThreadLocal<>();
public static void set(UserRef r) { H.set(r); }
public static UserRef get() { return H.get(); }
public static void clear() { H.remove(); } // 唯一允许 remove 的入口
}
配一条 JUnit @AfterEach 全局钩子(@ExtendWith(RegisteredExtension) 或 surefire 的 runOrder 无关,直接用 JUnitPlatform.launcher 的 TestExecutionListener):
public class ThreadLocalSweeper implements TestExecutionListener {
@Override public void executionFinished(TestIdentifier id, ExecutionResult r) {
BizContext.clear();
// 其他 ThreadLocal 统一在这里清
}
}
3.5 临时文件的两个铁律
- 永远用
@TempDir Path tmp,不要new File("/tmp/xxx")固定名——CI 上并行度 4 时,两个用例同秒起同名文件,FileAlreadyExistsException直接翻车(我们踩过 2 次); - 必须用固定路径时(某些 SDK 只读配置目录),前缀加
UUID.randomUUID(),并在@AfterEach里递归删——删失败要fail(),不能吞,否则残留文件在下一轮 CI 里继续污染。
四、踩过的坑(反直觉清单)
- ❌
@AfterEach里恢复 Locale 没用——因为泄漏发生在用例中途抛异常时,@AfterEach会执行,但如果用例在静态初始化块里就改了 Locale(比如某个工具类的static { Locale.setDefault(...) }),@AfterEach恢复的是「被污染后」的默认值,等于没恢复。正解:@BeforeAll里强制Locale.setDefault(Locale.ROOT)打基线,再快照。 - ❌ Mockito 的
mockStatic用@MockitoSettings或字段注入——字段注入的 static mock 生命周期跟着 mock 对象走,一旦对象被 GC 或复用,行为不可预期。正解:try (MockedStatic<X> m = Mockito.mockStatic(X.class)) { ... }作用域化,且用 ArchUnit 白名单锁住调用点。 - ❌ 以为「每个用例一个新线程」就隔离了 ThreadLocal——JUnit 并行用的是固定线程池(默认 = CPU 核数),线程被复用,ThreadLocal 值会跨用例存活。必须显式
remove()。 - ❌ 在
@BeforeAll里造数据、在@AfterAll里清数据——并行度 >1 时,A 类的@AfterAll可能比 B 类的@BeforeAll先执行(取决于调度),清理了 B 类还没用完的数据。正解:数据生命周期跟着用例走,用@BeforeEach/@AfterEach或 per-test 事务。
五、Java 21 虚拟线程:ThreadLocal 的「继承语义」变了,你的 Sweeper 可能静默失效
2025 年 Q2 我们把部分 IO 密集型用例从 CompletableFuture.supplyAsync(平台线程池)迁到 Thread.ofVirtual().start(...) 后,ThreadLocalSweeper 的 executionFinished 钩子对虚拟线程完全失效——原因不是 JUnit 的 bug,而是虚拟线程的生命周期和平台线程不同:
问题复现(Java 21.0.2 + JUnit 5.10.2):
@Test
void virtualThreadLeak() {
// 用例 A:启动虚拟线程,设置 ThreadLocal
Thread v = Thread.ofVirtual().start(() -> {
BizContext.set(UserRef.of("user-A"));
// 模拟 IO 阻塞
Thread.sleep(100);
});
v.join(); // 用例 A 结束,平台线程回收
// 用例 B:复用同一个 carrier 线程(fork-join pool)
// BizContext.get() 返回 "user-A" ← 泄漏!
// ThreadLocalSweeper 的 executionFinished 只挂在 JUnit 的 TestIdentifier 上,
// 不感知虚拟线程的创建/销毁
}
根因:虚拟线程跑在 ForkJoinPool 的 carrier thread 上。JUnit 的 TestExecutionListener.executionFinished 只对「用例方法所在的平台线程」触发回调,虚拟线程内部的 ThreadLocal.set 写在 carrier thread 的 ThreadLocalMap 里,但 JUnit 不知道这个 carrier 被哪个用例的虚拟线程借用过。
修复方案(三选一,按侵入性排序):
-
最低侵入:用
ScopedValue(Java 21 预览 / Java 25 正式)替代ThreadLocal。ScopedValue的生命周期绑定try (scopedValue.run(...))作用域,虚拟线程退出时自动清除,不需要手动remove():static final ScopedValue<UserRef> USER = ScopedValue.newInstance(); // 用例里 USER.run(UserRef.of("user-A"), () -> { /* ... */ }); // 出作用域即清除注意:
ScopedValue不支持「运行时 set」,只能在run入口传入。如果你的业务代码到处BizContext.set(...),迁移成本高。 -
中等侵入:在
ThreadLocalSweeper里加一个 carrier thread 级别的清理钩子:// 利用 Thread.onSpinWait + 轮询(不优雅但能用) // 更好的方式:用 JDK 21 的 Thread.onPark() 回调 // 或者:在虚拟线程启动前包一层 static Runnable wrapForVirtual(Runnable task) { return () -> { try { task.run(); } finally { BizContext.clear(); } // 虚拟线程退出时清理 }; }缺点:需要改所有
Thread.ofVirtual().start(...)的调用点。 -
推荐(工程化):加一条 ArchUnit 规则,禁止在测试代码里直接创建虚拟线程,强制走一个
VirtualThreadTestRunner门面,内部自动包finally { BizContext.clear(); }:@ArchTest static final ArchRule tests_must_use_virtual_runner = noClasses().that().resideInAPackage("..it..") .should().callMethodWhere( target().isRawType(Thread.class).and().name().isEqualTo("ofVirtual")) .as("测试代码禁止直接创建虚拟线程,请用 VirtualThreadTestRunner");
数据:迁移后跑了 2 周,1400 个用例里原来 3 个「偶现 ThreadLocal 串值」的用例(每 10 次全量回归红 1 次)全部消失,flaky rate 从 0.21% 降到 0.04%。
六、落地 Checklist(给团队直接抄)
| # | 检查项 | 工具 | 状态 |
|---|--------|------|------|
| 1 | 用例代码禁止 Locale.setDefault / TimeZone.setDefault | ArchUnit | ✅ 11 处已修 |
| 2 | 用例代码禁止 System.setProperty / clearProperty | ArchUnit | ✅ 2 处已修 |
| 3 | mockStatic 必须在 try-with-resources 作用域内 | ArchUnit + Code Review | ✅ 1 处已修 |
| 4 | 所有 ThreadLocal 走统一出口 + @AfterEach 清理 | BizContext + Sweeper | ✅ |
| 5 | 临时文件用 @TempDir,删失败必须 fail() | Code Review | ✅ |
| 6 | 静态单例提供 resetForTest() | Code Review | ✅ |
| 7 | 虚拟线程必须走 VirtualThreadTestRunner(Java 21+) | ArchUnit | ✅ |
| 8 | CI 并行度 ≤ CPU 核数,避免 carrier 线程复用放大泄漏 | GitLab CI 配置 | ✅ |
最后一句话:flaky test 的 80% 不是「测试写得不好」,而是「测试代码在 JVM 进程里制造了全局副作用,然后祈祷调度顺序别变」。把「禁止写全局」变成编译期规则,比写 100 个 @AfterEach 清理代码更可靠。