1. 为什么要给 Feign 客户端写测试：联调期的"慢"与"痛"

先聊一个实际场景。某跨平台系统的订单服务需要调用库存服务的接口，团队里两个人分别负责两个服务，约定好接口文档后分头开发。到了联调阶段，两边服务一启动，问题接踵而至：库存服务某个接口返回的 JSON 字段名和文档对不上、鉴权 Token 过期、环境配置指向错误、下游服务代码没合入主分支……联调窗口被无限拉长。这时候你会发现，通过 @FeignClient 声明的客户端接口，恰恰是整个链路里最容易被忽略、却又最容易出问题的一层。

Feign 客户端的坑通常不在"能不能调通"，而在"调通之后返回的数据是否正确"。比如序列化配置漏了 LocalDateTime 的格式、响应体结构变了导致反序列化抛异常、超时时间设得太短导致偶发失败——这些问题如果全部压到联调阶段才发现，排查成本会翻好几倍。更麻烦的是，很多团队根本没有给 Feign 接口写测试的习惯，以为"声明一个接口、加个注解"就完事了。

用 MockWebServer 配合 @FeignClient 做单元测试，本质上是把"下游 HTTP 服务"这个外部依赖，替换成一个能完全由测试代码控制的本地假服务器。它能解决的核心问题有三个：第一，让测试不再依赖真实下游服务的可用性和数据状态；第二，让 Feign 接口的序列化、反序列化、超时、重试、错误处理等逻辑能在本地快速验证；第三，把联调阶段的"玄学问题"提前暴露在 CI 流水线里。

本文适合这些读者：使用 Spring Cloud OpenFeign 但还没建立有效测试体系的同学、被下游接口不稳定折磨得焦头烂额的开发者、以及想要把接口测试纳入持续集成但没有成熟方案的团队。我会从 MockWebServer 的原理讲起，给出两套不同的测试策略，再补充一批我在实际项目中踩过的坑。

2. 核心思路拆解：@FeignClient 凭什么能用 MockWebServer 来测

2.1 先搞懂 Feign 在测试场景下的"身份"问题

理解 @FeignClient 和 MockWebServer 的关系，关键要抓住一个点：Feign 本质上是一个 HTTP 客户端。它做的事情就是把接口方法调用转换成 HTTP 请求，再把 HTTP 响应反序列化回 Java 对象。虽然它在 Spring Cloud 体系里被包装得很"声明式"——你只需要定义一个接口、加注解、声明方法签名——但底层链路就是标准的"请求-响应"模型。

传统测试里 mock Feign 的方式是直接替换 Bean，比如用 Mockito 去 mock 整个 Feign 接口的方法返回值。这种方式不是不行，但它有一个致命的问题：它绕过了 Feign 自身的序列化和网络层逻辑。如果 Feign 接口上配置了自定义的 Decoder、拦截器、超时参数，Mockito 是测不到的。换句话说，你只是在测"调用方怎么处理返回值"，完全没有测"Feign 作为客户端到底能不能正确完成任务"。

而 MockWebServer 的思路完全不同——它从网络层介入。Feign 发出去的 HTTP 请求会被一个真实的本地 Socket 服务接收，MockWebServer 再返回预设好的响应。在这个过程里，Feign 的编码、解码、拦截器、超时逻辑全都会真正执行。你可以把 MockWebServer 理解为"在测试环境里搭了一个假的数据库服务端"，Feign 是客户端，两边之间的所有网络通信都是真刀真枪跑的。

2.2 MockWebServer 的工作原理：一个能让你"点菜"的假服务端

MockWebServer 是 OkHttp 团队开源的一个测试组件，它本身就是一个轻量的 HTTP 服务器，设计目标就是用在测试里。它做的事情看起来简单，但背后有几个很关键的机制：

第一，启动真实端口。当你调用mockWebServer.start()时，它会在本地随机找一个可用端口（也可以指定端口）创建 ServerSocket。你不需要手动管理端口号，它自动避开已占用端口，并暴露url()/port属性供测试代码引用。

