mapstruct与lombok冲突原因及解决方案

问题背景说明

MapStruct 和 Lombok 都是 Java 开发中常用的代码生成工具，但两者在编译时的注解处理器（Annotation Processor）机制上存在冲突。MapStruct 依赖生成的代码进行对象映射，而 Lombok 用于自动生成 getter/setter 等方法。若未正确配置，可能导致编译失败或生成的代码不完整。

---

冲突原因分析

1. 注解处理器执行顺序问题：Lombok 和 MapStruct 的注解处理器在编译时可能因顺序问题相互干扰。
2. 代码生成时机冲突：Lombok 生成的代码可能未被 MapStruct 及时识别，导致映射失败。
3. IDE 兼容性问题：部分 IDE（如 IntelliJ IDEA）对注解处理器的支持需要额外配置。 如果你用的IntelliJ IDEA版本是2023及以上的版本，Lombok对应的版本也会与老版的IDE有所不同，因此高版本的Lombok对应的MapStruct需要额外的一些配置。

---

解决方案

配置编译插件顺序

在 Maven 或 Gradle 中明确指定注解处理器的执行顺序，确保 Lombok 先于 MapStruct 执行。

MapStruct官网中写了 Lombok 1.18.16 引入了一个重大更改（更新日志）。 必须添加额外的注释处理器 （Maven），否则 MapStruct 将停止与 Lombok 一起工作。
https://mapstruct.org/documentation/stable/reference/html/#lombok

官网也给出了解决方式

对应 Maven 示例：

<!-- 我用的IntelliJ IDEA版本是2023.3.4 -->
<org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
<lombok.version>1.18.22</lombok.version>
<build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${org.mapstruct.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>

                        <!-- additional annotation processor required as of Lombok 1.18.16 -->
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok-mapstruct-binding</artifactId>
                            <version>0.2.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>

Gradle 示例：

dependencies {  
    compileOnly 'org.projectlombok:lombok'  
    annotationProcessor 'org.projectlombok:lombok'  
    annotationProcessor 'org.mapstruct:mapstruct-processor'  
}  

IDE 特定配置

IntelliJ IDEA 用户：

1. 启用注解处理器：
   • 路径：Settings > Build > Compiler > Annotation Processors，勾选 Enable annotation processing。
2. 确保 Lombok 插件已安装并启用。

Eclipse 用户：

1. 安装 Lombok 插件并重启 IDE。
2. 检查项目属性中 Java Compiler > Annotation Processing 是否启用。

---

验证解决方案

1. 编写一个简单的 DTO 和实体类，使用 Lombok 的 @Data 和 MapStruct 的 @Mapper。
2. 编译项目，确认无错误且生成的映射代码完整。
3. 运行单元测试验证对象转换逻辑。

---

常见问题排查

1. 编译失败：检查依赖版本是否兼容，如 MapStruct 1.5+ 和 Lombok 1.18.16+。
2. 代码未生成 ：清理项目并重新构建（mvn clean compile 或 gradle clean build）。
3. IDE 报错：尝试重启 IDE 或重新导入项目。