Spring Boot REST 控制器 JUnit 测试指南与常见陷阱

本文深入探讨了spring boot rest控制器进行junit测试的最佳实践。我们将学习如何利用`@webmvctest`和`mockmvc`对控制器层进行隔离测试，并重点讲解如何正确模拟控制器依赖的服务层组件。文章还将分析常见测试错误，提供结构清晰、代码示例丰富的解决方案，旨在帮助开发者编写高效、可靠的控制器单元测试。

引言：Spring Boot 控制器测试的重要性

在Spring Boot应用开发中，对REST控制器进行单元测试是确保API行为正确、提高代码质量的关键环节。控制器作为处理HTTP请求并调用业务逻辑的入口，其测试通常需要模拟HTTP请求、验证响应内容以及隔离底层服务依赖。Spring Boot提供了强大的测试工具，如@WebMvcTest和MockMvc，使得控制器测试变得高效且易于管理。

理解 @WebMvcTest 与 MockMvc

@WebMvcTest 的作用与范围

@WebMvcTest 是一个专门用于测试Spring MVC控制器的切片测试注解。它会自动配置与MVC层相关的组件，例如@Controller、@ControllerAdvice、@JsonComponent、Filter、WebMvcConfigurer等，但不会加载完整的应用上下文。这意味着它不会扫描@Service、@Component、@Repository等注解的Bean，从而将测试范围限定在Web层，提高测试效率和隔离性。

使用@WebMvcTest时，通常需要指定要测试的控制器类，例如@WebMvcTest(MyController.class)。

MockMvc 的使用

MockMvc 是Spring Test模块提供的一个核心工具，用于模拟对Spring MVC控制器执行HTTP请求。它允许我们在不启动完整HTTP服务器的情况下，测试控制器的行为。通过MockMvc，我们可以构建请求（指定URL、HTTP方法、参数、请求头、请求体等），执行请求，并对响应进行断言（验证状态码、响应头、响应体等）。

重构与优化控制器测试

为了更好地演示和理解控制器测试，我们首先假设一个具有服务层依赖的控制器：

// MyService.javapackage com.test.project.service;import com.test.project.beans.RequestModel;import java.util.Map;public interface MyService {    Map deleteUploadedFile(RequestModel requestModel);}// MyServiceImpl.java (实际实现，在控制器测试中会被Mock)package com.test.project.service;import com.test.project.beans.RequestModel;import org.springframework.stereotype.Service;import java.util.Collections;import java.util.HashMap;import java.util.Map;@Servicepublic class MyServiceImpl implements MyService {    @Override    public Map deleteUploadedFile(RequestModel requestModel) {        // 实际的业务逻辑，例如调用数据仓库        System.out.println("Deleting file for requestData: " + requestModel.getRequestData());        Map result = new HashMap();        result.put("status", "success");        result.put("message", "File deleted successfully for " + requestModel.getRequestData());        return result;    }}// RequestModel.javapackage com.test.project.beans;public class RequestModel {    private String requestData;    public String getRequestData() {        return requestData;    }    public void setRequestData(String requestData) {        this.requestData = requestData;    }}// MyController.javapackage com.test.project.web;import com.test.project.beans.RequestModel;import com.test.project.service.MyService;import org.springframework.web.bind.annotation.*;import java.util.Map;import java.util.HashMap;@RestController // 使用 @RestController 更符合 RESTful API 惯例@RequestMapping(path = "/project-files")public class MyController {    private final MyService service; // 依赖 MyService 接口    // 通过构造器注入依赖    public MyController(MyService service) {        this.service = service;    }    private RequestModel setRequestModel(String params) {        RequestModel requestModel = new RequestModel();        requestModel.setRequestData(params);        return requestModel;    }    @PostMapping("/deleteUploadedFile")    public Map deleteUploadedFile(@RequestParam(value = "requestData", required = false) String params) {        RequestModel requestModel = setRequestModel(params);        // 调用服务层逻辑        return service.deleteUploadedFile(requestModel);    }}

原始问题分析与常见错误

原始的测试代码存在以下几个主要问题：

java.lang.IllegalStateException: Failed to load ApplicationContext:

原因：当使用@WebMvcTest(MyController.class)时，Spring Boot会配置一个精简的上下文，用于测试Web层。然而，在@Before方法中，又使用了MockMvcBuilders.standaloneSetup(new MyController()).build()。这两种MockMvc的构建方式是冲突的。@WebMvcTest已经提供了预配置的MockMvc实例，直接注入即可。standaloneSetup通常用于不依赖Spring上下文的纯POJO控制器测试。解决方案：移除@Before方法中的MockMvc构建逻辑，直接通过@Autowired注入由@WebMvcTest提供的MockMvc实例。

