MapStruct在编译期生成纯Java赋值代码，如target.setOrderId(source.getId())，无反射调用；常见陷阱包括Lombok与MapStruct注解处理器执行顺序冲突导致映射逻辑丢失。
MapStruct 生成的代码到底长什么样
MapStruct 不是在运行时靠反射调用 getter/setter，而是在编译期（javac 阶段）直接生成一个实现类，比如 OrderMapperImpl，里面全是手动写的、直白的赋值语句。你可以打开 target/generated-sources/annotations/（Maven 项目）或 build/generated/sources/annotationProcessor/java/main/（Gradle）看到它——没有 Method.invoke()，没有 Field.get()，只有 target.setOrderId(source.getId()) 这种纯 Java 代码。
这意味着：JVM 完全不需要动态解析字段或方法，GC 压力更小，热点代码也更容易被 JIT 优化。实测在高并发 DTO 转换场景下，相比 BeanUtils.copyProperties()，吞吐量可提升 3–5 倍，GC 暂停时间下降明显。
@Mapping 注解里哪些参数最常误用
很多人只写 @Mapping(target = "name", source = "fullName")，却忽略几个关键控制点：
-
qualifiedByName和qualifiedBy必须配对使用，否则编译失败；常见错误是只加了qualifiedByName = "toLocalDateTime"，但没在对应方法上加@Named("toLocalDateTime") -
expression中的 Java 表达式必须用java(...)包裹，例如@Mapping(target = "status", expression = "java(source.getStatus() == 1 ? 'ACTIVE' : 'INACTIVE')")，漏掉java()会报Unknown property -
defaultExpression仅在 source 字段为null时生效；若想覆盖所有空值（包括空字符串、空集合），得用defaultValue+ 自定义@Condition方法
嵌套对象映射为什么经常漏掉 @Mapper#uses
当 Entity 有 User user 字段，DTO 有 UserDto userDto，且你已写了 UserMapper 接口，那么主 OrderMapper 必须显式声明依赖：
@Mapper(uses = {UserMapper.class})
public interface OrderMapper {
OrderDto toDto(Order entity);
}
不加 uses，MapStruct 默认尝试“内联”映射，结果要么编译报错（找不到合适转换方法），要么静默生成错误逻辑（比如把 User 对象 toString 后塞进字符串字段）。尤其在模块化项目中，跨 module 的 mapper 更容易因 classpath 扫描遗漏而失败。
Spring 环境下 @Mapper(componentModel = "spring") 的陷阱
设成 "spring" 会让 MapStruct 生成带 @Component 的实现类，但要注意：
- 该类不会自动参与 Spring 的泛型类型推导——比如
@Autowired private Mapper会失败，必须用具体接口类型注入mapper; - 如果项目启用了
spring-boot-starter-validation，且 DTO 有@NotNull等注解，MapStruct 生成的代码默认不做校验；需额外配置@Bean或启用mapstruct-suppress-generator-warnings避免误报 - IDE（如 IntelliJ）有时无法识别自动生成的 Impl 类，导致跳转失败或红标；建议开启
Settings → Build → Annotation Processors → Enable annotation processing
编译期生成看着透明，但一旦路径、依赖或注解组合出错，错误信息往往藏在 annotation processor 日志深处，而不是常规编译错误里——查不到生成代码时，先翻 mvn compile -X 输出里的 mapstruct 相关行。
