如何正确导入mapstruct，同时避免编译时mapstruct与lombok冲突

本文介绍编译时产生的冲突，导包时期产生的冲突请劳驾查找其他解决方法

一般情况下只需要按照官网的导入即可，但如果同时使用了lombok，则需要小心。详细信息可以查看官网文档：MapStruct 1.5.5.Final 集成lombok

注意：在编译测试的时候，一定先清理再编译。这样可以解决80%的报错问题

出现如下问题请清理后再编译

[WARNING] 批注处理不适用于隐式编译的文件。
  使用 -implicit 指定用于隐式编译的策略。

如果配置不正确，则可能在编译的时候出现如下问题：

[ERROR] /E:/my_project_move/12_milkbox2/milkbox2-api/milkbox-service/service-sys/src/main/java/top/milkbox/sys/modular/menu/enums/SysMenuTypeEnum.java:[16,9] 无法将枚举 top.milkbox.sys.modular.menu.enums.SysMenuTypeEnum中的构造器 SysMenuTypeEnum应用到给定类型;
  需要: 没有参数
  找道:    java.lang.String,java.lang.String
  原因: 实际参数列表和形式参数列表长度不同

导入lombok和mapstruct

<!-- lombok -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

<!-- mapstruct 数据类（bean）转换工具 -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>${org.mapstruct.version}</version>
</dependency>

除了导入mapstruct基础的包之外还需要配置这三个path

<!-- mapstruct与lombok同时使用的时候必须要加这个，否则某些使用lombok注解的类会在编译的时候报错 -->
<!-- 注意：lombok一定要放到mapstruct之前，否则在编译的时候某些字段可能无法被mapstruct正确处理 -->
<path>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <version>${lombok.version}</version>
</path>
<!-- mapstruct 处理器 -->
<path>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>${org.mapstruct.version}</version>
</path>
<!-- additional annotation processor required as of Lombok 1.18.16 -->
<!-- 从 Lombok 1.18.16 开始需要额外的注解处理器，这个版本之前的不用加 -->
<path>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.2.0</version>
</path>

完整的配置如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>top.milkbox</groupId>
    <artifactId>milkbox-api</artifactId>
    <version>1.0-DEV</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.1</version>
    </parent>

    <dependencies>
        <!-- spring全家桶导包...... -->
        <!-- 其他技术导包...... -->

        <!-- lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

        <!-- mapstruct 数据类（bean）转换工具 -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${org.mapstruct.version}</version>
        </dependency>

        <!-- 其他工具包结束 -->
    </dependencies>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        
        <!-- 锁定依赖版本号 -->
        <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
    </properties>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>${maven.compiler.source}</source>
                    <target>${maven.compiler.target}</target>
                    <encoding>UTF-8</encoding>
                    <annotationProcessorPaths>
                        <!-- mapstruct与lombok同时使用的时候必须要加这个，否则某些使用lombok注解的类会在编译的时候报错 -->
                        <!-- 注意：lombok一定要放到mapstruct之前，否则在编译的时候某些字段可能无法被mapstruct正确处理 -->
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <!-- mapstruct 处理器 -->
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${org.mapstruct.version}</version>
                        </path>
                        <!-- additional annotation processor required as of Lombok 1.18.16 -->
                        <!-- 从 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>

</project>

以下为官方文档原文中英对照（豆包ai翻译）

14.2. Lombok

MapStruct works together with Project Lombok as of MapStruct 1.2.0.Beta1 and Lombok 1.16.14.
MapStruct 与 MapStruct 1.2.0.Beta1 和 Lombok 1.16.14 的 Lombok 项目一起工作。

MapStruct takes advantage of generated getters, setters, and constructors and uses them to generate the mapper implementations.
MapStruct 利用生成的 getter、setter 和构造函数，并使用它们来生成 mapper 实现。

Lombok 1.18.16 introduces a breaking change (changelog). The additional annotation processor (Maven) must be added otherwise MapStruct stops working with Lombok. This resolves the compilation issues of Lombok and MapStruct modules.lombok-mapstruct-binding
Lombok 1.18.16 引入了一个重大更改（更新日志）。必须添加额外的注释处理器 （Maven），否则 MapStruct 将停止与 Lombok 一起工作。这将解决 Lombok 和 MapStruct 模块的编译问题。lombok-mapstruct-binding

<path>
   <groupId>org.projectlombok</groupId>
   <artifactId>lombok-mapstruct-binding</artifactId>
   <version>0.2.0</version>
</path>

14.2.1. Set up 设置

The set up using Maven or Gradle does not differ from what is described in Set up. Additionally, you need to provide Lombok dependencies.
使用 Maven 或 Gradle 的设置与 设置中描述的设置没有区别。此外，您需要提供 Lombok 依赖项。

Example 116. Maven configuration
例 116.Maven 配置

<properties>
   <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
   <org.projectlombok.version>1.18.16</org.projectlombok.version>
   <maven.compiler.source>1.8</maven.compiler.source>
   <maven.compiler.target>1.8</maven.compiler.target>
</properties>

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

   <!-- Lombok dependency should not end up on classpath -->
   <!-- Lombok 依赖最终不应该出现在类路径上。（意思就是让你加上这个：<scope>provided</scope>） -->
   <dependency>
       <groupId>org.projectlombok</groupId>
       <artifactId>lombok</artifactId>
       <version>${org.projectlombok.version}</version>
       <scope>provided</scope>
   </dependency>
</dependencies>

<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>
                   <!-- （注：这里我不清楚是不是官方文档弄错了，应该把lombok放到mapstruct前面，否则生成的代码可能会缺少许多字段） -->
                   <path>
                       <groupId>org.mapstruct</groupId>
                       <artifactId>mapstruct-processor</artifactId>
                       <version>${org.mapstruct.version}</version>
                   </path>
                   <path>
                       <groupId>org.projectlombok</groupId>
                       <artifactId>lombok</artifactId>
                       <version>${org.projectlombok.version}</version>
                   </path>

                   <!-- additional annotation processor required as of Lombok 1.18.16 -->
                   <!-- 从 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>

Example 117. Gradle configuration (3.4 and later)
例 117.Gradle 配置（3.4 及更高版本）

dependencies {

   implementation "org.mapstruct:mapstruct:${mapstructVersion}"
   compileOnly "org.projectlombok:lombok:1.18.16"
   annotationProcessor "org.projectlombok:lombok-mapstruct-binding:0.2.0"
   annotationProcessor "org.mapstruct:mapstruct-processor:${mapstructVersion}"
   annotationProcessor "org.projectlombok:lombok:1.18.16"
}

The usage combines what you already know from Defining a mapper and Lombok.
该用法结合了您在定义映射器和 Lombok 中已经了解的内容。

Example 118. Usage of MapStruct with Lombok
例 118.MapStruct 在 Lombok 中的使用

@Data
public class Source {

   private String test;
}

public class Target {

   private Long testing;

   public Long getTesting() {
       return testing;
   }

   public void setTesting( Long testing ) {
       this.testing = testing;
   }
}

@Mapper
public interface SourceTargetMapper {

   SourceTargetMapper MAPPER = Mappers.getMapper( SourceTargetMapper.class );

   @Mapping( source = "test", target = "testing" )
   Target toTarget( Source s );
}

A working example can be found on the GitHub project mapstruct-lombok.
可以在 GitHub 项目 mapstruct-lombok 上找到一个工作示例。