HTTP 方法不匹配:

控制器中deleteUploadedFile方法使用了@PostMapping，但在测试中却使用了MockMvcRequestBuilders.get(uri)。这会导致请求无法匹配到正确的处理器。解决方案：测试时应使用MockMvcRequestBuilders.post(uri)。

不正确的断言和响应解析:

测试代码尝试将响应内容解析为MyController[]类型 (super.mapFromJson(content, MyController[].class))，这显然是错误的。控制器方法返回的是Map，而不是控制器数组。解决方案：响应内容应解析为Map类型，并对Map中的键值进行断言。

不必要的 @InjectMocks:

测试代码中声明了@InjectMocks serviceImpl和@InjectMocks dataRepoImpl，但这些依赖在MyController中并未直接体现（控制器只依赖MyService接口），并且在@WebMvcTest环境下，它们也不会被自动注入到MyController中。@WebMvcTest不会加载这些非Web层的Bean。解决方案：对于控制器依赖的服务层组件，应使用@MockBean进行模拟，而不是@InjectMocks。

正确配置测试环境与模拟依赖

注入 MockMvc:

@Autowiredprivate MockMvc mockMvc; // 由 @WebMvcTest 自动提供

模拟服务层依赖:

@WebMvcTest不会加载服务层Bean，因此我们需要使用@MockBean来为控制器所依赖的MyService接口创建一个模拟（Mock）实例。这样，当控制器调用service.deleteUploadedFile()时，实际上会调用这个模拟实例的方法，我们可以预设其行为。

白瓜面试

白瓜面试 – AI面试助手,辅助笔试面试神器

40 查看详情

@MockBeanprivate MyService myService; // 模拟 MyController 所依赖的 MyService

移除冲突的 setup 方法:

// 移除 @Before public void setup() { ... }

编写请求与断言

使用MockMvc执行请求并进行断言时，应遵循以下模式：

mockMvc.perform(requestBuilder) // 执行请求       .andExpect(status().isOk()) // 验证HTTP状态码       .andExpect(content().contentType(MediaType.APPLICATION_JSON)) // 验证响应内容类型       .andExpect(jsonPath("$.status").value("success")) // 验证JSON响应体中的特定字段       .andReturn(); // 获取 MvcResult 以进行更复杂的处理

MockMvcRequestBuilders提供了各种HTTP方法的静态方法，例如get()、post()、put()、delete()等。

示例：一个完善的控制器测试

下面是一个针对MyController的完善的JUnit测试案例，它解决了上述所有问题并遵循了最佳实践：