第二，请求排队与响应匹配。每个enqueue()调用会往内部队列里放一条预定义的 MockResponse。每当收到一个请求，就从队列头部取一条响应返回。这就实现了"请求一次，返回一次"的确定性测试，可以精确模拟各种场景。

第三，记录请求详情。每个收到的 HTTP 请求都会被记录到recordedRequest列表里，你可以断言请求的路径、请求头、请求体、请求方法，确保 Feign 真的按预期发了请求。这对校验"重试后是否多发了一次请求""请求头是否带上了 Token"等场景特别有用。

它和 Feign 能无缝配合的根源在于：两者都以 HTTP 协议为接口标准。Feign 不关心连到的服务器是谁，只要按 HTTP 协议发请求、收响应就行。MockWebServer 也不关心请求来自哪个客户端。双方都严格实现 HTTP 协议，这就让测试环境的模拟变得干净、稳定、不需要任何代理或特殊配置。

2.3 为什么不用 WireMock 或其他 mock 库？

在 Java 生态里，WireMock 也是个很流行的 HTTP mock 库。我并不是说 MockWebServer 一定碾压 WireMock，但在这个特定场景下有几点优势值得一提：

• 轻量：MockWebServer 是 OkHttp 家族里的测试组件，引入它基本不增加额外依赖复杂度（它自己就依赖一个轻量 HTTP 实现）。WireMock 则更"重型"，支持动态端口映射、场景模拟、录制回放等大量功能，但对单测而言很多是用不到的。
• 贴近 OkHttp 生态：Feign 在流程中经常搭配 OkHttp 作为底层 Client（feign.okhttp.enabled=true），用同一个技术栈里的测试组件心理负担小得多。
• API 直接：enqueue()+MockResponse+RecordedRequest三个类就把大多数需求覆盖了，上手成本极低。

当然，如果你需要模拟"同一组 URL 按不同请求参数返回不同响应"，MockWebServer 需要借助 Dispatcher 实现，而 WireMock 则天然按 URL 和 body 匹配。但绝大多数 Feign 接口单测场景只是"一次测试调用一次接口"，队列模式已经足够，Dispatcher 属于进阶能力。

3. 两套实操方案：从"裸 Feign 单测"到"Spring 集成测试"

面对不同场景，我用过两套方案。实际项目中不是二选一，而是按需混合使用——单测跑得快，覆盖核心逻辑；集成测试跑得慢，但能验证 Spring 装配层面的东西。

3.1 方案一：裸 Feign 单测（不启动 Spring 容器）

这套方案适合验证 Feign 接口的序列化/反序列化、拦截器、超时等"接口自身行为"。因为不启动 Spring 容器，测试速度快得惊人，几百个测试用例几秒钟就跑完。

先放依赖（Maven 方式）：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <!-- 由于 MockWebServer 是从 OkHttp 分离出来的，需要单独引入 --> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>mockwebserver</artifactId> <version>4.12.0</version> <scope>test</scope> </dependency>

这里额外说明一下：如果你的项目还引入了feign-okhttp（即 Feign 底层用 OkHttp 而非默认的 HttpURLConnection），那么还必须确认okhttp版本和mockwebserver版本保持一致，否则运行时可能因为类版本冲突出现奇怪问题。

接下来定义一个待测 Feign 接口：

@FeignClient(name = "inventory-service", url = "http://localhost:8080") public interface InventoryClient { @GetMapping("/api/inventory/{skuId}") InventoryInfo getInventory(@PathVariable("skuId") String skuId); }

注意这个接口上的url属性本来是指向真实服务的，在裸 Feign 测试里，这个 URL 是我们手动指定的 MockWebServer 地址，所以它会被覆盖。测试代码是这样写的：

