在 Spring Boot 单元测试中，若 Service 依赖 MapStruct 自动生成的 Mapper（如 CategoryRequestMapper），直接 @Mock 会导致其方法调用返回 null，引发 NPE；正确做法是使用 @Spy 包装真实实现类（如 CategoryRequestMapperImpl），兼顾可验证性与实际映射逻辑执行。
在 spring boot 单元测试中，若 service 依赖 mapstruct 自动生成的 mapper（如 `categoryrequestmapper`），直接 `@mock` 会导致其方法调用返回 `null`，引发 npe；正确做法是使用 `@spy` 包装真实实现类（如 `categoryrequestmapperimpl`），兼顾可验证性与实际映射逻辑执行。
MapStruct 是一个编译期生成类型安全映射代码的优秀工具，但在测试中常因依赖注入机制误用而失败。核心问题在于：@Mock 完全替代了 Mapper 实例，所有方法返回 null；而 @Spy 则代理真实对象，在未显式 stub 的情况下仍能执行实际映射逻辑——这正是单元测试中验证业务流程（而非 Mapper 自身）时所必需的。
✅ 正确的单元测试写法（推荐）
使用 @Spy + 手动实例化 Impl 类，配合 @InjectMocks 自动注入：
@ExtendWith(MockitoExtension.class)
class CategoryServiceTest {
@InjectMocks
private CategoryService service; // 自动注入 @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);
// 执行业务逻辑（Mapper 方法将真实执行）
service.create(request);
// 验证 Repository 被调用
verify(categoryRepository).save(any(Category.class));
}
}⚠️ 注意事项：
- CategoryRequestMapperImpl 是 MapStruct 编译后生成的类（通常位于 target/generated-sources/annotations/...），确保测试阶段该类已生成（运行 mvn compile 或启用 IDE 的 annotation processor）；
- 不要使用 @Mock 注解 Mapper 接口——它会切断所有映射逻辑，导致 toEntity() 返回 null；
- 若 Mapper 内部依赖其他 Spring Bean（如 @Context 注入的 Clock 或其他 Mapper），则 @Spy 可能因缺少上下文而失败，此时应升级为轻量级集成测试。
? 替代方案：轻量级集成测试（适用于复杂 Mapper 场景）
当 Mapper 依赖 Spring 管理的组件（例如嵌套 @Mapper(uses = {OtherMapper.class}) 或 @Context 注入）时，建议采用 @SpringBootTest(classes = {...}) 指定最小化上下文，并用 @SpyBean 替代 @Spy：
@SpringBootTest(classes = {
CategoryService.class,
CategoryRequestMapperImpl.class, // 显式注册 Impl（或定义 @Mapper 的接口+配置类）
CategoryRepository.class // 如需真实 JPA 行为，可配内存 DB；否则仍用 @MockBean
})
class CategoryServiceIntegrationTest {
@Autowired
private CategoryService service;
@MockBean
private CategoryRepository categoryRepository;
@SpyBean
private CategoryRequestMapper categoryRequestMapper; // Spring 管理的 SpyBean，支持 AOP 和依赖注入
@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));
}
}? 总结：选择策略指南
| 场景 | 推荐方式 | 关键点 |
|---|---|---|
| 纯单元测试（仅验证 Service 逻辑，Mapper 无外部依赖） | @Spy + new Impl() | 快速、隔离性强，无需 Spring 上下文 |
| Mapper 含 @Context 或 uses 依赖 | @SpringBootTest(classes = {...}) + @SpyBean | 保证依赖注入完整性，支持验证和部分 stub |
| 需测试完整 Mapper 行为本身 | 独立 Mapper 单元测试（不涉及 Service） | 直接实例化 Impl，调用方法断言结果，无需 Spring |
最后提醒：MapStruct 的 @Mapper 接口默认不被 Spring 管理，因此 @Autowired 无法直接注入接口——务必确认你的配置是否启用了 @Mapper(componentModel = "spring")，否则需手动 new Impl() 或通过 @Import 注册。正确区分测试层级，是写出稳定、可维护测试的关键。
