mapstruct需同时引入mapstruct与mapstruct-processor依赖且版本一致，启用注解处理器，@mapper加componentmodel="spring"使其成为spring bean，空值策略分层级配置，自定义逻辑须外置工具类并通过uses声明。
MapStruct 依赖加不对，编译时根本不会生成映射代码
MapStruct 不是运行时反射工具，它的核心是注解处理器（annotation processor）——必须让编译器在编译期识别 @Mapper 并生成实现类。只加 mapstruct 运行时依赖，不配 processor，Mapper 接口会一直报 “unimplemented method” 或直接编译失败。
实操建议：
- Maven 中必须同时声明
mapstruct和mapstruct-processor，且版本严格一致（比如都用1.5.5.Final） - 使用 Lombok 时，
mapstruct-processor必须排在lombok后面，否则字段读取为空 - IDEA 用户：确认 Settings → Build → Compiler → Annotation Processors 已启用，且勾选 “Obtain processors from project classpath”
Mapper 接口没被识别？检查 package 和 @Mapper 的 scope
常见现象：明明写了 @Mapper，但调用方注入时报 BeanCreationException: No qualifying bean of type 'xxxMapper' —— Spring 根本没扫描到它。
原因往往是 MapStruct 默认不参与 Spring 组件扫描，它生成的是普通 Java 类，不是 Spring Bean。
实操建议：
- 最简方案：在
@Mapper上加componentModel = "spring"，这样生成的实现类会带@Component - 如果项目用了模块化（如 JDK 9+），确保
module-info.java中有requires mapstruct;，且 processor 被正确引用 - 接口不能是
private或default方法（除非用@BeanMapping配置）
NullValueMappingStrategy 和 NullValuePropertyMappingStrategy 别混用
这两个策略控制不同层级的空值行为，但名字太像，容易设错导致字段意外丢失或 NPE。
NullValueMappingStrategy 管“整个源对象为 null 时，目标对象怎么处理”；NullValuePropertyMappingStrategy 管“某个字段为 null 时，对应目标字段是否跳过赋值”。
实操建议：
- 全局配置推荐：
@Mapper(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL)+@Mapper(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE) - 局部覆盖用
@Mapping(nullValuePropertyMappingStrategy = ...)更安全，避免影响其他映射逻辑 - 注意：若源字段是基本类型（如
int），null 值根本不存在，该策略不生效
自定义映射方法写在哪？别塞进 Mapper 接口里
想把 Date → String 转成特定格式？或者要调用外部 service？直接在 @Mapper 接口里写方法体，编译会报错：“Mapper interface methods must not have implementation”。
MapStruct 只认抽象方法和 default 方法（用于委托），真正的逻辑必须外置。
实操建议：
- 写一个普通工具类（比如
DateMapperUtils），提供static String formatDate(Date)方法 - 在
@Mapper上用uses = DateMapperUtils.class声明依赖 - 再用
@Mapping(source = "birthDate", target = "birthStr", qualifiedByName = "formatDate")关联 - 不要试图用
@AfterMapping处理复杂业务逻辑——它只是钩子，不是事务边界
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
