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 与 ParameterResolver

2.1 BeforeAllCallback：全局一次性初始化的利器

BeforeAllCallback接口只定义了一个方法：void beforeAll(ExtensionContext context)。顾名思义，它会在标注了@Test、@RepeatedTest、@ParameterizedTest等注解的测试类中，所有测试方法执行之前被调用一次。注意，是每个测试类调用一次，而不是整个测试套件。

它的典型应用场景有哪些呢？

1. 启动外部服务：比如启动一个内嵌的 Redis、Kafka 或者数据库（如 Testcontainers），并获取连接配置。
2. 初始化静态资源：创建一些昂贵的、只读的、需要在所有测试间共享的资源，例如一个大型的测试数据文件加载到内存中。
3. 全局配置设置：设置一些系统属性、环境变量，或者初始化某些全局工具类。
4. 执行数据库迁移：在运行测试前，执行 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就是那个背后的“魔法师”，负责在运行时决定这些参数的值。

它的应用场景更加广泛：

1. 依赖注入：模拟 Spring 的@Autowired，为测试方法注入诸如UserRepository、RestTemplate这样的 Bean。
2. 测试数据工厂：根据参数类型，动态生成测试数据对象。比如，参数类型是Product，就自动创建一个随机的、有效的Product实例。
3. 上下文信息传递：将BeforeAllCallback中初始化的资源（如数据库连接）传递给每个测试方法。
4. 与@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(); } }

代码解读与注意事项：

1. 实现CloseableResource：我们同时实现了CloseableResource接口，它的close()方法会在该存储区（Store）的生命周期结束时被调用。我们将自身实例存入GLOBAL命名空间的 Store，从而确保在所有测试完成后，能执行关闭服务器的逻辑。这是一种优雅的资源清理模式。
2. 使用Store：ExtensionContext.Store是扩展之间、扩展与测试之间共享数据的核心机制。这里我们使用GLOBAL命名空间存储服务器实例，使其在整个测试运行期间都可用。
3. 静态变量与并发：这里使用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(); } }

代码解读与设计思路：

1. 自定义注解：我们创建了@MockServerUrl注解。这是一种非常优雅的模式，它让测试方法的意图更加清晰。通过注解，我们明确表达了“这个参数需要被注入模拟服务器的 URL”，而不是通过参数类型等隐式规则。
2. supportsParameter逻辑：这里我们要求参数同时满足两个条件：被@MockServerUrl注解标记，并且类型是String。这样设计非常精确，避免了误匹配。
3. 依赖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 配置了响应 HttpResponse<String> 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 处理扩展的依赖与执行顺序

有时，你的多个扩展之间存在依赖关系。比如，一个DatabaseInitializationExtension（BeforeAllCallback）需要在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方法里的日志打印了多次，或者资源被重复初始化。原因：

1. 嵌套测试类（@Nested）：JUnit 5 中，每个静态嵌套测试类都会触发一次BeforeAllCallback。如果你在父类上使用了@ExtendWith，那么父类和每个嵌套类都会执行。
2. 扩展被重复注册：可能通过@ExtendWith、@RegisterExtension和自动注册（META-INF/services）多种方式重复注册了同一个扩展。
3. 静态变量处理不当：在并行测试模式下，如果扩展没有正确管理状态，可能导致初始化逻辑被多个线程执行。

排查与解决：

• 对于嵌套类，考虑是否真的需要在每个嵌套类前都初始化。如果不需要，可以将扩展移到具体的测试方法层级，或者使用ExtensionContext的存储机制配合唯一键来确保逻辑只执行一次（就像我们示例代码中检查wireMockServer == null那样）。
• 检查扩展的注册方式，确保唯一。
• 在并行测试中，避免使用可变的静态变量。使用ExtensionContext.Store并选择适当的命名空间（如Namespace.create(getClass(), context.getUniqueId())）来保存线程隔离的状态。

5.2 问题：ParameterResolver 不生效

现象：测试方法的参数没有得到注入，值为null或者 JUnit 抛出ParameterResolutionException。原因：

1. 扩展未注册：忘记使用@ExtendWith将ParameterResolver实现注册到测试类。
2. supportsParameter条件太严格或太宽松：你的supportsParameter方法返回了false，导致 JUnit 认为该解析器不支持此参数；或者有其他解析器先于你的解析器返回了true。
3. 参数类型或注解不匹配：测试方法参数的类型或注解与supportsParameter中的判断逻辑不匹配。
4. 与框架自带解析器冲突：例如，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 扩展模型的强大能力，构建出高度模块化、可复用且维护性极佳的测试基础设施。这不仅仅是写测试，更是设计一套支持测试的、专业级的开发工具。