spring boot 3 项目若同时引入了 webflux（如 spring-boot-starter-webflux 或 spring-cloud-starter-gateway），则默认启用响应式 web 栈，此时 mockmvc 不再可用——因其专为 spring mvc 设计；应改用 testwebclient 进行端点测试。
spring boot 3 项目若同时引入了 webflux（如 spring-boot-starter-webflux 或 spring-cloud-starter-gateway），则默认启用响应式 web 栈，此时 mockmvc 不再可用——因其专为 spring mvc 设计；应改用 testwebclient 进行端点测试。
在 Spring Boot 3 中，MockMvc 是基于 Servlet 容器和 DispatcherServlet 构建的测试工具，仅适用于阻塞式、基于 Spring MVC 的 Web 应用。而一旦项目中引入了 spring-boot-starter-webflux 或 spring-cloud-starter-gateway（二者均依赖 WebFlux），Spring Boot 将自动切换至响应式编程模型，底层使用 WebHandler 和 ReactorHttpHandlerAdapter，不再启动 DispatcherServlet。因此，@AutoConfigureMockMvc 注解失效，Spring 容器无法创建 MockMvc Bean，最终抛出 NoSuchBeanDefinitionException。
✅ 正确做法：使用 WebTestClient（注意：Spring Boot 2.2+ 及 Spring 5+ 中统一命名为 WebTestClient，而非旧文档中偶见的 TestWebClient）替代 MockMvc，它是专为 WebFlux 设计的全功能、非阻塞式测试客户端，支持函数式路由、服务端事件（SSE）、WebSocket 等特性，并可无缝集成到 @SpringBootTest 环境中。
✅ 正确配置与示例代码
确保测试类满足以下条件：
- 使用 @SpringBootTest（必要，用于加载完整应用上下文）；
- 无需 @AutoConfigureMockMvc（该注解对 WebFlux 无效，应移除）；
- 自动注入 WebTestClient（Spring Boot 会自动配置并注册 Bean）；
- 若需模拟安全上下文，可搭配 @WithMockUser 或 @AutoConfigureWebTestClient（可选，通常非必需）。
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.reactive.server.WebTestClient;
import static org.springframework.http.HttpStatus.OK;
@SpringBootTest
// @AutoConfigureWebTestClient 可省略（Spring Boot 3 默认启用），但显式声明更清晰
@AutoConfigureWebTestClient
public class FooTest {
@Autowired
private WebTestClient webClient;
@Test
void testFooEndpointReturnsOk() {
webClient.get()
.uri("/foo")
.exchange()
.expectStatus().isEqualTo(OK)
.expectBody(String.class).isNotEmpty();
}
}
? 补充说明：WebTestClient 支持两种模式：
- 绑定到真实服务器（WebTestClient.bindToServer()）：需手动指定 baseUrl，适用于集成测试；
- 绑定到应用上下文（WebTestClient.bindToApplicationContext(...)）：即上述 @SpringBootTest 场景，默认行为，推荐使用。
⚠️ 注意事项与常见误区
- ❌ 不要混用 @AutoConfigureMockMvc 和 WebFlux 依赖：这会导致配置冲突且无实际效果；
- ❌ 不要手动创建 WebTestClient 实例（如 new WebTestClient.builder()）：将丢失 Spring 容器管理的 Bean 注入（如 SecurityContext、ReactiveOAuth2AuthorizedClientManager 等）；
- ✅ 若项目同时存在 MVC 和 WebFlux 控制器（不推荐），应明确区分测试目标：MVC 接口用 MockMvc + @WebMvcTest，WebFlux 接口用 WebTestClient + @WebFluxTest 或 @SpringBootTest；
- ✅ spring-boot-starter-test 已包含 spring-test 和 spring-webflux 测试支持，无需额外添加依赖（您的 pom.xml 中已正确定义）；
- ✅ spring-cloud-starter-gateway 显式引入 WebFlux，是触发该问题的典型原因——检查是否确实需要网关；若仅为 API 服务，建议移除该依赖以回归 MVC 模式。
✅ 总结
| 场景 | 推荐测试客户端 | 关键注解 | 适用模块 |
|---|---|---|---|
| Spring MVC（spring-boot-starter-web） | MockMvc | @WebMvcTest / @SpringBootTest + @AutoConfigureMockMvc | spring-webmvc |
| Spring WebFlux（spring-boot-starter-webflux, spring-cloud-gateway） | WebTestClient | @SpringBootTest（自动配置）或 @WebFluxTest | spring-webflux |
遇到 No qualifying bean of type 'MockMvc' 错误时，请首先检查项目是否意外引入了 WebFlux 相关 Starter——这是 Spring Boot 3 中最常见且易被忽略的根本原因。切换至 WebTestClient 后，不仅能解决问题，还能获得更符合响应式语义的测试体验。