package com.test.project.web;import static org.mockito.ArgumentMatchers.any;import static org.mockito.Mockito.when;import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;import com.fasterxml.jackson.databind.ObjectMapper;import com.test.project.beans.RequestModel;import com.test.project.service.MyService;import java.util.HashMap;import java.util.Map;import org.junit.jupiter.api.BeforeEach; // 推荐使用 JUnit 5 的 BeforeEachimport org.junit.jupiter.api.Test;import org.springframework.beans.factory.annotation.Autowired;import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;import org.springframework.boot.test.mock.mockito.MockBean;import org.springframework.http.MediaType;import org.springframework.test.web.servlet.MockMvc;import org.springframework.test.web.servlet.MvcResult;// 使用 JUnit 5 的 @WebMvcTest 和 @ExtendWith(SpringExtension.class) 或直接使用 @SpringBootTest// 对于 JUnit 4，使用 @RunWith(SpringRunner.class)@WebMvcTest(MyController.class)public class MyControllerTest {    @Autowired    private MockMvc mockMvc; // 由 @WebMvcTest 自动注入    @MockBean // 模拟 MyController 所依赖的 MyService    private MyService myService;    // ObjectMapper 用于 JSON 序列化/反序列化，如果需要的话    private ObjectMapper objectMapper = new ObjectMapper();    @BeforeEach // JUnit 5 的 setup 方法    void setUp() {        // 可以在这里进行一些通用的 Mock 配置或初始化        // 例如，如果 MyController 有其他共同依赖，可以在这里模拟    }    @Test    void deleteFile_shouldReturnSuccessStatus() throws Exception {        String requestDataParam = "test_file.txt";        String expectedMessage = "File deleted successfully for " + requestDataParam;        // 模拟 MyService 的行为        Map serviceResult = new HashMap();        serviceResult.put("status", "success");        serviceResult.put("message", expectedMessage);        // 当 myService.deleteUploadedFile 方法被调用时，返回 serviceResult        when(myService.deleteUploadedFile(any(RequestModel.class)))            .thenReturn(serviceResult);        // 执行 POST 请求到 /project-files/deleteUploadedFile        // 使用 .param() 方法传递 @RequestParam 参数        MvcResult mvcResult = mockMvc.perform(post("/project-files/deleteUploadedFile")                .param("requestData", requestDataParam) // 传递 requestData 参数                .accept(MediaType.APPLICATION_JSON)) // 期望接受 JSON 响应                .andExpect(status().isOk()) // 验证 HTTP 状态码为 200 OK                .andExpect(jsonPath("$.status").value("success")) // 验证 JSON 响应体中的 status 字段                .andExpect(jsonPath("$.message").value(expectedMessage)) // 验证 message 字段                .andReturn();        // 如果需要进一步解析响应内容        String content = mvcResult.getResponse().getContentAsString();        Map responseMap = objectMapper.readValue(content, Map.class);        // 可以进行更细致的断言        assert(responseMap.get("status").equals("success"));        assert(responseMap.get("message").equals(expectedMessage));    }    @Test    void deleteFile_shouldHandleNullRequestData() throws Exception {        String expectedMessage = "File deleted successfully for null"; // 假设服务层处理 null        Map serviceResult = new HashMap();        serviceResult.put("status", "success");        serviceResult.put("message", expectedMessage);        when(myService.deleteUploadedFile(any(RequestModel.class)))                .thenReturn(serviceResult);        mockMvc.perform(post("/project-files/deleteUploadedFile")                // 不传递 requestData 参数，因为 required = false                .accept(MediaType.APPLICATION_JSON))                .andExpect(status().isOk())                .andExpect(jsonPath("$.status").value("success"))                .andExpect(jsonPath("$.message").value(expectedMessage));    }}

注意事项：

JUnit 版本: 上述示例使用了JUnit 5的注解（@BeforeEach, @Test），如果使用JUnit 4，请将@BeforeEach替换为@Before，并确保@WebMvcTest与@RunWith(SpringRunner.class)配合使用。

参数命名: 控制器中的@RequestParam(value = “requestData”, required = false) String params，建议将变量名params改为requestData，以提高可读性。在测试中，使用param(“requestData”, requestDataParam)来匹配。

mapFromJson: 在@WebMvcTest环境中，通常使用ObjectMapper直接将MvcResult.getResponse().getContentAsString()解析为预期的Java对象或Map，而不是通过super.mapFromJson这样的辅助方法。

@DeleteMapping: 对于删除操作，更符合RESTful风格的最佳实践是使用@DeleteMapping注解，例如：

@DeleteMapping("/uploadedFile") // URL 更简洁，通常通过路径变量或请求参数指定要删除的资源public Map deleteUploadedFile(@RequestParam("id") String fileId) {    // ...    return service.deleteFile(fileId);}

相应的测试也应改为mockMvc.perform(delete(“/project-files/uploadedFile”).param(“id”, “123”))。

总结与注意事项

编写Spring Boot控制器测试时，请牢记以下几点：

选择正确的测试注解：使用@WebMvcTest进行Web层切片测试，它只加载与MVC相关的组件，提高测试效率。利用 MockMvc 模拟请求：通过MockMvc构建HTTP请求，并使用其提供的断言方法链式验证响应。模拟依赖服务：对于控制器所依赖的服务层或其他非Web层组件，使用@MockBean创建模拟对象，并通过Mockito.when().thenReturn()预设其行为。避免在@WebMvcTest中使用@InjectMocks来注入非Web层的Bean。匹配 HTTP 方法：确保测试中使用的HTTP方法（GET, POST, PUT, DELETE）与控制器方法上定义的注解一致。精确断言：除了验证状态码，还要对响应内容（如JSON字段、文本内容）进行精确断言，确保控制器返回的数据符合预期。专注于控制器逻辑：控制器测试的重点是验证HTTP请求到控制器方法调用、参数绑定、以及返回结果的正确性。不应在控制器测试中测试服务层的业务逻辑，那应该由服务层自己的单元测试来完成。清晰的变量命名：使用描述性强的变量名，使代码更易读、易懂。

通过遵循这些原则，您可以编写出高效、可靠且易于维护的Spring Boot控制器单元测试。

以上就是Spring Boot REST 控制器 JUnit 测试指南与常见陷阱的详细内容，更多请关注创想鸟其它相关文章！