用 WireMock 验证真正的商户 HTTP 客户端

核查日期：2026-10-11。状态：本节是测试设计，未安装、启动 WireMock，也未运行任何客户端或写入实验。

目标与前置知识

证明应用真正使用的客户端，在可控制的失败面前有没有按契约发请求、重试和结束等待。先有只读商户客户端与统一错误映射，读过超时/重试模块，会写 JUnit 断言。

测试接线步骤

1. 先检查实际 JDK、HTTP 客户端、JUnit、WireMock、Jetty 及框架依赖。保留现有依赖，不抄一套未经兼容验证的新版本。
2. 让 WireMock 使用动态端口，将运行时取得的 base URL 注入应用实际创建的 MerchantClient。被测对象必须是处理 URL、参数、身份传递、反序列化、超时和重试的那一个客户端；测试代码另写一次 HTTP 请求只能证明测试工具自己可用。
3. 每个用例重置 stub、请求日志和场景状态，再单独装载本例数据。JUnit 扩展默认重置 stub 与请求；使用有状态场景时也明确核对状态归零。避免并行测试共用同一可变场景。
4. 为“503 后 200”设置两个状态：起始状态返回 503 并进入 next，next 返回 200。不能放两个完全相同且无状态的 stub，然后凭顺序猜会轮流响应。
5. 每次都核对响应、业务断言与精确请求次数。除目标路径外，也检查全部接收记录及未匹配请求，防止“目标路径 0 次，但错误地址被调用了”漏过测试。记录真实传递的租户标识来自可信身份，不接受模型自报租户。

固定验收表

下表“次数”是待实现的设计断言；不是已执行结果。只读查询的重试规则固定为仅 503 可重试、maxAttempts=3，正常及错误分支均用完全相同的实际客户端。慢响应例单独关闭重试，避免混测。

业务未查得包括“夹具中没有 9999”与“A 请求 B 的 1002”两种内部情况，对外均为统一 404；断言前者在夹具中不存在、后者没有跨租户数据进入响应。进入只读工具或客户端不等于读取了无权数据，授权和 tenant + id 查询条件也要验证。

写入响应丢失该怎样解释

WireMock 收到请求、返回空响应，只证明这个模拟下游接收了请求并丢失可用回复；不能证明真实数据库已经提交。要研究“提交后丢回复”，另做隔离的带状态假服务：先记录一次虚构写入已应用，再让响应丢失，最后用只读状态接口核对。写入尝试的 POST 次数和状态核对 GET 次数分别计数。此扩展仍未实现、未运行，不能拿请求日志充当真实订单落库证据。

Windows 先选择固定延迟或 EMPTY_RESPONSE；官方文档指出 CONNECTION_RESET_BY_PEER 在 Windows 可能挂起，不能把它当成跨平台稳定的复现开关。超时之后要确认客户端的后台请求或重试已结束，再做最终次数断言；只在超时瞬间数一次，可能漏掉晚到请求。

交付物与证据边界

交付测试源码、真实客户端构造/注入位置、端口与运行配置、每个用例的请求记录、实际次数、状态、异常和耗时。未运行前这些实测字段全部留空；“WireMock 已返回 503”不证明应用重试策略有效，只有走过真实客户端并通过断言才算本用例的证据。

原始来源与指定阅读

• JUnit 集成：Basic usage、生命周期、Resetting before each test method、Unmatched request behaviour。滚动文档；其中关闭每例重置的选项标注自 3.13.0 起可用，本节保持每例重置。
• 状态场景：Scenario 与 Resetting scenarios。
• 请求验证：Verifying in Java、Querying the request journal；用 verify(n, ...) 核对精确次数。
• 故障模拟：Fixed delays、Bad responses 及 Windows 注意事项。

站点已有 WireMock 官方资源卡，补上本实验的学习导航即可，不为同一来源再新增一张重复资源卡。