如何为 MapStruct…

在需要验证实体与 DTO 之间映射/转换逻辑正确性时，用可执行的单元测试覆盖字段映射、空值、双向、嵌套、枚举和自定义表达式。

适用场景

解决思路

1. 测试前先确认生成的映射器类存在：Maven 执行 `ls target/generated-sources/`，Gradle 执行 `ls build/generated/sources/`；若缺失，运行 `mvn compile` 或 `./gradlew compileJava`，检查 MapStruct 注解处理器是否配置，并确认 `@Mapper` 接口位于已编译的源集中。
2. 测试空值处理：断言 `assertThat(mapper.toDto(null)).isNull();`；若空值应返回空对象/默认值，则在映射器中配置 `nullValueMappingStrategy`；若空值测试失败，在 `@Mapper` 上加 `nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL`，或用 `nullValuePropertyMappingStrategy` 处理嵌套属性。
3. 测试双向映射：用 `User restored = mapper.toEntity(mapper.toDto(original)); assertThat(restored).usingRecursiveComparison().isEqualTo(original);`；若失败，检查 `@Mapping` 注解的字段名是否匹配，自动映射失败时显式映射两个方向，并用 `unmappedTargetPolicy = ReportingPolicy.ERROR` 捕获遗漏映射。
4. 测试嵌套对象映射：用 `assertThat(dto.getNested()).usingRecursiveComparison().isEqualTo(expected);`；若失败，确保嵌套映射器存在或通过 `uses = NestedMapper.class` 引用，并检查集合元素映射的 `elementMappingStrategy`。
5. 测试自定义表达式：`@Mapping(target = "field", expression = "java(...)")` 中的表达式不会在编译期校验；若失败，核对表达式语法与方法签名，并确认表达式上下文中可访问所导入的类。
6. 测试枚举映射：用 `@ValueMapping` 做枚举到枚举的转换，并穷举测试所有枚举值。
7. 使用 `Mappers.getMapper()` 编写独立测试，集成测试时用 Spring 注入。
8. 对复杂嵌套结构使用 `usingRecursiveComparison()` 进行比较。
9. 测试映射器的所有方法，包括集合转换。
10. 对所有可为空的源字段验证空值处理。
11. 用双向映射测试捕获 entity→DTO 与 DTO→entity 之间的不对称。
12. 让映射器测试聚焦于转换正确性，而非实现细节。
13. 注意 MapStruct 在编译期生成代码，运行测试前必须确认生成类存在。
14. 注意 MapStruct 无法处理映射器之间的循环依赖。
15. 映射不可变集合可能需要特殊配置。
16. 验证日期/时间对象在不同时区下是否正确映射。

适用边界 · 注意事项

• 尚未配置 MapStruct 注解处理器或未编译生成映射器类时，无法运行映射测试。
• 映射器之间存在循环依赖时，MapStruct 无法处理，不适用此做法。
• 仅需验证业务逻辑而非数据转换正确性时，不必使用本测试模式。