别再只会用@Mock了！SpringBoot单元测试中@MockBean与@SpyBean的实战避坑指南

甘剑平

259人浏览 · 2026-03-20 01:07:58

甘剑平 · 2026-03-20 01:07:58 发布

别再只会用@Mock了！SpringBoot单元测试中@MockBean与@SpyBean的实战避坑指南

在SpringBoot项目的单元测试中，Mockito几乎是每个Java开发者必备的工具。但很多人在从纯Mockito测试转向Spring集成测试时，常常陷入@Mock的舒适区，忽略了SpringBoot专门提供的@MockBean和@SpyBean这两个更强大的武器。本文将带你深入理解这两个注解的核心差异、适用场景和常见陷阱，让你的SpringBoot测试代码更加健壮可靠。

1. 为什么需要@MockBean和@SpyBean？

在传统的单元测试中，我们习惯使用@Mock来创建模拟对象。但当测试涉及到Spring容器时，简单的@Mock就显得力不从心了。考虑以下典型场景：

@Service
public class OrderService {
    @Autowired
    private PaymentService paymentService;
    
    public boolean processOrder(Order order) {
        return paymentService.processPayment(order);
    }
}

如果只用@Mock测试这个服务：

@ExtendWith(MockitoExtension.class)
class OrderServiceTest {
    @Mock
    private PaymentService paymentService;
    
    @InjectMocks
    private OrderService orderService;
    
    @Test
    void testProcessOrder() {
        // 测试代码...
    }
}

这种测试存在几个严重问题：

完全脱离了Spring上下文，无法测试真实的依赖注入行为
无法验证Spring特有的功能如事务、AOP等
当有多个@Service相互依赖时，手动管理依赖关系将变得极其复杂

这就是@MockBean和@SpyBean的价值所在——它们能在保持Spring上下文完整性的同时，灵活地替换容器中的Bean。

2. @MockBean vs @SpyBean：核心区别解析

2.1 行为差异对比

特性	@MockBean	@SpyBean
对象类型	完全模拟的Mock对象	真实对象的包装(Spy)
方法调用默认行为	所有方法都需要stub，否则返回默认值	调用真实方法，除非被stub
Spring上下文影响	完全替换原有Bean	包装原有Bean
适用场景	需要完全控制依赖行为	需要部分保留真实逻辑
性能影响	轻量级	需要初始化真实对象，稍重

2.2 典型使用场景

@MockBean适用情况：

测试不依赖具体实现的接口
需要完全控制依赖对象的行为
测试外部服务(如数据库、第三方API)的异常处理

@SpringBootTest
class OrderServiceTest {
    @MockBean
    private PaymentService paymentService;
    
    @Autowired
    private OrderService orderService;
    
    @Test
    void whenPaymentFails_thenOrderFails() {
        when(paymentService.processPayment(any()))
            .thenThrow(new PaymentException("Insufficient balance"));
        
        assertThrows(PaymentException.class, 
            () -> orderService.processOrder(new Order()));
    }
}

@SpyBean适用情况：

需要保留部分真实逻辑(如数据转换)
只修改对象的少数方法行为
测试具有复杂初始化的Bean

@SpringBootTest
class UserServiceTest {
    @SpyBean
    private UserRepository userRepository;
    
    @Autowired
    private UserService userService;
    
    @Test
    void whenFindById_thenApplySpecialLogic() {
        // 保留真实的save方法
        doReturn(new User("admin")).when(userRepository)
            .findById("special-id");
            
        User user = userService.getUser("special-id");
        assertEquals("ADMIN", user.getUsername()); // 假设服务层会转为大写
    }
}

3. 实战中的五大陷阱与解决方案

3.1 陷阱一：循环依赖导致上下文加载失败

问题现象：

@Service
class ServiceA {
    @Autowired ServiceB serviceB;
}

@Service 
class ServiceB {
    @Autowired ServiceA serviceA;
}

@SpringBootTest
class TestClass {
    @MockBean ServiceA serviceA; // 导致启动失败
}

解决方案：

使用@Lazy注解打破循环
或者在测试中mock两个服务：

@SpringBootTest
class TestClass {
    @MockBean ServiceA serviceA;
    @MockBean ServiceB serviceB;
}

3.2 陷阱二：事务回滚与@MockBean的冲突

问题代码：

@SpringBootTest
@Transactional
class TransactionTest {
    @MockBean
    private AuditService auditService;
    
    @Test
    void testWithTransaction() {
        // 测试代码...
    }
}

问题分析： @Transactional会导致测试后回滚，但@MockBean的修改是直接作用于Spring上下文的，不会被回滚。这可能导致后续测试出现意外行为。

