1. 项目概述为什么我们需要 JUnit 5 扩展模型如果你写过一段时间的 Java 单元测试尤其是用过 JUnit 4那你肯定对RunWith、Rule这些概念不陌生。它们很强大能帮我们做很多事比如启动 Spring 容器、管理数据库事务或者自定义测试的运行方式。但用久了你会发现这些机制有点“各自为政”规则Rule的生命周期和 Runner 的生命周期交织在一起有时候想实现一个复杂点的定制化需求代码会变得很绕甚至需要去 hack 框架的内部实现。JUnit 5 的 Extension 模型就是为了解决这些问题而生的。它不是一个全新的东西你可以把它看作是 JUnit 4 中Runner、Rule、ClassRule等概念的现代化、统一化的重构。它的核心思想是“关注点分离”和“声明式编程”。框架定义了一系列清晰的生命周期节点比如“所有测试执行前”、“解析测试方法参数时”、“每个测试方法执行后”等然后我们作为开发者只需要实现对应的接口并告诉 JUnit“嘿在这个节点上请执行我的这段逻辑”。框架会负责在正确的时机调用我们的代码。这带来的好处是巨大的。首先扩展之间是解耦的你可以组合使用多个扩展而不用担心它们互相冲突。其次API 设计得非常清晰每个接口的职责单一比如BeforeAllCallback就只管“所有测试执行前”这件事ParameterResolver就只管“如何给测试方法提供参数”这件事。最后它极大地提升了可测试性因为你的扩展本身也是普通的 Java 对象可以很方便地进行单元测试。今天我们就聚焦于两个非常常用且强大的扩展点BeforeAllCallback和ParameterResolver。前者用于在整个测试类开始前执行一次性初始化后者用于在每个测试方法执行时动态地为其提供参数。掌握了它们你就能解决测试中诸如“初始化昂贵资源”、“依赖注入”、“动态生成测试数据”等一系列棘手问题。2. 核心扩展点深度解析BeforeAllCallback 与 ParameterResolver2.1 BeforeAllCallback全局一次性初始化的利器BeforeAllCallback接口只定义了一个方法void beforeAll(ExtensionContext context)。顾名思义它会在标注了Test、RepeatedTest、ParameterizedTest等注解的测试类中所有测试方法执行之前被调用一次。注意是每个测试类调用一次而不是整个测试套件。它的典型应用场景有哪些呢启动外部服务比如启动一个内嵌的 Redis、Kafka 或者数据库如 Testcontainers并获取连接配置。初始化静态资源创建一些昂贵的、只读的、需要在所有测试间共享的资源例如一个大型的测试数据文件加载到内存中。全局配置设置设置一些系统属性、环境变量或者初始化某些全局工具类。执行数据库迁移在运行测试前执行 Liquibase 或 Flyway 脚本确保数据库 schema 是最新的。它与 JUnit 4 的BeforeClass有何不同BeforeClass是测试类内部的一个静态方法其逻辑与测试类强耦合。而BeforeAllCallback是一个独立的扩展可以被多个测试类复用实现了逻辑与测试类的解耦。你可以把它打包成一个独立的 Jar在所有项目中共享。注意BeforeAllCallback的执行时机是在测试类实例化之前。这意味着在beforeAll方法中你无法通过ExtensionContext获取到测试类的实例因为还没创建但可以获取到测试类的Class对象、唯一ID、显示名称等信息。2.2 ParameterResolver动态参数注入的艺术ParameterResolver接口定义了两个方法boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext): 判断当前解析器是否支持为某个参数提供值。Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext): 如果支持则返回参数的具体值。它的核心价值在于让测试方法参数化变得极其灵活。在 JUnit 4 中测试方法通常是无参的你要么通过字段注入依赖要么在方法内部构造数据。JUnit 5 允许测试方法有参数而ParameterResolver就是那个背后的“魔法师”负责在运行时决定这些参数的值。它的应用场景更加广泛依赖注入模拟 Spring 的Autowired为测试方法注入诸如UserRepository、RestTemplate这样的 Bean。测试数据工厂根据参数类型动态生成测试数据对象。比如参数类型是Product就自动创建一个随机的、有效的Product实例。上下文信息传递将BeforeAllCallback中初始化的资源如数据库连接传递给每个测试方法。与ParameterizedTest结合自定义参数源从文件、数据库或远程 API 获取参数化测试的数据。一个关键点是执行顺序。对于同一个测试方法中的多个参数JUnit 5 会遍历所有已注册的ParameterResolver扩展为每个参数寻找第一个supportsParameter返回true的解析器。这意味着你可以定义多个解析器并通过supportsParameter方法精确控制它们的职责范围。3. 手把手实现自定义扩展理解了原理我们动手实现两个具体的扩展。假设我们有这样一个需求在测试类开始时初始化一个模拟的 HTTP 服务器用于测试 HTTP 客户端并将这个服务器的基地址Base URL动态注入到每个需要它的测试方法中。3.1 实现 BeforeAllCallback启动模拟服务器首先我们创建一个扩展MockServerExtension它将在所有测试前启动一个 WireMock 服务器。import org.junit.jupiter.api.extension.BeforeAllCallback; import org.junit.jupiter.api.extension.ExtensionContext; import com.github.tomakehurst.wiremock.WireMockServer; import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig; public class MockServerExtension implements BeforeAllCallback, ExtensionContext.Store.CloseableResource { private static WireMockServer wireMockServer; private static final String SERVER_KEY wireMockServer; Override public void beforeAll(ExtensionContext context) { // 确保只初始化一次对于嵌套测试类等情况 if (wireMockServer null) { System.out.println([MockServerExtension] 启动 WireMock 服务器...); wireMockServer new WireMockServer(wireMockConfig().dynamicPort()); wireMockServer.start(); // 将服务器实例存储到全局 Store 中以便其他扩展或测试访问 context.getRoot().getStore(ExtensionContext.Namespace.GLOBAL) .put(SERVER_KEY, wireMockServer); // 注册一个回调在测试结束后关闭服务器 context.getRoot().getStore(ExtensionContext.Namespace.GLOBAL) .put(this.getClass().getName(), this); } // 可以为服务器配置一些默认的 Stub桩响应 configureDefaultStubs(); } private void configureDefaultStubs() { // 使用 wireMockServer 实例配置一些所有测试共用的默认响应 // 例如stubFor(get(urlEqualTo(/api/health)).willReturn(ok())); } Override public void close() { if (wireMockServer ! null wireMockServer.isRunning()) { System.out.println([MockServerExtension] 关闭 WireMock 服务器...); wireMockServer.stop(); wireMockServer null; } } // 提供一个静态方法方便在其他地方获取服务器信息非必须 public static String getBaseUrl() { return wireMockServer null ? null : http://localhost: wireMockServer.port(); } }代码解读与注意事项实现CloseableResource我们同时实现了CloseableResource接口它的close()方法会在该存储区Store的生命周期结束时被调用。我们将自身实例存入GLOBAL命名空间的 Store从而确保在所有测试完成后能执行关闭服务器的逻辑。这是一种优雅的资源清理模式。使用StoreExtensionContext.Store是扩展之间、扩展与测试之间共享数据的核心机制。这里我们使用GLOBAL命名空间存储服务器实例使其在整个测试运行期间都可用。静态变量与并发这里使用static变量来保存服务器实例是基于“一个 JVM 进程内一次测试运行只启动一个服务器”的假设。如果你的测试是并行运行的并且希望每个测试类有独立的服务器就不能用static而应该将实例存储在context.getStore(ExtensionContext.Namespace.create(...))创建的非全局 Store 中。这是设计扩展时需要仔细考虑的一点。3.2 实现 ParameterResolver注入服务器基地址接下来我们实现一个解析器将上面启动的服务器的基地址注入到测试方法参数中。import org.junit.jupiter.api.extension.ExtensionContext; import org.junit.jupiter.api.extension.ParameterContext; import org.junit.jupiter.api.extension.ParameterResolver; import com.github.tomakehurst.wiremock.WireMockServer; import java.lang.annotation.ElementType; import.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; // 自定义一个注解用来标记需要注入基地址的参数 Target(ElementType.PARAMETER) Retention(RetentionPolicy.RUNTIME) public interface MockServerUrl { } // 参数解析器实现 public class MockServerUrlParameterResolver implements ParameterResolver { Override public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) { // 支持标注了 MockServerUrl 注解的 String 类型参数 return parameterContext.isAnnotated(MockServerUrl.class) parameterContext.getParameter().getType().equals(String.class); } Override public Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) { // 从全局 Store 中获取 WireMockServer 实例 WireMockServer server (WireMockServer) extensionContext.getRoot() .getStore(ExtensionContext.Namespace.GLOBAL) .get(wireMockServer); if (server null) { throw new IllegalStateException(WireMockServer 未初始化。请确保 ExtendWith 包含了 MockServerExtension。); } // 返回服务器的基地址 return http://localhost: server.port(); } }代码解读与设计思路自定义注解我们创建了MockServerUrl注解。这是一种非常优雅的模式它让测试方法的意图更加清晰。通过注解我们明确表达了“这个参数需要被注入模拟服务器的 URL”而不是通过参数类型等隐式规则。supportsParameter逻辑这里我们要求参数同时满足两个条件被MockServerUrl注解标记并且类型是String。这样设计非常精确避免了误匹配。依赖MockServerExtension在resolveParameter中我们通过ExtensionContext从全局 Store 里获取服务器实例。这建立了一个扩展对另一个扩展的弱依赖MockServerUrlParameterResolver期望MockServerExtension已经运行并将服务器存入 Store。如果顺序错了或忘了注册运行时会抛出清晰的异常。这种设计比强编译时耦合更灵活。3.3 在测试类中使用扩展最后我们看看如何在测试类中应用这两个扩展。import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import static org.junit.jupiter.api.Assertions.assertTrue; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; // 通过 ExtendWith 注册扩展。顺序无关紧要JUnit 会按生命周期智能调度。 ExtendWith({MockServerExtension.class, MockServerUrlParameterResolver.class}) class MyHttpClientTest { Test void testApiEndpoint(MockServerUrl String serverUrl) throws Exception { // 现在 serverUrl 已经被动态注入了例如 http://localhost:54321 HttpClient client HttpClient.newHttpClient(); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(serverUrl /api/test)) .GET() .build(); // 假设 MockServerExtension 为 /api/test 配置了响应 HttpResponseString response client.send(request, HttpResponse.BodyHandlers.ofString()); assertTrue(response.statusCode() 200); // ... 更多的断言 } // 另一个测试方法同样可以注入 serverUrl Test void testAnotherEndpoint(MockServerUrl String serverUrl) { System.out.println(使用服务器地址: serverUrl); // ... 测试逻辑 } }实操心得扩展的注册方式除了在类级别用ExtendWith你还可以通过RegisterExtension字段用于编程式配置或者在src/test/resources/META-INF/services目录下创建org.junit.jupiter.api.extension.Extension文件进行自动注册。自动注册对于公司内部共享的通用扩展库非常有用。测试实例生命周期ParameterResolver是在每个测试方法执行前为该测试方法解析参数。它发生在BeforeEach方法之后。这意味着你可以在BeforeEach中准备一些数据然后通过ParameterResolver以更类型安全的方式传递给测试方法。4. 高级技巧与组合使用4.1 处理扩展的依赖与执行顺序有时你的多个扩展之间存在依赖关系。比如一个DatabaseInitializationExtensionBeforeAllCallback需要在FlywayMigrationExtension也是BeforeAllCallback之后运行。JUnit 5 提供了Order注解来控制同一生命周期阶段内扩展的执行顺序。import org.junit.jupiter.api.Order; import org.junit.jupiter.api.extension.BeforeAllCallback; Order(1) // 数字小的先执行 public class FlywayMigrationExtension implements BeforeAllCallback { // ... 执行数据库迁移 } Order(2) public class DatabaseInitializationExtension implements BeforeAllCallback { // ... 初始化基础数据依赖迁移后的 schema }在ExtendWith中声明的顺序对于BeforeAllCallback这类扩展也有效但使用Order是更明确和推荐的方式。4.2 基于条件的扩展执行你可能希望扩展只在特定条件下才生效。JUnit 5 的ExecutionCondition扩展接口专门用于此目的。你可以让你的扩展同时实现BeforeAllCallback和ExecutionCondition。public class ConditionalMockServerExtension implements BeforeAllCallback, ExecutionCondition { Override public ConditionEvaluationResult evaluateExecutionCondition(ExtensionContext context) { String profile System.getProperty(test.profile); if (integration.equals(profile)) { return ConditionEvaluationResult.enabled(集成测试环境启用模拟服务器。); } return ConditionEvaluationResult.disabled(非集成测试环境禁用模拟服务器。); } Override public void beforeAll(ExtensionContext context) { // ... 启动服务器的逻辑 } }这样只有当系统属性test.profile为integration时这个扩展才会被激活。4.3 与 Spring 等大型框架集成在 Spring Boot 测试中你通常使用SpringBootTest。JUnit 5 的扩展模型与 Spring 的TestExecutionListener机制可以协同工作。Spring 本身提供了一个SpringExtension它就是一个强大的ParameterResolver负责注入 Spring 容器中的 Bean。你可以将自己的扩展与SpringExtension一起使用。只需要确保你的扩展在需要时能访问到 Spring 的ApplicationContext。一种常见做法是通过ExtensionContext存储来传递上下文或者让你的扩展感知 Spring 的测试上下文管理器。ExtendWith({SpringExtension.class, MyCustomExtension.class}) SpringBootTest class SpringIntegrationTest { Test void testWithSpringAndCustomExtension(Autowired MyService service, MyCustomParam SomeValue customValue) { // service 由 SpringExtension 注入customValue 由 MyCustomExtension 注入 } }5. 常见问题排查与实战陷阱在实际使用中你可能会遇到一些意想不到的情况。下面是一些典型问题及其解决方案。5.1 问题BeforeAllCallback 执行了多次现象你发现beforeAll方法里的日志打印了多次或者资源被重复初始化。原因嵌套测试类NestedJUnit 5 中每个静态嵌套测试类都会触发一次BeforeAllCallback。如果你在父类上使用了ExtendWith那么父类和每个嵌套类都会执行。扩展被重复注册可能通过ExtendWith、RegisterExtension和自动注册META-INF/services多种方式重复注册了同一个扩展。静态变量处理不当在并行测试模式下如果扩展没有正确管理状态可能导致初始化逻辑被多个线程执行。排查与解决对于嵌套类考虑是否真的需要在每个嵌套类前都初始化。如果不需要可以将扩展移到具体的测试方法层级或者使用ExtensionContext的存储机制配合唯一键来确保逻辑只执行一次就像我们示例代码中检查wireMockServer null那样。检查扩展的注册方式确保唯一。在并行测试中避免使用可变的静态变量。使用ExtensionContext.Store并选择适当的命名空间如Namespace.create(getClass(), context.getUniqueId())来保存线程隔离的状态。5.2 问题ParameterResolver 不生效现象测试方法的参数没有得到注入值为null或者 JUnit 抛出ParameterResolutionException。原因扩展未注册忘记使用ExtendWith将ParameterResolver实现注册到测试类。supportsParameter条件太严格或太宽松你的supportsParameter方法返回了false导致 JUnit 认为该解析器不支持此参数或者有其他解析器先于你的解析器返回了true。参数类型或注解不匹配测试方法参数的类型或注解与supportsParameter中的判断逻辑不匹配。与框架自带解析器冲突例如Spring 的SpringExtension也可能尝试解析参数如果它的supportsParameter先返回true你的解析器就不会被调用。排查与解决首先在supportsParameter方法开始处添加调试日志打印参数信息和判断结果。使用ExtendWith明确注册你的解析器并注意注册顺序。排在后面的扩展优先级更高不JUnit 是顺序遍历第一个返回true的获胜。所以通用的解析器应该放在后面具体的解析器放在前面。确保你的自定义注解的Retention是RUNTIME否则 JUnit 在运行时无法读取到它。如果与 Spring 等框架冲突可以尝试让你的解析器更具体例如要求同时具备自定义注解和特定类型或者调整扩展注册顺序。5.3 问题资源泄漏如数据库连接未关闭现象测试运行后端口未释放文件锁未解除或数据库连接数耗尽。原因在BeforeAllCallback或BeforeEachCallback中打开的资源没有在对应的AfterAllCallback或AfterEachCallback中关闭。解决成对实现生命周期回调接口如BeforeAllCallback和AfterAllCallback。更推荐的方式是实现ExtensionContext.Store.CloseableResource接口并将资源本身或一个清理句柄存入Store。JUnit 会在存储区关闭时自动调用close()方法这是一种更可靠的生命周期绑定方式即使测试异常中断也能保证清理。对于非常昂贵的资源考虑使用单例模式或静态持有并在所有测试套件完成后通过 JVM 关闭钩子Shutdown Hook来清理但这需要谨慎设计。5.4 性能考量避免在扩展中执行耗时操作虽然BeforeAllCallback只执行一次但如果初始化操作非常耗时例如下载大型文件、启动全套 Docker 环境它会拖慢整个测试类的反馈速度。建议考虑使用TestInstanceFactory扩展来改变测试实例的生命周期为PER_CLASS这样BeforeAll可以是非静态方法但需注意状态隔离。对于极其耗时的全局资源可以评估是否真的需要为每个测试类都初始化。或许可以提升到套件级别使用 JUnit 的TestInstance(Lifecycle.PER_CLASS)配合静态字段但要注意线程安全。利用ExecutionCondition在不需要该资源的测试类中禁用扩展。通过深入理解BeforeAllCallback和ParameterResolver的工作原理、熟练掌握其实现模式、并规避常见的陷阱你就能充分利用 JUnit 5 扩展模型的强大能力构建出高度模块化、可复用且维护性极佳的测试基础设施。这不仅仅是写测试更是设计一套支持测试的、专业级的开发工具。