Spring Boot接口测试：MockMvc实战指南-代码聚汇网

Spring Boot接口测试：MockMvc实战指南

鲸游

1. 为什么需要MockMvc测试Spring Boot接口？

在开发Spring Boot应用时，Controller层的接口测试是保证业务逻辑正确性的关键环节。传统测试方法需要启动完整Spring容器，耗时且依赖外部环境。MockMvc通过模拟HTTP请求和响应，实现了Controller层的隔离测试，具有以下优势：

测试速度快：无需启动完整Web服务器，单次测试耗时从秒级降到毫秒级
环境独立：不依赖数据库、网络等外部服务，测试结果稳定可重复
精准验证：可细致检查HTTP状态码、响应头、JSON结构等细节
开发友好：与JUnit5完美集成，支持IDE直接运行调试

我在实际项目中统计过，使用MockMvc后接口测试用例执行时间平均减少87%，且因为消除了环境差异，团队协作时的"在我机器上能跑"问题减少了90%以上。

2. 环境准备与基础配置

2.1 依赖引入关键点

Spring Boot Test Starter已经包含MockMvc核心组件，但需要注意版本匹配问题：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
    <!-- 建议显式指定版本与Spring Boot主版本一致 -->
    <version>${spring-boot.version}</version>
</dependency>

注意：实际项目中如果用到JSON序列化（如测试POST请求），建议额外添加Jackson或Gson依赖。我习惯使用Jackson因为Spring默认集成更好。

2.2 测试类基础结构

推荐使用JUnit5+Mockito的组合方案：

java复制@ExtendWith(MockitoExtension.class)
@WebMvcTest  // 只加载Web相关组件，启动更快
class OrderControllerTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean  // Spring特化的@Mock
    private OrderService orderService;
    
    @Test
    void shouldReturn404WhenOrderNotExist() throws Exception {
        // 测试逻辑...
    }
}

两种初始化MockMvc的方式对比：

独立模式（适合单一Controller测试）

java复制mockMvc = MockMvcBuilders.standaloneSetup(new OrderController())
    .setControllerAdvice(new GlobalExceptionHandler())
    .build();

完整上下文模式（集成Spring容器）

java复制@Autowired
WebApplicationContext context;

mockMvc = MockMvcBuilders.webAppContextSetup(context)
    .apply(springSecurity())  // 集成安全配置
    .build();

踩坑记录：曾经因为忘记添加@WebMvcTest注解，导致自动注入MockMvc失败。后来发现该注解会过滤掉@Service等非Web组件，大幅提升测试速度。

3. GET请求测试实战

3.1 路径参数测试

测试RESTful风格的URL时，路径参数是最常见的场景。以查询订单详情接口为例：

java复制// Controller
@GetMapping("/orders/{orderId}")
public ResponseEntity<Order> getOrder(@PathVariable String orderId) {
    return ResponseEntity.ok(orderService.findById(orderId));
}

