Spring Boot集成WireMock遇404错误：请求未匹配存根未注册

核心排查方向 #

• 严格校验Stub匹配规则与实际请求的一致性
  WireMock的匹配逻辑是严格匹配，HTTP方法、请求路径、请求头、查询参数甚至路径末尾的斜杠，只要有一项不匹配就会触发404。比如Stub定义的是/api/test，但实际请求带了末尾斜杠/api/test/，就会匹配失败。
  可通过开启WireMock verbose日志（启动时加--verbose参数，或代码中配置日志级别），对比实际收到的请求细节和Stub定义，定位差异点。

• 确认WireMock端口与应用配置完全对齐
  检查Spring Boot测试配置（如application-test.properties）中的第三方服务地址，是否和WireMock实例的端口一致。若使用动态端口（如JUnit扩展），需确保端口值正确注入到应用配置中：

  @RegisterExtension
  static WireMockExtension wireMockServer = WireMockExtension.newInstance()
          .options(wireMockConfig().dynamicPort())
          .build();
  
  @DynamicPropertySource
  static void setExternalServiceUrl(DynamicPropertyRegistry registry) {
      registry.add("external.service.url", wireMockServer::baseUrl);
  }
  

• 确保Stub注册到正确的WireMock实例
  若同时存在多个WireMock实例（比如手动启动了独立服务，又在测试中用了Rule/扩展），可能出现Stub注册到A实例，但应用请求的是B实例的情况。测试中需通过当前实例对象注册Stub，比如用wireMockServer.stubFor(...)而非全局的WireMock.stubFor(...)。

• 调整启动顺序：先注册Stub，再启动应用上下文
  若使用ApplicationContext初始化器或@TestConfiguration，需保证Stub在Spring Boot应用启动前完成注册，避免应用启动后发起请求时Stub尚未生效。

常见错误修正示例 #

1. 路径与参数匹配错误
   错误写法（未处理查询参数）：

   stubFor(get(urlEqualTo("/api/test"))
           .willReturn(aResponse().withStatus(200)));
   

   修正写法（匹配路径+指定参数）：

   stubFor(get(urlPathEqualTo("/api/test"))
           .withQueryParam("id", equalTo("123"))
           .willReturn(aResponse().withStatus(200)));
   

2. 遗漏请求头匹配
   若应用请求携带了Content-Type等特定头，Stub必须包含对应匹配规则：

   stubFor(post(urlEqualTo("/api/test"))
           .withHeader("Content-Type", equalTo("application/json"))
           .willReturn(aResponse().withStatus(200)));
   

快速验证手段 #

• 访问WireMock的管理端点http://localhost:<端口>/__admin/mappings，查看已注册的Stub列表，确认目标Stub是否存在；
• 访问http://localhost:<端口>/__admin/requests，查看最近的请求记录，直接对比请求细节与Stub规则的差异。

内容的提问来源于stack exchange，提问作者Shruti Mishra