Java 17升级后AnnotationTypeMismatchException异常排查求助

问题背景 #

因上游依赖变更，将项目从Java 11升级至Java 17。项目大量使用注解驱动代码生成，升级后触发以下异常。

异常信息 #

java.lang.annotation.AnnotationTypeMismatchException: Incorrectly typed data found for annotation element public abstract pro.projo.interfaces.annotation.Options pro.projo.interfaces.annotation.Interface.options() (Found data of type pro.projo.interfaces.annotation.Options)
at com.sun.tools.javac.model.AnnotationProxyMaker$ValueVisitor$1AnnotationTypeMismatchExceptionProxy.generateException (AnnotationProxyMaker.java:271)
at sun.reflect.annotation.AnnotationInvocationHandler.invoke (AnnotationInvocationHandler.java:89)
at jdk.proxy4.$Proxy31.options (Unknown Source)
at pro.projo.generation.interfaces.InterfaceTemplateProcessor.lambda$getInterfaceConfiguration$5 (InterfaceTemplateProcessor.java:268)
at java.util.stream.ReferencePipeline$3$1.accept (ReferencePipeline.java:197)
at java.util.ArrayList$ArrayListSpliterator.forEachRemaining (ArrayList.java:1625)
at java.util.stream.AbstractPipeline.copyInto (AbstractPipeline.java:509)
at java.util.stream.AbstractPipeline.wrapAndCopyInto (AbstractPipeline.java:499)
at java.util.stream.ReduceOps$ReduceOp.evaluateSequential (ReduceOps.java:921)
at java.util.stream.AbstractPipeline.evaluate (AbstractPipeline.java:234)
at java.util.stream.ReferencePipeline.collect (ReferencePipeline.java:682)
at pro.projo.generation.interfaces.InterfaceTemplateProcessor.getInterfaceConfiguration (InterfaceTemplateProcessor.java:379)
at pro.projo.generation.interfaces.InterfaceTemplateProcessor.process (InterfaceTemplateProcessor.java:185)
at pro.projo.generation.interfaces.InterfaceTemplateProcessor.process (InterfaceTemplateProcessor.java:162)
at com.sun.tools.javac.processing.JavacProcessingEnvironment.callProcessor (JavacProcessingEnvironment.java:1023)
at com.sun.tools.javac.processing.JavacProcessingEnvironment.discoverAndRunProcs (JavacProcessingEnvironment.java:939)
at com.sun.tools.javac.processing.JavacProcessingEnvironment$Round.run (JavacProcessingEnvironment.java:1267)
at com.sun.tools.javac.processing.JavacProcessingEnvironment.doProcessing (JavacProcessingEnvironment.java:1382)
at com.sun.tools.javac.main.JavaCompiler.processAnnotations (JavaCompiler.java:1234)

关键困惑点 #

• 预期类型与实际找到的类型完全一致（均为pro.projo.interfaces.annotation.Options）
• 注解处理库基于Java 8编写（使用@SupportedSourceVersion(RELEASE_8)和ElementScanner8），在Java 9、11中运行正常
• 非注解场景中，此类看似类型匹配却报错的异常（如ClassCastException）通常与类加载器有关，想确认注解处理器是否存在同类情况
• 切回Java 11可解决问题，但无法作为长期方案

调试思路 #

• 排查类加载器隔离问题：
  在异常触发点添加日志，打印Options.class.getClassLoader()以及从注解中获取的实例的类加载器annotation.options().getClass().getClassLoader()，对比两者是否为同一个加载器。Java 17对模块系统和类加载器的约束更严格，注解处理器运行在编译期的类加载环境中，可能存在API类和处理器类被不同加载器加载的情况。
• 检查注解处理库的兼容性：
  确认使用的Projo库是否有Java 17兼容的版本，或者是否有已知的Java 17适配问题。虽然库标注了支持RELEASE_8，但Java 17的注解处理API可能有隐性变化，比如AnnotationProxyMaker的实现逻辑调整。
• 升级注解处理API依赖：
  项目中如果依赖了javax.annotation.processing相关的API，尝试升级到Jakarta对应的版本，或者确保使用的是与Java 17兼容的JDK自带API版本，避免混用不同版本的注解处理API。
• 启用编译期调试日志：
  添加Javac编译参数-Xdiags:verbose和-verbose:annotation，查看编译过程中注解处理的详细日志，特别是Options注解的加载和解析过程，是否有加载异常或重复加载的情况。
• 调试注解处理器代码：
  在InterfaceTemplateProcessor.java的第268行（异常触发点）添加断点，调试获取注解实例的过程，查看annotation.options()的实际类型细节，比如是否是代理类，代理类的类加载器信息。Java 17的代理生成逻辑可能与之前版本不同，导致类型校验失败。
• 检查模块配置（若使用JPMS）：
  如果项目使用了JPMS模块，确认module-info.java中是否正确导出了pro.projo.interfaces.annotation包，并且注解处理器模块是否正确依赖了该模块。Java 17对模块的访问权限检查更严格，可能导致注解类无法被正确加载。

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