MapStruct 编译不生成实现类的根本原因是未配置 annotation processor；Maven 需同时引入 mapstruct 和 mapstruct-processor（scope=provided），IDEA 要启用 Annotation Processors，Gradle 需添加 annotationProcessor 依赖。
MapStruct 依赖没生效，编译时 Mapper 接口还是空实现？
根本原因不是写错了注解，而是 MapStruct 的代码生成依赖 annotation processor，JDK 本身不处理它。Maven 项目里只加 mapstruct 依赖，不配 processor，编译器根本不会生成实现类。
实操建议：
- 用 Maven 的话，必须同时声明
mapstruct和mapstruct-processor两个依赖；后者要加<scope>provided</scope>，否则运行时会冲突 - IDEA 用户注意：勾选
Settings > Build > Compiler > Annotation Processors > Enable annotation processing，否则改了@Mapper也看不到生成的类 - Gradle 用户别只写
implementation 'org.mapstruct:mapstruct'，得补上annotationProcessor 'org.mapstruct:mapstruct-processor'
为什么 @Mapper 接口编译后没生成实现类？
MapStruct 不是运行时代理，也不靠反射——它在编译期生成真实 Java 类。如果没看到 MyMapperImpl 这样的类，说明 annotation processor 没跑起来，或者配置路径/包扫描出问题。
常见错误现象：
立即学习“Java免费学习笔记（深入）”；
- 运行时报
NoClassDefFoundError: MyMapperImpl或NullPointerException（因为注入的是 null） - IDE 中接口方法调用处没跳转、没补全，提示 “cannot resolve method”
- 手动在
target/generated-sources/annotations下找不到生成的 .java 文件
检查点：
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 确认
@Mapper接口是否用了public修饰（非 public 接口不会被 processor 处理） - 确认接口里至少有一个
@Mapping或直接有方法签名能匹配字段名（全空接口可能被跳过） - clean 后重新 build，别信 IDE 的 incremental compile
Spring 中怎么让 @Mapper 被自动注入？
MapStruct 默认生成的类不是 Spring Bean，不能直接 @Autowired。想无缝集成 Spring，得告诉 MapStruct：“请按 Spring 管理的方式生成实现类”。
做法很简单：
- 在
@Mapper上加componentModel = "spring"，例如：@Mapper(componentModel = "spring") - 生成的实现类会带
@Component注解，Spring 扫描到就能注入 - 注意：如果项目用了 Lombok，
@Data或@Builder别加在 Mapper 接口上——接口不能用这些 - 不用额外写
@Configuration或 XML 配置，Spring Boot 2.6+ 默认支持 component scanning
@Mapping 的 source 和 target 填错字段名就静默失败？
MapStruct 不会在编译时报“字段不存在”，它只会跳过这个映射，或者尝试用默认策略（比如同名字段自动拷贝）。结果就是：你写了映射，但值没过去，还查不出错。
容易踩的坑：
-
source = "userDTO.name"写成source = "name"，而目标对象字段叫userName—— 这种链式取值必须显式写全，且源对象要有对应 getter - 大小写敏感：
userId≠userid，哪怕 getter 是getUserID()，字段名仍按 JavaBean 规范解析为userID - 嵌套对象映射要用
@BeanMapping+qualifiedByName控制策略，别指望单个@Mapping搞定多层转换
建议打开编译警告：在 Maven 的 maven-compiler-plugin 里加 <compilerargs><arg>-Xlint:all</arg></compilerargs>，MapStruct 会输出未映射字段的 warning。
最麻烦的其实是嵌套集合映射和日期格式转换——那些没法靠字段名自动对齐，得手写 @Named 方法或用 expression，而且一写错就是运行时 NullPointerException，编译期完全不报。
