在 Spring 单元测试中，MapStruct 生成的 Mapper 实例常因未被正确初始化而报 NullPointerException；本文详解如何通过 @Spy（单元测试）或 @SpyBean（集成测试）精准注入并控制 Mapper 行为，兼顾可测性与真实性。
在 spring 单元测试中，mapstruct 生成的 mapper 实例常因未被正确初始化而报 nullpointerexception；本文详解如何通过 `@spy`（单元测试）或 `@spybean`（集成测试）精准注入并控制 mapper 行为，兼顾可测性与真实性。
MapStruct 是一款高性能、编译期生成映射代码的 Java Bean 映射框架。它不依赖运行时反射，因此在 Spring 测试中无法像普通 @Service 或 @Component 那样被自动扫描和注入——尤其在纯单元测试（@ExtendWith(MockitoExtension.class)）场景下，@Mock 或 @InjectMocks 无法自动创建其实例，导致服务类中注入的 Mapper 字段为 null，进而引发 NullPointerException。
✅ 正确方案一：纯单元测试 — 使用 @Spy 包装真实实现类
当你的测试目标是验证业务逻辑本身（如 CategoryService.create() 的流程控制、条件分支、Repository 交互），且 Mapper 无外部依赖（如不引用其他 Spring Bean 或复杂配置），推荐使用 @Spy + 手动实例化实现类：
@ExtendWith(MockitoExtension.class)
class CategoryServiceTest {
@InjectMocks
private CategoryService service; // Mockito 自动将 @Spy 和 @Mock 注入此处
@Mock
private CategoryRepository categoryRepository;
@Spy
private CategoryRequestMapper categoryRequestMapper = new CategoryRequestMapperImpl(); // ✅ 关键：显式构造 Impl 类
@ParameterizedTest
@CsvFileSource(resources = "/data/categories.csv")
void test_create(Long id, String name, Integer ordinal) {
CategoryRequest request = new CategoryRequest(id, name, ordinal);
when(categoryRepository.existsByNameIgnoreCase(request.getName())).thenReturn(false);
service.create(request);
// 验证 Mapper 是否被调用（可选）
verify(categoryRequestMapper).toEntity(request);
// 验证 Repository 调用
verify(categoryRepository).save(any(Category.class));
}
}⚠️ 注意事项：
- CategoryRequestMapperImpl 是 MapStruct 编译后生成的类（默认命名规则），确保其已由 mapstruct-processor 成功生成（检查 target/generated-sources/annotations/... 目录）；
- 不要使用 @Mock 替代 @Spy：@Mock 会完全拦截所有方法调用并返回 null（除非显式 when(...).thenReturn(...)），而 @Spy 默认委托给真实对象，仅对 stubbed 方法生效；
- 若 Mapper 接口含 @Mapper(componentModel = "spring")，则其实现类会被 Spring 管理，此时不应手动 new，而应改用方案二。
✅ 正确方案二：轻量级集成测试 — 使用 @SpyBean 启动最小上下文
当 Mapper 依赖其他 Spring Bean（例如嵌套映射调用了另一个 @Mapper，或使用了 @Context 参数注入 Clock、PasswordEncoder 等），需让 Spring 容器参与初始化。此时应使用 @SpringBootTest 并精简加载的 Bean：
@SpringBootTest(classes = {
CategoryService.class,
CategoryRequestMapper.class, // 声明接口，Spring 将自动注册其实现
CategoryRequestMapperImpl.class, // 显式注册 Impl（若未启用 componentModel="spring"）
CategoryRepository.class // 可替换为 @MockBean（见下文）
})
class CategoryServiceIntegrationTest {
@Autowired
private CategoryService service;
@MockBean // ✅ 替换真实 Repository，避免 DB 依赖
private CategoryRepository categoryRepository;
@SpyBean // ✅ 让 Spring 创建真实 Mapper 实例，并允许 Mockito 拦截/验证
private CategoryRequestMapper categoryRequestMapper;
@Test
void test_create_with_spybean() {
CategoryRequest request = new CategoryRequest(1L, "Tech", 1);
when(categoryRepository.existsByNameIgnoreCase("Tech")).thenReturn(false);
service.create(request);
verify(categoryRequestMapper).toEntity(request); // 可验证调用
verify(categoryRepository).save(any(Category.class));
}
}✅ 关键优势：
- @SpyBean 保证 Mapper 是 Spring 上下文中的真实单例，支持 @Autowired 注入的嵌套依赖；
- @MockBean 可安全替换 CategoryRepository 等外部组件，实现“隔离但真实”的集成测试；
- 无需 @InjectMocks，Spring 全权管理依赖注入，更贴近生产行为。
❌ 常见错误与规避建议
| 错误做法 | 问题说明 | 正确替代 |
|---|---|---|
| @Mock private CategoryRequestMapper mapper | Mock 对象不执行实际映射逻辑，toEntity() 返回 null，导致 NPE | 改用 @Spy + new Impl() 或 @SpyBean |
| @SpringBootTest 无 classes 属性 | 加载全量上下文，启动慢、易受无关 Bean 干扰（如数据库连接失败） | 显式指定 classes = {...}，构建最小必要上下文 |
| 在 @InjectMocks 类中 @Autowired Mapper | @InjectMocks 与 Spring 容器冲突，字段仍为 null | 单元测试禁用 @Autowired；集成测试统一用 @Autowired + @SpyBean |
总结
- 单元测试（快、隔离） → 用 @Spy + new CategoryRequestMapperImpl()，配合 @InjectMocks；
- 集成测试（真、可靠） → 用 @SpringBootTest(classes = {...}) + @SpyBean + @MockBean；
- 始终确保 mapstruct-processor 已配置于 pom.xml（Maven）或 build.gradle（Gradle），并启用注解处理器；
- 若 Mapper 接口标注 @Mapper(componentModel = "spring")，优先采用 @SpyBean 方案，避免手动 new 破坏 Spring 生命周期管理。
通过合理选择注入策略，你既能享受 MapStruct 的零开销性能，又能写出稳定、可维护、覆盖充分的测试代码。
