添加MapStruct Annotation Processor后Maven编译失败问题排查

问题场景 #

使用MapStruct时，按照要求在Maven Compiler Plugin中配置annotationProcessorPaths引入MapStruct注解处理器后，原本可正常编译的代码出现cannot find symbol、类型参数无法推断等错误。

简化测试用例如下：
自定义泛型类：

@Getter
@Setter
public class Result<D, E> {
    private D data;
    private E error;
}

对应的泛型方法：

public static <D, E> Result<D, E> createResult(D data, Class<E> type) {
    Result<D, E> res = new Result<>();
    res.setData(data); // 此处编译报错：cannot find symbol
    return res;
}

调用代码：

Result<String, String> test = createResult("Test", String.class);

未配置annotationProcessorPaths时编译正常；但配置后报错。而类似的泛型List方法却能正常编译：

public static <T> List<T> createListWithItem(T item) {
    List<T> res = new ArrayList<>();
    res.add(item);
    return res;
}

调用：

List<String> list = createListWithItem("BANANA");

疑问解答 #

1. 为何仅添加注解处理器就导致编译失败？ #

这是因为显式配置annotationProcessorPaths后，Maven Compiler Plugin会停止自动扫描项目依赖中的注解处理器。你的代码里用了Lombok的@Getter/@Setter注解，需要Lombok的注解处理器生成对应的get/set方法，但你只在annotationProcessorPaths里加了MapStruct，没加Lombok，导致编译阶段Lombok没生成setData方法，编译器找不到这个符号，自然报错。

2. 该问题与MapStruct相关还是Maven Compiler Plugin的问题？ #

本质是Maven Compiler Plugin的行为特性，和MapStruct本身无关。当你手动指定annotationProcessorPaths时，插件会忽略依赖中自带的注解处理器，必须把所有需要的处理器（比如Lombok、MapStruct）都手动加入配置。只加MapStruct的话，Lombok处理器失效，代码就编译失败了。

3. Result示例与List示例的差异是什么？ #

• Result类：是你自定义的泛型类，依赖Lombok注解处理器生成setData等方法。当Lombok处理器失效时，这些方法不存在，编译报错。
• List/ArrayList：是JDK原生自带的类，它们的add等方法是类本身就有的，不需要任何注解处理器生成，所以即使Lombok处理器失效，这段代码依然能正常编译。

解决方案 #

在Maven Compiler Plugin的annotationProcessorPaths中同时添加Lombok的依赖，必要时还要加上Lombok和MapStruct的绑定插件，示例配置如下：

<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>
            <!-- MapStruct处理器 -->
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>${mapstruct.version}</version>
            </path>
            <!-- Lombok处理器 -->
            <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>${lombok-mapstruct-binding.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

内容的提问来源于stack exchange，提问作者aviad cohen