本文详解 Spring Boot 集成测试中因错误使用 @MockBean 导致服务层方法未实际执行的问题，提供控制器测试与服务层测试两种场景的正确配置方式，并附可运行代码示例。
本文详解 spring boot 集成测试中因错误使用 `@mockbean` 导致服务层方法未实际执行的问题，提供控制器测试与服务层测试两种场景的正确配置方式，并附可运行代码示例。
在 Spring Boot 的分层测试实践中，一个高频陷阱是：本意想验证控制器 + 服务 + 数据访问的完整链路，却无意中用 @MockBean 替换了真实服务实例，导致 categoryService.findById() 根本未执行，返回值为 null 或默认 stub 响应。这并非代码缺陷，而是测试设计逻辑偏差。
? 问题根源分析
观察原始测试类：
@SpringBootTest(classes = {CategoryController.class, CategoryService.class, CategoryResponseMapperImpl.class})
class CategoryControllerTest {
// ...
@MockBean
private CategoryService categoryService; // ❌ 关键错误：此处 mock 掉了真实服务
}由于 @MockBean 会完全替代 Spring 容器中同类型的 Bean，即使你通过 @SpringBootTest 加载了 CategoryService.class，它也会被这个空的 mock 实例覆盖。因此控制器调用 categoryService.findById(id) 时，实际执行的是 Mockito 生成的哑实现（默认返回 null），而非你期望的、含 categoryRepository.findById().map(...) 逻辑的真实方法。
✅ 正确解法一：测试控制器（Controller Layer Test）
目标：验证控制器能否正确接收请求、调用服务、序列化响应，不关心服务内部逻辑。此时应：
- 保留 @MockBean CategoryService；
- 显式 stub 服务方法返回值，模拟其行为。
@SpringBootTest
@AutoConfigureTestDatabase // 如需数据库支持（可选）
class CategoryControllerTest {
@Autowired
private MockMvc mockMvc;
@MockBean
private CategoryService categoryService; // ✅ 保持 mock
@MockBean
private CategoryRepository categoryRepository; // 若 service 内部还依赖 repo，也需 mock（但本例中 service 已被 mock，此行可省略）
@Test
void test_findById_controller() throws Exception {
// 准备模拟的响应 DTO
CategoryResponse mockResponse = new CategoryResponse();
mockResponse.setId(123L);
mockResponse.setName("Category");
mockResponse.setOrdinal(1);
// Stub service 方法 —— 这是关键！
when(categoryService.findById(123L)).thenReturn(mockResponse);
mockMvc.perform(get("/api/v1/categories/{id}", 123L))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_JSON))
.andExpect(jsonPath("$.data.id").value(123))
.andExpect(jsonPath("$.data.name").value("Category"));
}
}⚠️ 注意：@SpyBean 或 @Spy 不适用于此场景。@Spy 创建的是对真实对象的“部分模拟”，但若该对象本身已被 @MockBean 覆盖，则 @Spy 将无意义或引发 Bean 冲突。
✅ 正确解法二：测试服务层（Service Layer Test）
目标：验证 CategoryService.findById() 是否能正确调用仓库、转换 DTO 并处理异常。此时应：
- 使用 @Autowired 注入真实服务实例；
- 仅 @MockBean 其直接依赖（如 CategoryRepository）；
- 确保 MapStruct Mapper 实现类（如 CategoryResponseMapperImpl）被正确加载（通常通过组件扫描或 @Import）。
@SpringBootTest(classes = {CategoryService.class, CategoryResponseMapperImpl.class})
@Import(TestConfig.class) // 如需自定义 Clock 等 bean，可在此注入
class CategoryServiceTest {
@Autowired
private CategoryService categoryService;
@MockBean
private CategoryRepository categoryRepository;
@MockBean
private Clock clock; // 若服务中依赖 Clock，需 mock
@Test
void test_findById_service() {
// 给定：仓库返回 Category 实体
Category entity = new Category();
entity.setId(123L);
entity.setName("Category");
entity.setOrdinal(1);
when(clock.instant()).thenReturn(Instant.parse("2022-01-01T00:00:00Z"));
when(categoryRepository.findById(123L)).thenReturn(Optional.of(entity));
// 当：调用服务方法
CategoryResponse result = categoryService.findById(123L);
// 那么：验证 DTO 字段映射正确
assertThat(result.getId()).isEqualTo(123L);
assertThat(result.getName()).isEqualTo("Category");
assertThat(result.getOrdinal()).isEqualTo(1);
}
}? 关键注意事项总结
@MockBean vs @Autowired 的语义必须清晰：
@MockBean = “我不要这个 Bean 的真实行为，我要自己控制它的返回”；
@Autowired = “我要这个 Bean 的真实逻辑，只 mock 它的下游依赖”。避免混合使用 @MockBean 和 @SpyBean 同一类型：会导致不可预测的 Bean 注入结果，Spring 无法确定应使用哪一个。
MapStruct 实现类注册：确保 CategoryResponseMapperImpl 类被 Spring 扫描到（如位于主启动类同包或子包），或显式通过 @Import(CategoryResponseMapperImpl.class) 引入。若使用 @Mapper(componentModel = "spring")，则无需额外配置。
测试范围隔离：控制器测试关注 HTTP 协议层（状态码、头、JSON 结构）；服务测试关注业务逻辑与数据转换。二者不可互相替代。
遵循以上原则，即可精准定位并修复“服务方法未被调用”的测试失效问题，构建健壮、可维护的 Spring Boot 分层测试体系。