class InventoryClientTest { private MockWebServer mockWebServer; private InventoryClient client; @BeforeEach void setUp() throws IOException { // 启动本地 HTTP 模拟服务 mockWebServer = new MockWebServer(); mockWebServer.start(); // 用 Feign.builder() 手动构建客户端，重点是 target() 指向 MockWebServer 的地址 client = Feign.builder() .addDecoder(new JacksonDecoder()) // 指定 JSON 反序列化器 .target(InventoryClient.class, mockWebServer.url("/").url().toString()); } @AfterEach void tearDown() throws IOException { mockWebServer.shutdown(); } @Test void testGetInventory() { // 预设一个成功的 JSON 响应 mockWebServer.enqueue(new MockResponse() .setResponseCode(200) .setHeader("Content-Type", "application/json") .setBody("{\"skuId\":\"SKU_1001\",\"stock\":58}")); InventoryInfo info = client.getInventory("SKU_1001"); assertEquals("SKU_1001", info.getSkuId()); assertEquals(58, info.getStock()); // 断言 Feign 发出去的请求路径和方法正确 RecordedRequest recordedRequest = mockWebServer.takeRequest(); assertEquals("GET", recordedRequest.getMethod()); assertEquals("/api/inventory/SKU_1001", recordedRequest.getPath()); } @Test void testGetInventory404() { mockWebServer.enqueue(new MockResponse().setResponseCode(404)); // 404 时 Feign 默认抛 FeignException，注意这是查 Feign 内部逻辑是否正确的关键 FeignException exception = assertThrows(FeignException.class, () -> client.getInventory("SKU_1001")); assertEquals(404, exception.status()); } }

这套方案的核心好处是不依赖 Spring 容器，断言粒度细。takeRequest()可以拿到 Feign 真正发出去的 HTTP 请求，我们能直接核对请求路径、请求头、请求体，这套组合拳把"Feign 配错了某个请求头"这类问题抓得死死的。

3.2 方案二：Spring Boot 集成测试（注入 @Autowired 的真实客户端）

裸 Feign 单测有个覆盖盲区：拿不到 Spring 托管的拦截器、请求重试（Spring Retry）、熔断降级配置。比如你在 Feign 接口上配置了@RequestInterceptor，或者开启了spring.cloud.openfeign.retry.enabled=true，裸 Feign 手动构建的客户端是感知不到的。要验证这些机制，就需要启动 Spring 容器。

集成测试的核心难点在于：把 MockWebServer 的动态端口塞给 @FeignClient 的 URL 属性。Spring 容器启动时 @FeignClient 的 URL 已经固定了，你不能在测试里临时改。解决方式是用@DynamicPropertySource（Spring Boot 2.5+ 支持）动态注册配置项：

@SpringBootTest(properties = { "spring.cloud.openfeign.client.config.default.connect-timeout=5000", "spring.cloud.openfeign.client.config.default.read-timeout=5000" }) class InventoryClientIntegrationTest { static MockWebServer mockWebServer = new MockWebServer(); @DynamicPropertySource static void registerProperties(DynamicPropertyRegistry registry) { // 重点：在容器启动前把 MockWebServer 的地址注册为 inventory-service 的 URL registry.add("spring.cloud.openfeign.client.config.inventory-service.url", () -> mockWebServer.url("/").url().toString()); } @Autowired private InventoryClient inventoryClient; @BeforeAll static void setUp() throws IOException { mockWebServer.start(); } @AfterAll static void tearDown() throws IOException { mockWebServer.shutdown(); } @Test void contextLoadsAndClientWorks() { mockWebServer.enqueue(new MockResponse() .setResponseCode(200) .setBody("{\"skuId\":\"SKU_1002\",\"stock\":20}")); InventoryInfo info = inventoryClient.getInventory("SKU_1002"); assertEquals("SKU_1002", info.getSkuId()); } }

这里的@DynamicPropertySource是关键。它允许在 Spring 容器启动过程中给测试环境添加配置属性，而且是在@FeignClient的 bean 创建之前生效。名字里必须用spring.cloud.openfeign.client.config.<feignClientName>.<property>的方式，其中<feignClientName>对应@FeignClient(name = "inventory-service")中的name字段，如果配错层级或名称，Feign 客户端会依然指向旧配置，测试就会出现"访问了真实服务"或"连接被拒"的错误。

这套方案虽然跑得慢，但它能覆盖到康健全链路：Spring 容器创建了 Feign 客户端代理、拦截器生效、熔断降级生效、超时设置生效。我建议核心对外暴露的 Feign 客户端至少配一套这样的集成测试，单测验证逻辑细节，集成测试验证"组合后的整体行为"。

3.3 两种方案对比及选型建议

我的经验是：优先把裸 Feign 单测当作缺省测试写，每个新接口、每次改动接口方法签名，先补单测。然后在核心链路上（比如订单调用库存、支付调用账户）补一两个集成测试来"看整体"。双管齐下，既保证了速度，又保证了覆盖深度。

4. MockWebServer 进阶玩法：不只是"预设一个响应"

很多人用 MockWebServer 以为就是enqueue()一条响应就完事，但实际工程场景里它还能干更多事情。这一章我按实战顺序介绍几个我常用但资料里不太被强调的能力。

4.1 Dispatcher：根据请求内容动态返回不同响应

enqueue()只能按请求顺序依次返回，这在"客户端的重试逻辑会发两次请求"的场景下会出问题——你以为第一次该返回 500，第二次该返回 200，但因为你不知道队列里哪一条会被对应第一次请求，实际上可能第二次请求拿到第一条响应。用 Dispatcher 就能按 "请求路径 + 方法 + body" 精确判断。

Dispatcher dispatcher = new Dispatcher() { @NotNull @Override public MockResponse dispatch(RecordedRequest request) { String path = request.getPath(); if (path != null && path.startsWith("/api/inventory/SKU_200")) { // 对特定 SKU 返回库存不足 return new MockResponse() .setResponseCode(200) .setHeader("Content-Type", "application/json") .setBody("{\"skuId\":\"SKU_200\",\"stock\":0}"); } if (request.getMethod().equals("POST") && path.equals("/api/order")) { // 模拟创建订单成功 return new MockResponse() .setResponseCode(201) .setBody("{\"orderId\":\"ORD_123456\"}"); } return new MockResponse().setResponseCode(404); } }; mockWebServer.setDispatcher(dispatcher);

这个能力在测 Feign 的 "fallback 降级逻辑"时特别好用：库存不足返回 stock=0，业务侧走缺货分支；订单创建成功返回 201，业务侧走成功分支。一次启动 MockWebServer，多个测试场景共用，不用不停地重新enqueue()。

4.2 模拟网络延迟和超时

Feign 客户端最头疼的测试就是"下游响应慢"——这是超时设置的试金石。MockWebServer 有一个很好用的接口setBodyDelay()，可以指定模拟延迟：

mockWebServer.enqueue(new MockResponse() .setBody("{\"skuId\":\"SKU_300\",\"stock\":10}") // 模拟 2 秒延迟 .setBodyDelay(2, TimeUnit.SECONDS));

如果你的 Feign 配置了read-timeout=1000（1 秒），这会导致读取超时，超时异常会被抛出来。这是验证"超时是否真的按预期触发"的关键手段。我踩过的坑是手工用 Thread.sleep() 模拟延迟——那样进程会被挂起，而且根本不会让 Feign 感知到"慢"，因为 Socket 层没有阻塞，只是客户端在等。setBodyDelay()是真的把 Socket 层响应推迟了，Feign 的读超时才会被激活。

4.3 请求头和请求体的断言

MockWebServer 的takeRequest()能拿到RecordedRequest，它提供了非常细粒度的请求信息：

RecordedRequest request = mockWebServer.takeRequest(); // 断言请求头 assertEquals("Bearer test-token", request.getHeader("Authorization")); // 断言请求体 assertEquals("{\"skuId\":\"SKU_400\",\"qty\":3}", request.getBody().readUtf8()); // 断言 Content-Type assertEquals("application/json", request.getHeader("Content-Type"));

这个方法能极大提高 Feign 拦截器的可测性。之前我帮某项目排查过一个诡异的问题：业务方设置了@RequestInterceptor往请求头里补充了登录上下文，但实际发现请求头里的字段一直是空的。用 MockWebServer 一断言request.getHeader("X-User-Id")，立刻发现拦截器执行顺序错了，处理得很透明。

4.4 验证重试与幂等性

Feign 开启重试后（通过 Spring Cloud 的spring.cloud.openfeign.retry.enabled=true），如果下游返回 5xx，Feign 会自动重试。测试这个行为只需要两行配置：

mockWebServer.enqueue(new MockResponse().setResponseCode(500)); mockWebServer.enqueue(new MockResponse().setResponseCode(500)); mockWebServer.enqueue(new MockResponse() .setResponseCode(200) .setBody("{\"skuId\":\"SKU_500\",\"stock\":5}")); InventoryInfo info = inventoryClient.getInventory("SKU_500"); // 重试机制生效：第一次 500，第二次 500，第三次成功 assertEquals(5, info.getStock()); // 确认确实发了 3 次请求 assertEquals(3, mockWebServer.getRequestCount());

这类测试很容易暴露出重试配置是否合理。之前一个用户反馈"下游明明是幂等的，为什么重试后数据重复了"——后来用 MockWebServer 验证发现，Feign 的 URL 拼接有偏差，原本应该请求/api/inventory/SKU_500，实际请求了/api/inventory/SKU_500/，下游对带斜杠和不带斜杠的路径解析不同，才造成了重复。这种"被路径差异埋下的雷"，不把请求打到真实测试服务器上根本发现不了。

5. 实战拼配：Spring Cloud 拦截器 + 错误解码器

很多真实项目的 Feign 客户端不是只有一个接口方法那么简单，它往往带有全局拦截器（比如统一加 Token）、自定义错误解码器、RequestInterceptor 等。这一节我用一个相对完整的案例，把前面学的工具在一个更贴近现实的工程里组装起来。

5.1 搭建待测工程：带拦截器的 Feign 客户端

先定义一个请求拦截器，它模拟"所有 Feign 请求都自动携带网关 Token"：

@Component public class AuthRequestInterceptor implements RequestInterceptor { @Override public void apply(RequestTemplate template) { // 这个 Header 名称随便，真实项目里一般是网关鉴权头 template.header("X-Gw-Token", "a1b2c3d4e5f6"); } }

再定义一个自定义错误解码器，把下游返回的报错信息解析成业务异常：

@Component public class InventoryErrorDecoder implements ErrorDecoder { @Override public Exception decode(String methodKey, Response response) { // 简单示意：读响应体的 error 字段 if (response.status() == 400) { return new IllegalArgumentException("参数不合法"); } return new RuntimeException("下游服务异常, code=" + response.status()); } }

再把它们装配到 Feign 客户端上：

@FeignClient( name = "inventory-service", url = "http://placeholder", // 实际地址在测试里动态替换 configuration = FeignConfig.class ) public interface InventoryClient { @GetMapping("/api/inventory/{skuId}") InventoryInfo getInventory(@PathVariable("skuId") String skuId); @PostMapping("/api/order") OrderInfo createOrder(@RequestBody CreateOrderRequest request); }

FeignConfig 里注册拦截器和错误解码器：

@Configuration public class FeignConfig { @Bean public RequestInterceptor authRequestInterceptor() { return new AuthRequestInterceptor(); } @Bean public ErrorDecoder inventoryErrorDecoder() { return new InventoryErrorDecoder(); } }

5.2 集成测试：验证拦截器和错误解码器都生效

测试里用@DynamicPropertySource注入地址后：

@SpringBootTest class InventoryClientIntegrationTest { static MockWebServer mockWebServer = new MockWebServer(); @DynamicPropertySource static void registerProperties(DynamicPropertyRegistry registry) { registry.add("spring.cloud.openfeign.client.config.inventory-service.url", () -> mockWebServer.url("/").url().toString()); } @Autowired private InventoryClient inventoryClient; @BeforeAll static void start() throws IOException { mockWebServer.start(); } @AfterAll static void stop() throws IOException { mockWebServer.shutdown(); } @Test void 请求头里自动带上Token() throws InterruptedException { mockWebServer.enqueue(new MockResponse() .setResponseCode(200) .setHeader("Content-Type", "application/json") .setBody("{\"skuId\":\"SKU_600\",\"stock\":88}")); inventoryClient.getInventory("SKU_600"); RecordedRequest request = mockWebServer.takeRequest(); assertEquals("a1b2c3d4e5f6", request.getHeader("X-Gw-Token")); } @Test void 400错误被解码为业务异常() { mockWebServer.enqueue(new MockResponse() .setResponseCode(400) .setBody("{\"error\":\"sku not found\"}")); IllegalArgumentException exception = assertThrows(IllegalArgumentException.class, () -> inventoryClient.getInventory("SKU_700")); assertEquals("参数不合法", exception.getMessage()); } }

这一步的含金量在于：它不是空手测一个裸的 Feign 方法，而是测了 Spring 容器把拦截器、错误解码器真正装配到 Feign 代理里的整体效果。如果你只是用 Mockito，那就只能 mock 掉整个 Feign 接口，这些增强逻辑永远不会执行，测出来的代码在真实运行时可能又是另一套表现。

5.3 集成测试里的@DynamicPropertySource容易踩的坑

第一个坑是参数名写错。Feign 客户端的配置层级是spring.cloud.openfeign.client.config.<name>.<property>，不是spring.cloud.openfeign.client.<name>.<property>。少一个config，注册的 URL 根本不会被 Feign 读取。

第二个坑是每个测试类都要自己@DynamicPropertySource，代码有点冗余。可以把这套逻辑抽成一个基类：

public abstract class FeignMockServerSupport { protected static MockWebServer mockWebServer = new MockWebServer(); @BeforeEach void setUpServer() throws IOException { if (!mockWebServer.started) { mockWebServer.start(); } } @AfterEach void tearDownServer() throws IOException { mockWebServer.shutdown(); } }

然后每个测试类继承它并注册属性。不过mockWebServer.started这个字段在较新版本中被移除了，建议自定义一个标志位：

private static boolean serverStarted = false; @BeforeEach void setUpServer() throws IOException { if (!serverStarted) { mockWebServer.start(); serverStarted = true; } }

如果每个测试类都各启一个 MockWebServer、且并行跑测试，还会遇到端口不够用或端口冲突的问题。我的建议是单个测试类内部用共享 MockWebServer，但不同测试类之间最好不要并行启用太多实例，CI 机器上资源有限时容易翻车。

6. 常见问题与排查技巧实录

这一章整理的是我在多个项目里实际踩过的坑，也包括社区里高频提问的场景，每一类都附上排查思路和解决方案。

6.1 MockWebServer 与 Feign 的 URL 拼接对不上

现象：Feign 请求发到http://localhost:端口/api/xxx，但 MockWebServer 收到的路径是/api/xxx或/或完全混乱。

原因：mockWebServer.url("/").url().toString()返回的字符串通常会带两个斜杠或者不带路径，比如http://localhost:12345/。而 @FeignClient 的url属性可能要求不带尾斜杠。Feign 在处理 path 拼接时，如果既有尾斜杠又有@GetMapping("/api/...")，容易得到http://localhost:12345//api/xxx这种双斜杠路径，MockWebServer 通常不会直接爆 404，但断言时会发现路径多了一个斜杠，导致路径比配逻辑失灵。

排查：在断言处打印request.getPath()，结合@FeignClient(url)和@GetMapping的拼接规则检查。解决方式是在@DynamicPropertySource里注册 URL 时去掉尾斜杠：

registry.add("...", () -> mockWebServer.url("/").url().toString().replaceAll("/$", ""));

6.2 响应体出现乱码或 JSON 解析失败

现象：MockWebServer 预设了 JSON 响应，但 Feign 客户端拿到的数据乱码，或抛JsonParseException。

原因：最常见的是 MockResponse 没有设置正确的Content-Type，Feign 的 JacksonDecoder 依赖 Content-Type 判断用哪种反序列化器。也有可能是 MockResponse 设置Content-Type时用了错误的字符集，比如application/json而没写;charset=UTF-8，中文内容就乱码。

处理：所有含 JSON body 的 MockResponse 统一加这两个 Header：

.setHeader("Content-Type", "application/json;charset=UTF-8") .setBody("{\"skuId\":\"SKU_中文\",\"stock\":1}")

如果你的 Feign 配置了自定义 Encoder/Decoder，也记得测试里手动指定（裸 Feign 测试场景）或确保 Spring 装配生效（集成测试场景）。

6.3 Feign 连接被拒（Connection refused）

现象：测试启动后调用 Feign 接口，抛java.net.ConnectException: Connection refused。

原因：九成是因为 MockWebServer 还没 start() 就调用了 Feign 接口。另外一成的可能性是 URL 配成了固定的http://localhost:8080而不是从 MockWebServer 动态获取的端口。

排查：确认@BeforeAll或@BeforeEach里执行了mockWebServer.start()；确认@DynamicPropertySource里的 URL 是用mockWebServer.url("/")动态生成的，而不是写死端口。如果写死端口，在 CI 或本地并行测试时很容易冲突出问题。

6.4 测试之间响应串了：B 测试拿到 A 测试的响应

现象：两个测试用例在同一个测试类里执行，第二个测试调用 Feign 接口时，MockWebServer 返回了第一个测试预设的响应。

原因：MockWebServer 的队列是"先进先出"的，如果某个测试用例里 enqueue 的响应没被消费完，队列里残留的响应会被下一个测试消费掉。特别是当 Feign 因为某个异常导致请求没发出去，或者重试逻辑发了多次请求时，队列容易残留。

处理：在每个@AfterEach里清空队列。MockWebServer 没有直接提供"清空队列"的 API，但可以takeRequest()把残留的请求吃掉，或者重新实例化一个 MockWebServer（测试类内共享实例时不适合）。更稳妥的方案是引入 Dispatcher 替代队列模式，让每次请求都按路径动态匹配，从根上避免队列残留问题。

6.5 重试导致 MockWebServer 被重复请求轰炸

现象：Feign 配置了重试，下游返回 500，Feign 疯狂重试，MockWebServer 队列空了，测试直接断言失败或者出现 InterruptedException。

原因：这是最常见的"重试 + MockWebServer"组合坑。getRequestCount()可以看到发出了很多请求，但队列里的 MockResponse 早用完了。

处理：在 Dispatcher 里对 5xx 场景专门返回 500，让它稳定重试指定次数后返回 200。或者嫌麻烦，直接在测试里关闭 Feign 重试（设置spring.cloud.openfeign.retry.enabled=false），只测重试本身的场景时再单独开启。我的建议是：专门写一个测试验证重试逻辑，其余测试统一关闭重试，避免互相干扰。

7. 工具选型辨析：MockWebServer 与相关测试手段如何搭配

7.1 与 WireMock 的选择——什么时候各有用武之地

WireMock 的优势是它原生支持"按 URL、请求头、请求体做条件匹配"，还有独立的"录制回放"能力，可以做契约测试。但它的 Mock 规则配置复杂，学习成本更高，且依赖更重。在实际项目里，如果只是给 Feign 客户端做单元测试，我基本只用 MockWebServer；只有在做消费者驱动的契约测试（比如把下游服务提供的契约文件在 CI 里跑回归）时，我才会引入 WireMock。普通团队根本不需要一上来就搞契约测试，先解决"本地能不能稳定测 Feign"的问题。

7.2 与 Spring Cloud Contract / Testcontainers 的搭档关系

如果你已经引入了 Testcontainers（真实下游服务跑在 Docker 容器里），MockWebServer 也并不是被替代的对象，而是互补关系。Testcontainers 适合测"下游服务的真实行为"——比如你真的需要依赖 Redis 或 MySQL 时，容器化的服务能提供更接近真实的语义；但下游服务如果是简单的 HTTP 接口、且启动很重，Testcontainers 的成本就远高于 MockWebServer。我的实践习惯是：

• Feign 客户端自身的序列化、路由、错误处理逻辑-> MockWebServer
• 下游服务的真实数据库/缓存行为-> Testcontainers
• 多服务间复杂联动验证-> 写一套轻量集成测试，让每个服务各自用 MockWebServer 模拟邻居

这样拆分下来，每层测试的目标都非常聚焦，跑起来也快。

7.3 用 Docker Compose 起一套下游依赖不是更真实？为什么还是推荐 MockWebServer

很多人会问：反正都是假接口，用 Docker 起一个真实下游服务不是更好吗？答案是"慢"和"脆"。本地跑测试时，Docker 依赖网络拉镜像、容器启动，没有几秒起不来；CI 环境如果没开 Docker 守护进程，整套测试直接不可用。而 MockWebServer 是一个进程内的 Socket 服务，毫秒级启动，天然和 JUnit 生命周期绑定，测试结束自动关闭。对"验证 Feign 客户端逻辑"这个单一目标来说，Docker 带来的"真实"完全是多余的成本。

8. 落地的最后一步：把测试塞进 CI 流水线

测试写好了，如果不跑，等于白写。我在多个团队落地这套方案后，总结了几个能保证"测试一直在跑且能发现问题"的关键配置。

第一，给 Feign 测试单独打 Maven Surefire 插件标签，避免它们和应用的慢速集成测试混在一起。比如：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <configuration> <includes> <include>**/*Feign*Test.java</include> <include>**/*MockServer*Test.java</include> </includes> </configuration> </plugin>

第二，把 Feign 测试放进git commit前的最小验证集。我个人的习惯是：本地提交前跑一遍"裸 Feign 单测"（几百个用例，秒级完成），推分支后再由 CI 跑完整套集成测试。第三，对核心链路的 Feign 集成测试设置超时阈值，如果一个测试超过 10 秒还没跑完，说明下游模拟出了大问题，让流水线直接失败提醒排查。

实际踩过的一个教训是：某团队把 Feign 集成测试和整个应用的测试混在一起，每次 CI 都要跑 20 分钟，维护热情很快就耗尽了。后来我把所有 Feign 测试拆到独立的 Maven profile 中，配合 CI 的 parallel stage，总耗时从 20 分钟降到 4 分钟，测试质量反而更受重视了。

9. 写在最后：MockWebServer 帮我抓到的那些"隐藏炸弹"

在多个项目里实践下来，MockWebServer + @FeignClient 这套组合带给我的最大价值，不只是一个可用的测试工具，而是把"接口调用"从"联调阶段的黑盒"变成了"写代码阶段就能验证的白盒"。

举两个印象很深的例子。第一个是我帮某公司排查一个线上偶发超时问题。代码 review 了很久都没发现异常，用 MockWebServer 模拟 1 秒延迟后，立刻复现出 Feign 默认超时配置太短的问题。第二个是另一个项目的 Feign 接口，本来测试用例写好了，结果第一次跑就发现请求路径多了个尾斜杠，导致下游 404——这个 bug 在真实环境里出现了好几次，却一直没人想到是路径拼接的问题。

我自己现在写 Feign 接口的流程是：先定义接口和 DTO，写好业务代码，紧接着写一套 MockWebServer 单测，验证成功路径、错误路径、超时行为、拦截器逻辑，确认所有行为符合预期后再交给联调。联调阶段反而变得轻松很多，因为 90% 的问题在本地测试阶段就已经暴露并修掉了。

最后一个小建议：别把 MockWebServer 当万能药。它适合模拟"协议端点"层面的行为，但如果你需要验证"下游确实按预期处理了某个业务规则"，那仍然需要走真实的集成测试甚至端到端测试。把每一层测试的目标定义清楚，工具才能真正发挥价值。