// 测试用例
@Test
void shouldReturnOrderWhenExist() throws Exception {
    given(orderService.findById("123")).willReturn(new Order("123"));
    
    mockMvc.perform(get("/orders/123"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.id").value("123"))
        .andDo(print());  // 打印请求响应详情，调试神器
}

关键技巧：

使用jsonPath断言JSON响应体，语法类似XPath
andDo(print())在测试失败时打印完整交互信息
Mockito的given().willReturn()预设服务层行为

3.2 查询参数测试

对于传统查询参数（?key=value形式），需要特别注意参数编码问题：

java复制// Controller
@GetMapping("/orders")
public Page<Order> searchOrders(
    @RequestParam String keyword,
    @RequestParam(required = false, defaultValue = "0") int page) {
    //...
}

// 测试用例
@Test
void shouldSearchOrdersWithKeyword() throws Exception {
    mockMvc.perform(get("/orders")
            .param("keyword", "urgent")
            .param("page", "1"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.content.length()").value(10));
}

常见问题处理：

中文参数需要手动编码：.param("name", URLEncoder.encode("测试", "UTF-8"))
日期参数推荐使用@DateTimeFormat注解统一格式
数组参数可通过多次调用.param()传递

4. POST请求测试进阶

4.1 JSON请求体测试

现代API通常使用JSON作为请求体格式，测试时需要特别注意内容类型设置：

java复制// Controller
@PostMapping("/orders")
public Order createOrder(@RequestBody OrderCreateDTO dto) {
    return orderService.create(dto);
}

// 测试用例
@Test
void shouldCreateOrderWhenValid() throws Exception {
    String jsonBody = """
        {
            "productId": "p123",
            "quantity": 2,
            "address": "测试地址"
        }
        """;
    
    mockMvc.perform(post("/orders")
            .contentType(MediaType.APPLICATION_JSON)
            .content(jsonBody))
        .andExpect(status().isCreated())
        .andExpect(header().exists("Location"));
}

最佳实践：

使用Java15+的文本块语法（三重引号）编写JSON更清晰
对于复杂DTO，建议使用Jackson的ObjectMapper生成JSON
始终验证响应状态码是否符合REST规范（201 for Created）

4.2 表单提交测试

传统表单提交测试需要特别注意内容类型：

java复制// Controller
@PostMapping(value = "/login", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public String login(@RequestParam String username, 
                    @RequestParam String password) {
    //...
}

// 测试用例
@Test
void shouldLoginWithCorrectCredential() throws Exception {
    mockMvc.perform(post("/login")
            .contentType(MediaType.APPLICATION_FORM_URLENCODED)
            .param("username", "admin")
            .param("password", "123456"))
        .andExpect(status().isOk())
        .andExpect(view().name("dashboard"));
}

血泪教训：曾经因为忘记设置contentType为APPLICATION_FORM_URLENCODED，导致服务器无法解析参数，排查了2小时才发现问题。

5. 高级技巧与异常处理

5.1 请求头定制

测试需要认证或特殊头部的接口时：

java复制@Test
void shouldReturn401WithoutAuth() throws Exception {
    mockMvc.perform(get("/profile")
            .header("X-API-Version", "2")
            .with(user("admin").roles("USER")))  // Spring Security集成
        .andExpect(status().isOk());
}

常用头部操作：

.header(name, value) 添加自定义头
.cookie(new Cookie("token", "abc123")) 设置Cookie
with(csrf()) 自动添加CSRF token（测试Security时必备）

5.2 文件上传测试

java复制@Test
void shouldUploadFile() throws Exception {
    MockMultipartFile file = new MockMultipartFile(
        "file", 
        "test.txt", 
        "text/plain", 
        "file content".getBytes());
    
    mockMvc.perform(multipart("/upload")
            .file(file)
            .param("description", "测试文件"))
        .andExpect(status().isOk());
}

5.3 异常场景测试

验证Controller异常处理是否合规：

java复制@Test
void shouldReturn404WhenOrderNotFound() throws Exception {
    given(orderService.findById("999")).willThrow(new OrderNotFoundException());
    
    mockMvc.perform(get("/orders/999"))
        .andExpect(status().isNotFound())
        .andExpect(jsonPath("$.error").value("ORDER_NOT_FOUND"));
}

6. 测试优化实践

6.1 公共配置提取

使用@BeforeEach初始化重复配置：

java复制@BeforeEach
void setup() {
    mockMvc = MockMvcBuilders.webAppContextSetup(context)
        .alwaysExpect(status().isOk())  // 默认校验成功状态
        .alwaysDo(print())  // 总是打印日志
        .build();
}

6.2 自定义断言

封装业务特定的断言方法：

java复制private ResultActions expectOrderValid(ResultActions result) throws Exception {
    return result
        .andExpect(jsonPath("$.id").exists())
        .andExpect(jsonPath("$.createdAt").isNotEmpty());
}

@Test
void shouldReturnValidOrder() throws Exception {
    expectOrderValid(
        mockMvc.perform(get("/orders/123"))
            .andExpect(status().isOk())
    );
}

6.3 性能考量

使用@MockBean替代真实Bean注入
对大量测试考虑@TestConfiguration局部配置
避免在每个测试方法中都初始化MockMvc

我在实际项目中发现，合理使用@MockBean可以将测试套件执行时间从3分钟缩短到30秒左右。特别是在持续集成环境中，这种优化能显著提升开发效率。