解决方案：

在@Test方法中手动reset mock：

@AfterEach
void tearDown() {
    Mockito.reset(auditService);
}

或者使用DirtiesContext强制重置上下文：

@SpringBootTest
@Transactional
@DirtiesContext(classMode = AFTER_EACH_TEST_METHOD)
class TransactionTest {
    // ...
}

3.3 陷阱三：@SpyBean与final方法的冲突

问题代码：

@Service
public class DataProcessor {
    public final String process(String input) {
        return input.toUpperCase();
    }
}

@SpringBootTest
class DataProcessorTest {
    @SpyBean
    private DataProcessor dataProcessor; // 报错！
}

原因分析： Mockito无法spy final方法，这是Mockito的基本限制。

解决方案：

重构代码移除final修饰符
或者对特定方法使用@MockBean代替：

@SpringBootTest
class DataProcessorTest {
    @MockBean
    private DataProcessor dataProcessor;
    
    @Test
    void testProcess() {
        when(dataProcessor.process("test")).thenReturn("TEST");
        // ...
    }
}

3.4 陷阱四：多个测试类间的@MockBean污染

问题现象： TestA中定义了@MockBean XService，TestB运行时意外使用了TestA中mock的XService。

解决方案：

为每个测试类添加@DirtiesContext
或者在@TestConfiguration中集中定义mock：

@TestConfiguration
class MockConfig {
    @Bean
    @Primary
    public XService xService() {
        return Mockito.mock(XService.class);
    }
}

@SpringBootTest(classes = {App.class, MockConfig.class})
class TestA {
    @Autowired
    private XService xService;
}

3.5 陷阱五：@SpyBean与复杂初始化的冲突

问题代码：

@Service
class HeavyService {
    private final ExpensiveResource resource;
    
    @PostConstruct
    void init() {
        resource.load(); // 耗时操作
    }
}

@SpringBootTest
class TestClass {
    @SpyBean // 每次测试都会执行真实初始化！
    private HeavyService heavyService;
}

优化方案：

使用@MockBean并手动模拟部分方法
或者提取轻量级测试专用配置：

@Profile("test")
@Configuration
class TestConfig {
    @Bean
    @Primary
    public HeavyService lightHeavyService() {
        HeavyService service = Mockito.spy(new HeavyService());
        doNothing().when(service).init();
        return service;
    }
}

4. 高级技巧：组合使用与性能优化

4.1 混合使用@MockBean和@SpyBean

在测试复杂服务时，可以针对不同依赖选择最合适的mock策略：

@SpringBootTest
class ComplexServiceTest {
    @MockBean // 完全mock外部服务
    private ExternalApiClient apiClient;
    
    @SpyBean // 部分保留数据库操作
    private UserRepository userRepository;
    
    @Autowired
    private ComplexService complexService;
    
    @Test
    void testComplexScenario() {
        // 设置apiClient返回特定值
        when(apiClient.getData()).thenReturn(new ApiResponse());
        
        // 覆盖repository的某个方法
        doReturn(Optional.empty()).when(userRepository)
            .findByEmail(anyString());
            
        // 执行测试并验证
        complexService.process();
        verify(userRepository, times(1)).save(any());
    }
}

4.2 使用@MockBean进行切片测试

SpringBoot的@WebMvcTest等切片测试会自动配置相关mock：

@WebMvcTest(UserController.class)
class UserControllerTest {
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean // 自动替换真实Service
    private UserService userService;
    
    @Test
    void getUserTest() throws Exception {
        when(userService.getUser(1L))
            .thenReturn(new User(1L, "test"));
            
        mockMvc.perform(get("/users/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("test"));
    }
}

4.3 性能优化建议

合理使用@DirtiesContext：避免不必要的上下文重置
Mock层次化：在@TestConfiguration中定义公共mock
懒加载Spy：对于初始化成本高的Bean：

@SpyBean(lazyInit = true)
private HeavyService heavyService;

复用上下文：相同配置的测试类会复用Spring上下文

@SpringBootTest
@ContextConfiguration(classes = TestConfig.class)
abstract class BaseTest {
    // 公共测试配置
}

class ServiceATest extends BaseTest {
    // 复用上下文
}

掌握这些技巧后，你会发现SpringBoot的测试不再是一件痛苦的事情。记住：@MockBean是你的"核武器"，适合完全控制依赖；@SpyBean则是"精准手术刀"，适合需要保留部分真实逻辑的场景。根据实际需求灵活选择，才能写出既可靠又高效的测试代码。