MapStruct更新Entity/DTO后未自动再生映射器的解决方案咨询

问题背景 #

我基于Java 17开发Spring Boot REST应用，用MapStruct 1.6.2实现Entity与DTO的双向映射，DTO采用Java Records，Entity通过Lombok 1.18.34生成getter/setter，构建工具为Maven。

MapStruct能正常生成映射器到target/generated-sources目录，但修改Entity或DTO（比如重命名字段）时，生成的映射器不会自动更新。目前只能手动删除target/generated-sources目录，或者启动前执行mvn clean，但后者会拖慢启动速度。怀疑是MapStruct或Maven编译器插件的配置问题，我的pom.xml配置如下：

<properties>
    <java.version>17</java.version>
    <maven-compiler-plugin.version>3.13.0</maven-compiler-plugin.version>
    <mapstruct.version>1.6.2</mapstruct.version>
    <lombok.version>1.18.34</lombok.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>${mapstruct.version}</version>
    </dependency>

    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>${mapstruct.version}</version>
        <scope>provided</scope>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>${lombok.version}</version>
    </dependency>
</dependencies>
<plugins>
    <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <configuration>
            <excludes>
                <exclude>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
                </exclude>
            </excludes>
        </configuration>
    </plugin>

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>${maven-compiler-plugin.version}</version>
        <configuration>
            <source>${java.version}</source>
            <target>${java.version}</target>
            <annotationProcessorPaths>
                <!-- Order is important! Lombok first! -->
                <path>
                    <groupId>org.projectlombok</groupId>
                    <artifactId>lombok</artifactId>
                    <version>${lombok.version}</version>
                </path>
                <path>
                    <groupId>org.mapstruct</groupId>
                    <artifactId>mapstruct-processor</artifactId>
                    <version>${mapstruct.version}</version>
                </path>
            </annotationProcessorPaths>
        </configuration>
    </plugin>
</plugins>

解决方案 #

1. 调整Maven编译器插件配置

Maven默认增量编译可能未正确识别Entity/DTO变更对MapStruct生成类的影响，需补充配置让编译器跟踪注解处理器的依赖关系：

修改maven-compiler-plugin的configuration部分，添加增量编译和MapStruct专属配置：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>${maven-compiler-plugin.version}</version>
    <configuration>
        <source>${java.version}</source>
        <target>${java.version}</target>
        <!-- 开启增量编译，仅编译变更的文件 -->
        <incremental>true</incremental>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </path>
            <!-- 添加Lombok与MapStruct的绑定依赖，解决二者协同感知问题 -->
            <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>
        <!-- 开启MapStruct增量生成，强制依赖变更时重新生成映射器 -->
        <compilerArgs>
            <arg>-Amapstruct.incremental=true</arg>
            <!-- 可选：开启verbose模式用于排查生成问题 -->
            <arg>-Amapstruct.verbose=true</arg>
        </compilerArgs>
    </configuration>
</plugin>

• lombok-mapstruct-binding：解决Lombok生成的getter/setter与MapStruct的感知断层，确保MapStruct能正确识别Entity字段变更
• mapstruct.incremental=true：启用MapStruct增量生成模式，仅当依赖的Entity/DTO变更时重新生成映射器
• incremental=true：开启Maven增量编译，减少不必要的全量编译操作

2. IntelliJ IDEA配置优化

如果使用IDEA开发，需要确保IDE正确处理注解处理器和生成的源文件：

• 打开File > Settings > Build, Execution, Deployment > Compiler，勾选Build project automatically
• 进入File > Settings > Build, Execution, Deployment > Compiler > Annotation Processors，勾选Enable annotation processing，并将Generated sources directory设置为target/generated-sources/annotations
• 右键项目根目录，选择Maven > Generate Sources and Update Folders，让IDE同步生成的文件

3. 验证

修改一个Entity或DTO的字段名称，执行mvn compile（无需加clean），检查target/generated-sources/annotations下的映射器是否已更新；使用IDEA的话，触发自动编译后查看生成的类是否同步变更。

内容的提问来源于stack exchange，提问作者Kirill Kravtsov