1. 项目概述为什么我们需要WireMock在微服务架构和前后端分离成为主流的今天API应用程序编程接口已经成了系统之间沟通的“普通话”。无论是前端调用后端服务还是后端服务之间相互调用都离不开API。但随之而来的一个巨大挑战就是依赖。当你开发一个订单服务需要调用库存服务和支付服务时如果这些依赖服务还没开发完、不稳定或者调用一次成本极高比如调用第三方短信服务要收费你的开发和测试工作就会寸步难行。这时候API Mock模拟工具就成了开发者的“救星”。而WireMock就是这片星空里最亮的那颗星之一。它不是简单的“占位符”而是一个功能强大、高度灵活的HTTP服务模拟器。你可以把它理解为一个极其逼真的“演员”能完美扮演你指定的任何一个API服务按照你写的“剧本”规则来回应请求。无论是返回预设的数据、模拟网络延迟还是故意制造错误它都能胜任。我用了WireMock好几年从早期的独立JAR包到现在的云平台感触最深的就是它让“测试左移”真正落地了。以前等联调、等测试环境是常态现在只要定义好接口契约前后端、不同服务团队可以并行开发效率提升不是一点半点。这篇文章我就结合自己踩过的坑和总结的经验带你用5个最核心、最高频的场景彻底掌握WireMock让你的API测试变得既简单又高效。2. 核心场景一基础桩Stub与请求匹配万事开头难但WireMock的入门却异常简单。它的核心思想就是“桩Stub”你告诉WireMock当收到什么样的请求时就返回什么样的响应。这个“什么样的请求”就是请求匹配Request Matching是WireMock最强大的能力之一。2.1 第一个WireMock桩从“Hello World”开始让我们跳过复杂的理论直接动手。假设你正在开发一个用户服务其中一个API是GET /api/users/{id}用于获取用户信息。依赖这个服务的团队比如前端需要先开始工作而你的服务还没写完。首先你需要启动WireMock。最快速的方式是使用Docker确保你已安装Dockerdocker run -it --rm -p 8080:8080 --name wiremock wiremock/wiremock:latest这条命令会在本地8080端口启动一个WireMock服务器。现在它就像一个空的HTTP服务器等待你的指令。接下来我们需要创建一个“桩”。WireMock提供了非常友好的RESTful管理API。我们通过发送一个HTTP请求来创建规则。打开你的终端或使用Postman等工具发送以下JSON请求到WireMockcurl -X POST http://localhost:8080/__admin/mappings \ -H Content-Type: application/json \ -d { request: { method: GET, urlPath: /api/users/123 }, response: { status: 200, jsonBody: { id: 123, name: 张三, email: zhangsanexample.com }, headers: { Content-Type: application/json } } }发送成功后这个桩就立好了。现在任何人访问http://localhost:8080/api/users/123都会立刻得到我们预设好的JSON响应仿佛真的有一个用户服务在运行。注意这里我用了urlPath而不是url。urlPath只匹配路径不匹配查询参数更常用。如果你需要精确匹配带参数的完整URL才用url。2.2 高级匹配让Mock更智能只匹配固定路径显然不够。真实的API充满了变数查询参数、请求头、JSON请求体等等。WireMock的匹配器Matchers家族非常庞大。场景1匹配查询参数假设我们的用户列表API支持分页GET /api/users?page1size20。{ request: { method: GET, urlPath: /api/users, queryParameters: { page: { equalTo: 1 }, size: { matches: ^[0-9]$ // 使用正则匹配数字 } } }, response: { ... } }场景2匹配JSON请求体对于POST创建用户的请求我们需要匹配请求体{ request: { method: POST, urlPath: /api/users, bodyPatterns: [{ equalToJson: { name: 李四, email: lisiexample.com }, ignoreArrayOrder: true, ignoreExtraElements: true // 忽略请求体中多余的字段 }] }, response: { status: 201, headers: { Location: /api/users/456 } } }这里用了equalToJson匹配器并且设置了ignoreExtraElements: true这在实际中非常实用。因为前端发送的请求体可能包含id为null或createTime等字段但你的匹配规则只关心name和email。这个设置能避免因字段不全而匹配失败。场景3使用优先级处理模糊匹配当定义了多个桩时可能会发生冲突。比如你既定义了一个匹配所有GET请求到/api/users/*的宽泛规则又定义了一个精确匹配/api/users/123的规则。这时候就需要优先级priority。{ priority: 1, // 数字越小优先级越高 request: { method: GET, urlPathPattern: /api/users/[0-9] }, response: { status: 200, body: 通用用户响应 } }, { priority: 10, request: { method: GET, urlPath: /api/users/123 }, response: { status: 200, body: 特殊用户123的响应 } }这样当请求/api/users/123时会优先匹配优先级更高的第二条规则priority10返回特殊响应。实操心得从简到繁不要一开始就追求复杂的匹配规则。先用最简单的urlPath或url让流程跑通再逐步增加查询参数、请求头等匹配条件。善用urlPathPattern它支持正则表达式比如/api/orders/\\d匹配所有数字ID的订单比写无数个固定路径的桩高效得多。管理你的桩随着项目进行桩定义会越来越多。我强烈建议不要只用动态API创建而是将桩定义写成JSON文件放在项目的src/test/resources/mappings目录下。当WireMock以--root-dir参数启动时会自动加载这些文件。这样能做到版本化管理团队共享。3. 核心场景二动态响应与响应模板返回固定的静态数据只能应付最简单的场景。很多时候我们需要响应能根据请求的不同而动态变化。比如返回的订单ID应该就是请求创建时传入的ID或者返回的数据需要包含当前时间戳。这就是WireMock动态响应和响应模板Response Templating大显身手的地方。3.1 启用响应模板功能要使用响应模板首先需要启用这个功能。如果你用的是Standalone模式启动时需要加参数java -jar wiremock-standalone.jar --extensionsorg.wiremock.extensions.ResponseTemplateTransformer如果是在代码中嵌入比如JUnit测试则需要通过构建器开启WireMockServer wireMockServer new WireMockServer(options() .extensions(new ResponseTemplateTransformer(false)) // false表示不全局应用 .port(8080)); wireMockServer.start();3.2 Handlebars模板实战WireMock使用Handlebars作为模板引擎语法简单直观。在响应定义中用{{...}}包裹变量或助手函数。场景1提取请求参数并返回假设创建订单的API希望返回的响应体里包含请求中的商品ID和数量。{ request: { method: POST, urlPath: /api/orders, bodyPatterns: [{ matchesJsonPath: $.items[*] }] }, response: { status: 201, headers: { Content-Type: application/json }, jsonBody: { orderId: {{randomValue length10 typeALPHANUMERIC}}, message: 订单创建成功, requestedItems: {{jsonPath request.body $.items}} }, transformers: [response-template] // 关键声明使用此变换器 } }在这个响应里{{randomValue ...}}生成一个10位的随机字母数字字符串作为订单ID这比写死一个ID要真实得多。{{jsonPath request.body $.items}}使用jsonPath助手从请求体request.body中提取items数组并原样放入响应体中。这样响应就能动态反映请求内容。场景2生成基于请求的复杂逻辑响应更复杂的场景比如模拟一个查询用户积分详情的API需要根据用户ID返回不同的等级。{ request: { method: GET, urlPathPattern: /api/members/([0-9])/points }, response: { status: 200, headers: { Content-Type: application/json }, jsonBody: { userId: {{request.pathSegments.[2]}}, level: {{#if (contains request.pathSegments.[2] 1)}}VIP{{else}}REGULAR{{/if}}, totalPoints: {{randomInt lower100 upper10000}}, queryTime: {{now formatyyyy-MM-dd HH:mm:ss}} }, transformers: [response-template] } }这个模板展示了更多技巧{{request.pathSegments.[2]}}提取URL路径中的第三段索引从0开始。对于/api/members/456/pointspathSegments是[api, members, 456, points]所以[2]就是456。{{#if (contains ...)}}...{{else}}...{{/if}}Handlebars的条件判断。这里判断用户ID是否包含字符‘1’来模拟不同的用户等级。contains是WireMock内置的助手。{{randomInt lower100 upper10000}}生成指定范围内的随机整数模拟积分。{{now format...}}生成当前时间并格式化为指定的字符串。这在测试中非常有用可以验证时间戳逻辑。场景3处理XML请求和响应虽然JSON是主流但一些老系统或特定行业接口仍用XML。WireMock同样支持。!-- 假设请求体是XML -- { request: { method: POST, urlPath: /api/legacy, headers: { Content-Type: { contains: xml } } }, response: { status: 200, headers: { Content-Type: application/xml }, body: ?xml version\1.0\?responsetxId{{xPath request.body /request/txId/text()}}/txIdstatusPROCESSED/status/response, transformers: [response-template] } }这里使用了{{xPath ...}}助手来从XML格式的请求体中提取数据。避坑指南转义问题在JSON中定义XML或HTML响应体时注意特殊字符的转义如双引号\尖括号。我建议将复杂的响应体模板保存在单独的.xml或.html文件中通过bodyFileName引用更清晰。数据类型Handlebars模板输出的所有内容默认都是字符串。如果你的下游服务期待一个整数类型的字段而模板生成了字符串123可能会导致反序列化错误。在定义jsonBody时对于非字符串字段有时需要结合{{jsonStringify ...}}助手或确保生成的字符串能被正确解析。性能复杂的模板逻辑会影响响应速度。在性能测试或高并发场景下尽量使用静态响应或简单的动态替换。4. 核心场景三记录与回放Record Playback手动编写大量的桩定义尤其是对于一个复杂的第三方API是一项枯燥且容易出错的工作。WireMock的记录与回放功能简直就是“懒人”福音。它能充当一个代理捕获你对真实服务的所有请求和响应并自动生成桩映射文件。4.1 录制你的第一个API会话假设你要模拟一个天气APIhttps://api.weather.example.com但你不想手动去研究它的每个接口和响应格式。步骤1以代理模式启动WireMockdocker run -it --rm -p 8080:8080 --name wiremock-proxy \ wiremock/wiremock:latest \ --proxy-allhttps://api.weather.example.com \ --record-mappings \ --verbose关键参数解释--proxy-all将所有收到的请求转发到指定的目标地址。--record-mappings开启录制模式将请求-响应对保存为桩映射。--verbose输出详细日志方便调试。步骤2执行你的测试或操作现在将你的应用程序或测试脚本中的API基地址改为http://localhost:8080。然后像平常一样进行操作比如查询北京天气GET http://localhost:8080/v1/forecast?cityBeijing查询上海天气GET http://localhost:8080/v1/forecast?cityShanghaiWireMock会拦截这些请求转发给真实的https://api.weather.example.com并将返回的响应和对应的请求规则记录下来。步骤3停止并保存操作完成后停止WireMock容器。在容器内记录的桩映射默认会保存在/home/wiremock/mappings目录下。你可以通过Docker卷挂载将这些文件保存到宿主机docker run -it --rm -p 8080:8080 -v $(pwd)/recorded-mappings:/home/wiremock/mappings \ --name wiremock-proxy \ wiremock/wiremock:latest \ --proxy-allhttps://api.weather.example.com \ --record-mappings这样停止容器后recorded-mappings文件夹里就会有一堆.json文件每个文件都是一个完整的桩定义。4.2 回放与优化录制的桩录制的桩文件可以直接使用。重启一个普通的WireMock实例并通过--root-dir指定包含这些映射文件的目录它就会加载所有桩。docker run -it --rm -p 9090:8080 -v $(pwd)/recorded-mappings:/home/wiremock \ wiremock/wiremock:latest现在访问http://localhost:9090/v1/forecast?cityBeijing你就会得到之前录制好的响应完全离线但是直接录制的桩往往不够“智能”需要优化去除敏感信息检查响应头或响应体中是否包含了API密钥、真实用户令牌、个人身份信息等。务必在桩文件中将其替换为占位符或删除。泛化匹配规则录制的规则通常是精确匹配包括所有查询参数、请求头。你可能需要将其修改得更通用。例如将url改为urlPathPattern将固定的查询参数匹配改为可选的或使用正则。修改前精确匹配request: { url: /v1/forecast?cityBeijingapiKeysecret123 }修改后泛化匹配request: { urlPath: /v1/forecast, queryParameters: { city: { matches: ^[A-Za-z]$ } } }简化响应体真实的响应可能包含大量无关字段。你可以精简响应体只保留测试所需的核心字段使桩文件更清晰测试意图更明确。添加动态内容结合场景二的知识将固定的ID、时间戳等替换为Handlebars模板使模拟更真实。实操心得录制是起点不是终点千万不要认为录制完就万事大吉。一定要花时间审查和优化生成的桩文件这是保证Mock质量的关键。场景化录制不要一次性录制所有操作。应该按测试场景录制比如“成功查询场景”、“城市不存在场景”、“认证失败场景”。为每个场景创建独立的目录或文件名前缀便于管理。用于契约测试录制功能非常适合用于创建消费者驱动的契约CDC测试的初始桩。前端团队可以录制他们期望的后端响应作为契约提供给后端团队。5. 核心场景四故障注入与延迟模拟一个健壮的系统不仅要能在一切正常时工作更要在依赖服务出现问题时优雅地处理。这就是混沌工程和韧性测试的核心。WireMock可以轻松模拟各种网络异常和故障而无需去破坏真实的服务器。5.1 模拟网络延迟网络延迟是常态。为了测试你的超时重试、熔断降级逻辑是否有效需要模拟慢响应。{ request: { method: GET, urlPath: /api/slow }, response: { status: 200, body: 终于响应了..., fixedDelayMilliseconds: 3000 // 固定延迟3秒 } }除了固定延迟还可以模拟更符合真实网络情况的随机延迟均匀分布response: { status: 200, body: 随机延迟响应, delayDistribution: { type: uniform, lower: 1000, upper: 5000 // 延迟在1到5秒之间随机 } }以及对数正态分布更贴近某些网络延迟模型delayDistribution: { type: lognormal, median: 100, sigma: 0.5 }5.2 模拟HTTP错误状态码模拟依赖服务返回4xx或5xx错误。{ request: { method: POST, urlPath: /api/payment }, response: { status: 503, // 服务不可用 headers: { Retry-After: 120 }, body: 支付服务暂时过载请稍后重试。 } }常见的错误场景都可以模拟400错误请求、401未授权、403禁止访问、404不存在、429请求过多、500内部服务器错误等。5.3 模拟网络连接故障这比返回错误码更“狠”直接模拟连接层面的问题。{ request: { method: GET, urlPath: /api/unstable }, response: { fault: CONNECTION_RESET_BY_PEER // 模拟连接被对端重置 } }可选的fault类型有CONNECTION_RESET_BY_PEER建立连接后立即重置模拟服务崩溃。EMPTY_RESPONSE发送完HTTP头后不发送任何响应体就关闭连接。MALFORMED_RESPONSE_CHUNK发送一个畸形的HTTP响应块测试客户端容错性。RANDOM_DATA_THEN_CLOSE先发送一堆随机数据然后关闭连接。5.4 模拟响应数据畸形有时候服务返回的数据格式是错误的比如JSON中缺少引号或者字段类型不对。{ request: { method: GET, urlPath: /api/bad-json }, response: { status: 200, headers: { Content-Type: application/json }, jsonBody: { // 注意这里故意制造一个无效的JSON对象 id: 1, name: 张三, // 缺少逗号下一行会解析错误 email: zhangsanexample.com active: true } } }实际上WireMock会验证jsonBody的合法性上述写法会报错。要模拟畸形JSON你需要直接使用body字段并写入一个无效的JSON字符串response: { status: 200, headers: { Content-Type: application/json }, body: {\id\: 1, \name\: \张三\ \email\: \zhangsanexample.com\, \active\: true} // 缺少逗号的无效JSON }测试策略建议 不要只在单元测试里用Mock返回成功数据。专门建立一套“故障测试套件”使用WireMock模拟你依赖的所有外部服务可能出现的各种异常情况慢响应、间歇性失败、完全宕机、返回畸形数据等。然后运行你的主服务观察其日志、监控指标如熔断器状态、错误率和最终行为是优雅降级还是彻底崩溃。这是提升系统韧性的最有效实践之一。6. 核心场景五集成测试与请求验证WireMock不仅是一个Mock服务器还是一个强大的测试工具。它可以集成到你的JUnit、TestNG等测试框架中并在测试结束后验证你的应用是否按预期发起了请求。6.1 在JUnit 5中嵌入WireMock对于Java项目将WireMock作为测试依赖嵌入是最常见的方式。它会在测试开始时启动一个WireMock服务器测试结束后自动关闭非常干净。首先添加Maven依赖以最新稳定版为例dependency groupIdorg.wiremock/groupId artifactIdwiremock/artifactId version3.13.2/version scopetest/scope /dependency然后编写一个JUnit 5集成测试import com.github.tomakehurst.wiremock.junit5.WireMockExtension; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.RegisterExtension; import static com.github.tomakehurst.wiremock.client.WireMock.*; import static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig; public class UserServiceIntegrationTest { // 注册WireMock扩展动态分配端口 RegisterExtension static WireMockExtension wireMockServer WireMockExtension.newInstance() .options(wireMockConfig().dynamicPort()) // 使用随机端口避免冲突 .build(); Test void testGetUserById() { // 1. 桩定当收到指定请求时返回模拟响应 wireMockServer.stubFor(get(urlPathEqualTo(/api/external/users/1001)) .willReturn(okJson({\id\: 1001, \name\: \Mocked User\}))); // 2. 获取WireMock服务器运行时信息如端口 int mockServerPort wireMockServer.getPort(); String mockServerUrl http://localhost: mockServerPort; // 3. 创建你的被测服务实例并注入Mock服务器的地址 UserService userService new UserService(mockServerUrl /api/external); // 4. 执行测试调用被测服务的方法该方法内部会去调用我们Mock的地址 User user userService.getUserById(1001); // 5. 断言验证业务逻辑 assertThat(user).isNotNull(); assertThat(user.getName()).isEqualTo(Mocked User); // 6. 请求验证验证被测服务是否确实发起了我们期望的请求 wireMockServer.verify(1, // 期望请求次数 getRequestedFor(urlPathEqualTo(/api/external/users/1001)) .withHeader(Content-Type, equalTo(application/json)) ); } }6.2 请求验证的威力上面的例子中verify方法是关键。它确保你的应用不仅逻辑正确而且与外部服务的交互行为也符合预期。这对于测试HTTP客户端配置、重试逻辑、请求头设置等至关重要。验证更多细节// 验证精确的请求体 wireMockServer.verify(postRequestedFor(urlPathEqualTo(/api/users)) .withRequestBody(equalToJson({\name\: \New User\, \active\: true}))); // 验证查询参数 wireMockServer.verify(getRequestedFor(urlPathMatching(/api/search)) .withQueryParam(keyword, matching(.*test.*)) .withQueryParam(page, equalTo(1))); // 验证请求次数范围 wireMockServer.verify(moreThan(2), getRequestedFor(urlPathEqualTo(/api/ping))); wireMockServer.verify(lessThan(5), postRequestedFor(urlPathEqualTo(/api/data)));6.3 模拟有状态的行为Stateful Behavior真实的API往往是有状态的。比如先调用POST /api/cart/items添加商品再调用GET /api/cart查看购物车后者应该能反映出前者的更改。WireMock通过“场景Scenarios”来模拟这种状态。// 模拟一个简单的登录-访问流程 wireMockServer.stubFor(post(urlPathEqualTo(/api/login)) .inScenario(Auth Flow) .whenScenarioStateIs(Scenario.STARTED) // 初始状态 .willReturn(okJson({\token\: \abc123\})) .willSetStateTo(LOGGED_IN)); // 执行后状态变为 LOGGED_IN wireMockServer.stubFor(get(urlPathEqualTo(/api/profile)) .inScenario(Auth Flow) .whenScenarioStateIs(LOGGED_IN) // 只有在登录后才能访问 .willReturn(okJson({\username\: \john_doe\}))); wireMockServer.stubFor(get(urlPathEqualTo(/api/profile)) .inScenario(Auth Flow) .whenScenarioStateIs(Scenario.STARTED) // 未登录状态访问 .willReturn(unauthorized())); // 返回401未授权在测试中你需要按照场景顺序发起请求。WireMock会跟踪每个场景的状态并返回对应的响应。这对于测试认证、多步骤流程如OAuth非常有用。6.4 常见集成测试问题排查端口冲突最常遇到的问题。务必使用dynamicPort()或通过wireMockConfig().port(0)让WireMock自动选择空闲端口。硬编码端口如8080在并行测试或本地已有服务时必然失败。桩未生效首先检查WireMock服务器是否成功启动查看日志。其次确认你的应用配置的基地址是否正确指向了WireMock的地址和端口。可以使用wireMockServer.getPort()动态获取。最后通过WireMock的管理APIGET http://localhost:${port}/__admin/mappings查看当前所有已注册的桩确认你的桩在其中。请求验证失败verify失败通常意味着你的应用发出的请求与预期不符。使用wireMockServer.getAllServeEvents()或访问管理APIGET /__admin/requests来查看WireMock实际收到的所有请求详情与你的验证条件进行比对找出差异可能是URL、请求头、请求体不一致。测试隔离确保每个测试方法都是独立的。如果使用静态的RegisterExtension所有测试方法共享同一个WireMock服务器实例和状态。如果测试间有干扰可以考虑使用BeforeEach在每个测试前重置WireMock状态wireMockServer.resetAll();。更好的方式是使用WireMockExtension.perTest()配置为每个测试方法创建独立的实例但需要注意启动开销。