如何为Eclipse创建兼容注解处理Factory Path的自定义注解处理器

核心适配规则 #

• 注解配置必须精确：@SupportedAnnotationTypes必须填写自定义注解的完整全类名，禁止使用*通配符，Eclipse JDT编译器对通配符的支持存在原生缺陷；@SupportedSourceVersion必须明确指定对应JDK版本，例如@SupportedSourceVersion(SourceVersion.RELEASE_17)，禁止使用RELEASE_*_OR_LATEST这类动态取值。
• 双注册机制保证兼容：除了Maven环境常用的META-INF/services/javax.annotation.processing.ProcessorSPI注册文件外，模块化项目还需要在module-info.java中添加provides javax.annotation.processing.Processor with 你的处理器全限定类名声明；如果适配Jakarta环境，需要额外添加META-INF/services/jakarta.annotation.processing.Processor注册文件。
• 增量编译适配：生成代码时调用filer.createResource必须传入对应的OriginatingElements参数，明确标注生成文件和原实体类的关联关系，Eclipse依赖该信息实现实体类修改时自动重新生成、清理旧文件。
• 日志与异常处理：所有日志必须使用processingEnv.getMessager()提供的接口输出，禁止使用System.out等标准流；所有业务异常必须主动捕获并通过Messager输出到Problem视图，否则Eclipse会静默跳过执行失败的处理器，无任何报错提示。
• 禁止使用非标准API：全程只使用javax.annotation.processing/jakarta.annotation.processing包下的标准API，禁止依赖Javac内部的Tree API等私有实现，Eclipse JDT编译器不识别此类API，会直接跳过处理器执行。

打包要求 #

• 处理器Jar必须将所有依赖全部打入，Factory Path使用独立类加载器加载处理器，依赖缺失会直接触发类加载失败，且不会抛出可见异常。
• 打包后校验SPI文件：解压Jar确认META-INF/services下的处理器注册文件存在，内容仅为处理器全类名，无多余空行、注释字符，Eclipse对该文件的解析规则非常严格，多余字符会导致注册失效。

Eclipse端验证配置 #

• 优先使用2021-09及以上版本的Eclipse，旧版本对JDK11+的注解处理器支持存在大量已知bug。
• 项目配置路径：Project Properties > Java Compiler > Annotation Processing，先勾选Enable annotation processing，生成目录推荐使用默认的.apt_generated，避免自定义路径的权限问题。
• 进入Factory Path添加处理器Jar后，点击Advanced按钮选择Add Library，如果扫描不到你的处理器，直接回查打包注册配置是否正确。
• 配置完成后Clean项目触发全量编译，生成的代码会自动输出到.apt_generated目录。

你的业务需求落地建议 #

• 生成的基础DTO、Mapper类统一添加@Generated注解，标注生成工具标识，提醒业务侧不要直接修改生成文件，通过继承的方式做扩展。
• 可通过@SupportedOptions定义自定义配置参数，例如dtoSuffix、enableMapper等，用户可在Eclipse Annotation Processing的Processor Options中自定义参数调整生成规则。
• 如果需要和Lombok同时生效，将你的处理器放在Factory Path列表中Lombok Jar的后面，可正常获取Lombok生成的getter、setter等方法。

内容的提问来源于stack exchange，提问作者Luis M. Villa