# 使用 MockMvc 对 REST 控制器进行单元测试 ## 概述此技能提供了使用 MockMvc 单元测试 @RestController 和 @Controller 类的模式。它涵盖了通过模拟隔离控制器测试的服务依赖关系来测试请求/响应处理、HTTP 状态代码、请求参数绑定、验证、内容协商、响应标头和异常处理。 ## 何时使用在以下情况下使用此技能： * 测试 REST 控制器请求/响应处理 * 验证HTTP状态码和响应格式 * 测试请求参数绑定和验证 * 用于隔离控制器测试的模拟服务层 * 测试内容协商和响应标头 * 想要快速控制器测试而无需集成测试开销 ## 说明 1. **使用独立的 MockMvc 设置** ：使用 `MockMvcBuilders.standaloneSetup(controller)` 进行隔离测试 2. **模拟所有服务依赖** ：对注入控制器的所有服务使用@Mock 3. **测试所有 HTTP 方法** ：使用适当的状态代码验证 GET、POST、PUT、PATCH、DELETE 4. **验证请求/响应格式** ：使用 JsonPath 断言进行 JSON 响应验证 5. **测试验证错误** ：发送无效请求并验证 400 状态以及错误详细信息 6. **测试错误场景**：验证 404、400、401、403、500 状态代码是否符合适当条件 7. **测试标头** ：验证请求标头（授权）和响应标头 8. **使用内容协商**：使用不同的 Accept 和 Content-Type 标头进行测试 ## 示例 ## 设置：MockMvc + Mockito ### Maven <依赖关系> org.springframework.boot spring-boot-starter-test <范围>测试 <依赖关系> org.mockito mockito-core <范围>测试 ### 摇篮依赖项{ testImplementation("org.springframework.boot:spring-boot-starter-test") testImplementation("org.mockito:mockito-core") } ## 基本模式：测试 GET 端点 ### 简单的 GET 端点测试导入 org.junit.jupiter.api.Test; 导入 org.junit.jupiter.api.extension.ExtendWith; 导入 org.mockito.InjectMocks; 导入 org.mockito.Mock; 导入 org.mockito.junit.jupiter.MockitoExtension; 导入 org.springframework.test.web.servlet.MockMvc; 导入 org.springframework.test.web.servlet.setup.MockMvcBuilders; 导入静态 org.mockito.Mockito.*; 导入静态org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*; 导入静态org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; @ExtendWith(MockitoExtension.class) 类 UserControllerTest { @模拟私有 UserService 用户服务； @InjectMocks 私有 UserController 用户控制器；私人 MockMvc 模拟Mvc；无效设置（）{ mockMvc = MockMvcBuilders.standaloneSetup(userController).build(); } @测试 void shouldReturnAllUsers() 抛出异常 { 列表用户 = List.of( 新的 UserDto(1L, "爱丽丝"), 新的 UserDto(2L, "鲍勃") ）； when(userService.getAllUsers()).thenReturn(users); mockMvc.perform(get("/api/users")) .andExpect(status().isOk()) .andExpect(jsonPath("$").isArray()) .andExpect(jsonPath("$[0].id").value(1)) .andExpect(jsonPath("$[0].name").value("Alice")) .andExpect(jsonPath("$[1].id").value(2)); 验证(userService, times(1)).getAllUsers(); } @测试 void shouldReturnUserById() 抛出异常 { UserDto 用户 = new UserDto(1L, "Alice"); 当(userService.getUserById(1L)).thenReturn(用户); mockMvc.perform(get("/api/users/1")) .andExpect(status().isOk()) .andExpect(jsonPath("$.id").value(1)) .andExpect(jsonPath("$.name").value("Alice")); 验证(userService).getUserById(1L); } } ## 测试 POST 端点 ### 使用请求正文创建资源 @测试 void shouldCreateUserAndReturn201() 抛出异常 { UserCreateRequest 请求 = new UserCreateRequest("Alice", "alice@example.com"); UserDto 创建的User = new UserDto(1L, "Alice", "alice@example.com"); 当（userService.createUser（任何（UserCreateRequest.class））） .thenReturn(创建的用户); mockMvc.perform(post("/api/users") .contentType(“应用程序/json”) .content("{\"姓名\":\"Alice\",\"电子邮件\":\"alice@example.com\"}")) .andExpect(status().isCreated()) .andExpect(jsonPath("$.id").value(1)) .andExpect(jsonPath("$.name").value("Alice")) .andExpect(jsonPath("$.email").value("alice@example.com")); 验证(userService).createUser(any(UserCreateRequest.class)); } ## 测试错误场景 ### 未找到处理 404 @测试 void shouldReturn404WhenUserNotFound() 抛出异常 { 当（userService.getUserById（999L）） .thenThrow(new UserNotFoundException("未找到用户")); mockMvc.perform(get("/api/users/999")) .andExpect(状态().isNotFound()) .andExpect(jsonPath("$.error").value("未找到用户")); 验证(userService).getUserById(999L); } ### 处理 400 错误请求 @测试 void shouldReturn400WhenRequestBodyInvalid() 抛出异常 { mockMvc.perform(post("/api/users") .contentType(“应用程序/json”) .content("{\"name\":\"\"}")) // 空名称 .andExpect(status().isBadRequest()) .andExpect(jsonPath("$.errors").isArray()); } ## 测试 PUT/PATCH 端点 ### 更新资源 @测试 void shouldUpdateUserAndReturn200() 抛出异常 { UserUpdateRequest request = new UserUpdateRequest("Alice Updated"); UserDto UpdatedUser = new UserDto(1L, "爱丽丝已更新"); 当(userService.updateUser(eq(1L),any(UserUpdateRequest.class))) .thenReturn(updatedUser); mockMvc.perform(put("/api/users/1") .contentType(“应用程序/json”) .content("{\"名称\":\"爱丽丝已更新\"}")) .andExpect(status().isOk()) .andExpect(jsonPath("$.id").value(1)) .andExpect(jsonPath("$.name").value("爱丽丝已更新")); 验证(userService).updateUser(eq(1L),any(UserUpdateRequest.class)); } ## 测试 DELETE 端点 ### 删除资源 @测试 void shouldDeleteUserAndReturn204() 抛出异常 { doNothing().when(userService).deleteUser(1L); mockMvc.perform(删除(“/api/users/1”)) .andExpect(status().isNoContent()); 验证(userService).deleteUser(1L); } @测试 void shouldReturn404WhenDeletingNonExistentUser() 抛出异常 { doThrow(new UserNotFoundException("未找到用户")) .when(userService).deleteUser(999L); mockMvc.perform(删除(“/api/users/999”)) .andExpect(status().isNotFound()); } ## 测试请求参数 ### 查询参数 @测试 void shouldFilterUsersByName() 抛出异常 { List users = List.of(new UserDto(1L, "Alice")); when(userService.searchUsers("Alice")).thenReturn(users); mockMvc.perform(get("/api/users/search?name=Alice")) .andExpect(status().isOk()) .andExpect(jsonPath("$").isArray()) .andExpect(jsonPath("$[0].name").value("Alice")); 验证（userService）.searchUsers（“爱丽丝”）； } ### 路径变量 @测试 void shouldGetUserByIdFromPath() 抛出异常 { UserDto 用户 = new UserDto(123L, "Alice"); 当(userService.getUserById(123L)).thenReturn(用户); mockMvc.perform(get("/api/users/{id}", 123L)) .andExpect(status().isOk()) .andExpect(jsonPath("$.id").value(123)); } ## 测试响应头 ### 验证响应标头 @测试 void shouldReturnCustomHeaders() 抛出异常 { when(userService.getAllUsers()).thenReturn(List.of()); mockMvc.perform(get("/api/users")) .andExpect(status().isOk()) .andExpect(header().exists("X-Total-Count")) .andExpect(header().string("X-Total-Count", "0")) .andExpect(header().string("Content-Type", containsString("application/json"))); } ## 测试请求头 ### 发送请求标头 @测试 void shouldRequireAuthorizationHeader() 抛出异常 { mockMvc.perform(get("/api/users")) .andExpect(status().isUnauthorized()); mockMvc.perform(get("/api/users") .header("授权", "承载 token123")) .andExpect(status().isOk()); } ## 内容协商 ### 测试不同的接受标头 @测试 void shouldReturnJsonWhenAcceptHeaderIsJson() 抛出异常 { UserDto 用户 = new UserDto(1L, "Alice"); 当(userService.getUserById(1L)).thenReturn(用户); mockMvc.perform(get("/api/users/1") .accept(“应用程序/json”)) .andExpect(status().isOk()) .andExpect(content().contentType("application/json")); } ## 高级：测试多个状态代码 @测试 void shouldReturnDifferentStatusCodesForDifferentScenarios() 抛出异常 { // 成功响应 when(userService.getUserById(1L)).thenReturn(new UserDto(1L, "Alice")); mockMvc.perform(get("/api/users/1")) .andExpect(status().isOk()); // 未找到当（userService.getUserById（999L）） .thenThrow(new UserNotFoundException("未找到")); mockMvc.perform(get("/api/users/999")) .andExpect(status().isNotFound()); // 未授权 mockMvc.perform(get("/api/admin/users")) .andExpect(status().isUnauthorized()); } ## 最佳实践 * **在测试单个控制器时使用独立设置**：`MockMvcBuilders.standaloneSetup()` * **模拟服务层** \- 控制器应该专注于 HTTP 处理 * **彻底测试快乐路径和错误路径** * **验证服务方法调用**以确保控制器委托正确 * **使用 content() 匹配器**进行响应正文验证 * **让测试集中**于每个测试的一个端点行为 * **使用 JsonPath** 进行流畅的 JSON 响应断言 ## 常见陷阱 * **在控制器中测试业务逻辑**：转向服务测试 * **不模拟服务层** ：始终模拟服务依赖项 * **测试框架行为** ：专注于您的代码，而不是 Spring 代码 * **硬编码 URL** ：使用 MockMvcRequestBuilders 帮助程序 * **不验证模拟交互**：始终验证服务是否正确调用 ## 限制和警告 * **控制器测试不是集成测试** ：它们验证 HTTP 处理，而不是完整的请求流 * **MockMvc 独立设置限制**：如果没有完整的上下文，某些功能（如 @Validated）可能无法工作 * **JsonPath 需要正确的 JSON 结构** ：确保响应正文对于 JsonPath 断言是有效的 JSON * **不测试框架行为** ：Spring的请求映射是由Spring测试的；仅测试您的代码 * **避免硬编码 URL** ：将 URL 路径提取为常量或使用控制器的 @RequestMapping 值 * **安全注解** : @PreAuthorize 和 @Secured 需要额外设置；考虑单独的安全测试 * **文件上传** : 使用 MockMultipartFile 测试分段文件上传 ## 故障排除 **内容类型不匹配** ：确保 `contentType()` 与控制器的 `@PostMapping(consumes=...)` 匹配或使用默认值。 **JsonPath 不匹配** ：使用 `mockMvc.perform(...).andDo(print())` 查看实际响应内容。 **状态代码断言失败**：检查控制器`@RequestMapping`、`@PostMapping`状态代码和错误处理。 ## 参考文献 * [Spring MockMvc 文档]() * [REST 断言的 JsonPath]() * [Spring 测试最佳实践]()

单元测试控制器层

包含技能