
本文介绍在 Spring Boot 3.1+ 项目中,使用 spring-cloud-contract-wiremock 时,如何为每个 @Test 方法动态加载专属的 WireMock JSON stub 文件(如 test1.json、test2.json),避免全局映射冲突,提升测试隔离性与可维护性。
本文介绍在 spring boot 3.1+ 项目中,使用 `spring-cloud-contract-wiremock` 时,如何为每个 `@test` 方法动态加载专属的 wiremock json stub 文件(如 `test1.json`、`test2.json`),避免全局映射冲突,提升测试隔离性与可维护性。
默认情况下,@AutoConfigureWireMock(port = 0) 会自动扫描 src/test/resources/mappings/ 下所有 JSON 文件并一次性加载全部 stub,无法按需启用。若需实现「一测一映射」,推荐手动管理 WireMockServer 实例——绕过自动配置,显式创建、配置并销毁服务,从而精准控制每条测试所加载的 JSON 文件。
✅ 正确实践:按需加载指定 JSON 映射文件
首先,在 src/test/resources 下创建结构化目录(例如 mappings/SomeTest/),并放入对应 JSON 文件:
src/test/resources/mappings/SomeTest/ ├── test1.json # 返回 200 └── test2.json # 返回 401
示例 test1.json:
使用 extruct 从原始 HTML 中提取机器可读的元数据,以便代理可以在不依赖脆弱的全页解析的情况下对页面进行分类、去重或丰富。它最适合元数据采集工作流,而不适用于爬取整个网站或渲染 JavaScript 密集型页面。
{
"request": {
"method": "GET",
"urlPath": "/endpoint"
},
"response": {
"status": 200,
"body": "{\"message\":\"OK\"}",
"headers": {
"Content-Type": "application/json"
}
}
}然后在测试类中手动管理 WireMockServer:
import com.github.tomakehurst.wiremock.WireMockServer;
import com.github.tomakehurst.wiremock.common.FileSource;
import com.github.tomakehurst.wiremock.core.WireMockConfiguration;
import com.github.tomakehurst.wiremock.stubbing.StubMapping;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.core.io.ClassPathResource;
import org.springframework.util.StreamUtils;
import java.nio.charset.StandardCharsets;
import static com.github.tomakehurst.wiremock.client.WireMock.*;
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE)
class SomeTest {
private WireMockServer wireMockServer;
@BeforeEach
void setUp() {
// 使用随机可用端口(兼容多模块并发测试)
wireMockServer = new WireMockServer(WireMockConfiguration.options().dynamicPort());
wireMockServer.start();
configureFor("localhost", wireMockServer.port()); // 设置客户端目标地址
}
@AfterEach
void tearDown() {
if (wireMockServer != null) {
wireMockServer.resetAll(); // 清除当前 stub
wireMockServer.stop(); // 关闭实例
}
}
@Test
void test1() throws Exception {
wireMockServer.addStubMapping(buildStubMapping("mappings/SomeTest/test1.json"));
// 执行业务调用与断言
// assertThat(httpClient.get("/endpoint")).hasStatusCode(200);
}
@Test
void test2() throws Exception {
wireMockServer.addStubMapping(buildStubMapping("mappings/SomeTest/test2.json"));
// assertThat(httpClient.get("/endpoint")).hasStatusCode(401);
}
private StubMapping buildStubMapping(String path) throws Exception {
ClassPathResource resource = new ClassPathResource(path);
String json = StreamUtils.copyToString(resource.getInputStream(), StandardCharsets.UTF_8);
return StubMapping.buildFrom(json);
}
}⚠️ 注意事项
-
禁用自动配置:必须移除
@AutoConfigureWireMock,否则会与手动创建的WireMockServer冲突(端口占用或重复 stub); -
路径匹配:JSON 文件路径基于
src/test/resources,推荐使用子目录(如mappings/SomeTest/)避免命名冲突; -
依赖版本适配:
spring-cloud-contract-wiremock:4.0.2基于 WireMock 1.3+,StubMapping.buildFrom()可直接解析标准 WireMock JSON 格式; -
资源清理:务必在
@AfterEach中调用resetAll()和stop(),防止测试间状态污染; -
线程安全:每个测试方法独占一个
WireMockServer实例(或至少独占其 stub 空间),天然支持并行执行。
✅ 总结
通过手动初始化 WireMockServer 并结合 addStubMapping(StubMapping) + ClassPathResource 加载 JSON,即可实现粒度至单个测试方法的 stub 隔离。该方式不依赖 Spring Boot 自动配置,更灵活、可控,特别适合契约测试中需要精确模拟多种 HTTP 状态、响应体或 Header 的场景。同时,JSON 映射文件可复用、可版本化、便于团队协作维护。

















