MapStruct的@Mapping注解必须写在接口方法声明处而非方法体上，因其仅扫描方法签名元数据；若误标在方法上则映射失效，且编译不报错。
为什么 @Mapping 不能直接写在接口方法上
MapStruct 的 @Mapping 必须标注在接口方法的参数或返回值声明处，而不是方法本身。常见错误是把注解加在方法上，导致编译不报错但映射逻辑完全失效——因为 MapStruct 只扫描方法签名中的注解，不解析方法体（它根本没有方法体）。
正确做法是把 @Mapping 放在接口方法定义里，作为方法的元数据：
@Mapper
public interface UserMapper {
@Mapping(source = "username", target = "loginName")
@Mapping(source = "age", target = "userAge")
UserDTO toDto(User user);
}
-
@Mapping的source必须严格匹配源对象字段名（或 getter 名），区分大小写；若字段是 private 且无 getter，MapStruct 默认无法访问，需配合@BeanMapping(access = Access.READ_WRITE)或改用 public 字段 - 如果 source 字段嵌套多层（如
user.profile.address.city），MapStruct 不支持点号路径写法，必须拆成@Mapping(source = "profile.address.city", target = "city")，前提是 profile 和 address 都是 public 字段或有标准 getter - 目标字段 target 若为 null 安全类型（如
Optional），需额外配置@BeanMapping(nullValueMappingStrategy = NullValueMappingStrategy.RETURN_DEFAULT)
当字段名不一致又不想手动写 @Mapping 怎么办
MapStruct 默认按字段名自动匹配，一旦不一致就静默跳过，不会报错也不会生成赋值代码——这是最隐蔽的坑：编译通过，运行时 DTO 字段为 null，但你根本不知道漏映射了。
启用严格模式可暴露问题：
@Mapper(
unmappedTargetPolicy = ReportingPolicy.ERROR,
unmappedSourcePolicy = ReportingPolicy.ERROR
)
public interface UserMapper { ... }
-
unmappedTargetPolicy = ERROR表示 DTO 里有字段没被任何@Mapping或自动匹配覆盖，编译失败 -
unmappedSourcePolicy = ERROR表示 User 里有字段没被映射出去，同样编译失败（适合强一致性校验） - 若只想警告不中断构建，换成
WARNING；设为IGNORE则退化为 BeanUtils 式“静默丢弃”，失去编译期保障
如何处理 List → List 这类集合转换
MapStruct 对集合类型有内置约定：只要存在单个元素的映射方法（如 UserDTO toDto(User)），就能自动生成集合转换方法，无需额外声明或 @IterableMapping。
但注意几个边界条件：
- 源集合类型和目标集合类型不必完全一致（
List→Set也支持），但必须是接口类型，不能是具体实现类（如ArrayList） - 若需要定制转换逻辑（比如过滤 null 元素、去重），必须显式添加
@IterableMapping(nullValues = NullValueMappingStrategy.RETURN_NULL)等策略 - 泛型擦除会导致编译期无法推导实际类型，所以务必确保 mapper 接口方法签名中泛型完整，例如
List，不能写成toDtoList(List users) List toDtoList(List users)
编译后生成的代码在哪？怎么确认没走反射
MapStruct 在编译期生成真实 Java 类，路径取决于构建工具：Maven 默认在 target/generated-sources/annotations/ 下，Gradle 在 build/generated/sources/annotationProcessor/java/main/。打开对应文件，你会看到纯手工风格的 new + set 赋值代码，没有 Field.set() 或 Method.invoke()。
- 检查生成类中是否含
java.lang.reflect或org.springframework.beans.BeanUtils的 import，有则说明配置冲突（比如同时引入了 Spring Boot 的 auto-configuration） - 若使用 Lombok，必须确保
@Data/@Getter注解在编译期已生效，否则 MapStruct 扫不到 getter 方法；推荐在lombok.config中加lombok.addLombokGeneratedAnnotation = true，方便 IDE 识别生成代码 - IDEA 中若看不到生成代码，需开启 “Enable annotation processing” 并勾选 “Obtain processors from project classpath”
真正麻烦的不是写错注解，而是生成代码被构建流程跳过、或被其他 processor 干扰覆盖——这种问题不会报错，只会让你以为“MapStruct 没生效”，结果 runtime 还在用 BeanUtils。
