踩坑实录：MapStruct 映射失效？揭秘 Lombok 组合下的编译期陷阱

在 Java 后端开发中，MapStruct、Lombok 和 MyBatis-Plus 是提升生产力的常客。但在将它们组合使用时，我们往往会遇到一个极其隐蔽的坑：MapStruct 正常执行了，但生成的实现类方法体却是空的，字段完全没有被赋值。

本文将为你还原案发现场，剖析背后的原理，并提供最优的解决方案。

一、 诡异的案发现场

当你在代码中定义好 DO 到 Entity 的转换接口，满心欢喜地编译项目后，点开 MapStruct 自动生成的 Impl 实现类，可能会看到类似下面这种让人崩溃的代码：

@Override
public CloudTypeConfigEntity toEntity(CloudTypeConfigDO cloudTypeConfigDO) {
    if ( cloudTypeConfigDO == null ) {
        return null;
    }
    
    CloudTypeConfigEntity cloudTypeConfigEntity = new CloudTypeConfigEntity();
    
    // 字段呢？去哪了？本该有一堆 cloudTypeConfigEntity.setConfigId(...) 的逻辑全丢了
    return cloudTypeConfigEntity;  
}

没有报错，没有警告，但业务逻辑直接静默失效。

二、 探究根本原因：注解处理器的博弈

导致这个问题的罪魁祸首是：编译期注解处理器（Annotation Processor）的执行顺序冲突。

Java 编译器在处理注解时，会调用相应的处理器来生成代码或读取元数据：

1. Lombok：负责在抽象语法树（AST）层面动态生成 getter/setter。
2. MapStruct：依赖目标类和源类的 getter/setter 方法来生成属性拷贝代码。

如果 Maven/Gradle 的编译配置中顺序不对，导致 MapStruct 在 Lombok 之前执行，此时实体类中只有 private 字段，根本没有访问器方法。MapStruct 就会认为这些字段无法被读写，最终只能生成一个没有任何映射逻辑的空方法。

三、 破局方案

方案一：调整 annotationProcessorPaths 顺序（ 最佳实践）

这是最根本的解决方式。我们需要在 pom.xml 的 maven-compiler-plugin 中显式接管注解处理器的执行顺序。

正确的 pom.xml 配置姿势如下：

<properties>
    <lombok.version>1.18.30</lombok.version>
    <mapstruct.version>1.6.3</mapstruct.version>
</properties>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <source>21</source>
                <target>21</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.2.0</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

方案二：手动指定字段映射（ 临时退路）

如果出于某些原因（如遗留项目不敢轻易改动全局 POM）导致配置无法生效，可以在 @Mapper 接口中通过 @Mapping 注解进行硬编码指定。

@Mapper(componentModel = "spring")
public interface CloudTypeConfigDBConvertor {
    @Mapping(source = "configId", target = "configId")
    @Mapping(source = "configName", target = "configName")
    @Mapping(source = "configType", target = "configType")
    CloudTypeConfigEntity toEntity(CloudTypeConfigDO cloudTypeConfigDO);
}

注：一旦 MapStruct 无法通过反射或访问器自动推断，显式指定可以强制它生成代码，但这违背了使用 MapStruct 减少样板代码的初衷。

方案三：移除 MyBatis-Plus 相关注解（ 强烈不推荐）

部分开发者在排查时发现，如果把实体类上的 @TableId 等注解删掉，MapStruct 就能映射了。这是因为某些特定版本下，第三方注解的存在可能干扰了内部的解析器机制。

但这种做法得不偿失，会直接导致 MyBatis-Plus 的核心功能（如主键自动生成、BaseMapper 自动推断）失效。

四、 总结

终极建议： 永远保持对构建工具生命周期的敬畏。采用 方案一 显式声明注解处理器的顺序与依赖，可以帮你彻底告别此类“灵异”的编译期映射丢失事件。