Java9迁移后Maven项目注解处理器失效问题排查

这个问题我之前在迁移Java 9模块化项目时也碰到过，核心原因是Java 9的模块系统改变了编译时类路径和模块路径的处理逻辑，加上Maven编译器插件的旧版本对模块化注解处理器支持不足。下面是一步步的排查和解决办法：

1. 优先升级Maven编译器插件 #

旧版本的maven-compiler-plugin（比如3.7.x及以下）对Java 9模块系统的注解处理器支持有缺陷，必须升级到3.8.0及以上版本（推荐3.11.0+，兼容性更好）。同时要明确指定Java版本为9，配置示例：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
            <configuration>
                <!-- 用release参数同时指定source/target，避免版本不一致 -->
                <release>9</release>
                <!-- 关键：显式配置注解处理器路径，Java 9后不能依赖普通依赖传递 -->
                <annotationProcessorPaths>
                    <path>
                        <groupId>你的处理器groupId</groupId>
                        <artifactId>你的处理器artifactId</artifactId>
                        <version>处理器版本号</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

2. 检查处理器模块的module-info.java配置 #

你的处理器模块必须正确声明模块依赖和服务提供：

module com.your.annotation.processor {
    // 必须依赖java.compiler模块，因为Processor接口在这个模块里
    requires java.compiler;
    // 如果用@AutoService，需要依赖auto-service模块（编译时依赖即可）
    requires com.google.auto.service;
    
    // 显式声明提供Processor服务实现
    provides javax.annotation.processing.Processor with com.your.annotation.processor.YourProcessorImpl;
}

注意：即使你用了@AutoService生成META-INF/services文件，在模块化项目中，provides语句仍然是必须的——模块系统会优先读取module-info的声明，而不是传统的服务加载文件。

3. 确保被处理模块的包可访问 #

如果你的注解处理器需要访问目标模块内的类（比如读取类上的注解、获取类结构），目标模块必须通过opens或exports语句开放对应包给处理器模块：

module com.your.target.app {
    // opens允许处理器在编译时通过反射访问包内的类（推荐，因为只开放编译时权限）
    opens com.your.target.app.annotation.to.process to com.your.annotation.processor;
    // 如果处理器不需要反射，仅读取注解信息，用exports也可以
    // exports com.your.target.app.annotation.to.process;
}

如果漏掉这一步，处理器可能无法访问目标类，导致看似“不执行”的假象（实际是执行了但无法处理任何类）。

4. 排查依赖范围问题 #

不要将注解处理器依赖放在普通的<dependencies>块中（即使加了provided scope），Java 9模块化环境下，注解处理器必须通过annotationProcessorPaths配置——普通依赖会被放到模块路径，而处理器需要在专门的处理器路径中才能被编译器识别。

额外验证步骤 #

• 执行mvn clean compile -X，查看编译日志中是否有处理器被加载的记录（比如会打印Annotation processors found: [com.your.annotation.processor.YourProcessorImpl]）
• 检查处理器模块的编译产物，确认module-info.class中包含正确的provides声明
• 如果用了@AutoService，确保处理器模块的target/classes/META-INF/services/javax.annotation.processing.Processor文件存在且包含你的处理器全类名

内容的提问来源于stack exchange，提问作者Magnus Lutz