Java 注解处理器
注解处理器(Annotation Processor)是编译器在编译阶段调用的插件。它读取类型和注解,校验程序结构,或者生成 Java 源码、class 文件和资源文件。
框架要知道应用里有哪些路由和映射器,可以在启动时扫描 classpath,也可以把一部分发现和校验工作交给注解处理器。后者让错误更早暴露,也能减少启动时的工作。理解这两种方案的取舍,关键是看哪些类型在构建时就已确定,哪些必须等到运行时才能发现。
1. 面试核心
先记住这几条,再读正文- 注解处理器在编译期读取
Element和TypeMirror,通过Messager报错,通过Filer生成文件,无需加载或执行业务代码。卡 · 注解处理模型 - 处理器生成的新类型会进入后续处理轮次,生成普通资源文件则不会触发新轮次。
process返回true表示认领传入的注解类型,后续处理器不再收到这些类型;返回值和编译是否成功无关。- Java 17、21 的
javac默认搜索注解处理器,未指定处理器路径时会搜索普通 classpath。卡 · 处理器发现与认领规则 - IoC 容器负责对象创建、依赖注入和生命周期,反射为它提供运行时检查和调用能力。卡 · 运行时扫描
2. 运行时扫描
运行时扫描是框架在应用启动或运行期间查找候选类的过程。例如,应用把路由类放进约定的包并加上注解,框架启动时就到这个范围内查找。下面以通过反射注册路由为例,看看需要做哪些工作:
- 确定需要扫描的包、模块或 classpath 位置。
- 找出候选类,通过类加载器加载。
- 用反射读取类和方法上的运行时注解。
- 校验方法签名、访问权限和配置冲突。
- 创建对象,把调用信息放进注册表。
for (Class<?> candidate : scanner.findClasses("com.example")) {
for (Method method : candidate.getDeclaredMethods()) {
Route route = method.getAnnotation(Route.class);
if (route != null) {
registry.register(route.value(), candidate, method);
}
}
}
这段代码把标有 Route 的方法和对应路径放进 registry,后续请求按路径查找。新增一个路由时,只要写好类、加上 @Route,下次启动框架就能发现它,应用不需要另外维护一份候选类清单。
2.1 运行时扫描的成本
扫描的灵活性来自运行时发现,代价是这些工作也都发生在运行时:
- 启动时要枚举资源、加载类并解析注解,扫描范围越大越慢。
- 方法签名写错、配置重复,要等到启动才报出来。
- classpath、模块和自定义类加载器都会让「找到所有候选类」变得更难。
- 反射结果需要缓存,否则进入请求热路径后会反复查找。
- Native Image 这类闭世界编译要求构建时确定可达代码,反射的目标需要额外元数据(见第 7 节)。
扫描几个明确的类和遍历所有依赖包,成本差得很远。所以优化启动时,先缩小扫描范围,再测量编译期生成还能省下多少。
3. 注解处理模型
注解处理器通过编译器的语言模型读取程序结构,不需要把业务类加载成 Class 对象。语言模型是编译器对程序声明和类型的描述:Element 表示类、方法、字段这样的声明,TypeMirror 表示这些声明涉及的类型。处理器据此检查结构,不需要执行业务代码。
@SupportedAnnotationTypes("com.example.GenerateMapper")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public final class MapperProcessor extends AbstractProcessor {
@Override
public boolean process(
Set<? extends TypeElement> annotations,
RoundEnvironment roundEnvironment
) {
if (roundEnvironment.processingOver()) {
return false;
}
TypeElement marker = processingEnv
.getElementUtils()
.getTypeElement("com.example.GenerateMapper");
if (marker == null) {
return false;
}
for (Element element : roundEnvironment.getElementsAnnotatedWith(marker)) {
generateMapper((TypeElement) element);
}
return true;
}
}
MapperProcessor 用 @SupportedAnnotationTypes 声明自己处理哪个注解,用 @SupportedSourceVersion 声明支持的源码版本。声明的版本低于编译用的 -source 时,javac 会给出警告,比如在 JDK 21 上编译 Java 21 源码;要同时支持 17 和 21,可以改为重写 getSupportedSourceVersion(),返回 SourceVersion.latestSupported()。每一轮,它从 roundEnvironment 取出被 GenerateMapper 标注的元素,交给 generateMapper 生成映射器,具体怎样生成文件见第 4 节。
处理器由编译器调用,业务代码不会手动创建它的实例,用到的只是它生成的结果。所以构建时要把处理器和它的依赖交给编译器,配置注解处理器路径或显式指定处理器,第 8 节会具体说明。
3.1 多轮处理
注解处理是分轮进行的。处理器生成了新的源码或 class 文件,这些新类型会在下一轮进入语言模型,其他处理器还能继续处理新类型上的注解。某一轮不再产生新类型时,编译器进入最后一轮,然后继续完成编译。只生成普通资源文件不会触发新的一轮。
RoundEnvironment.processingOver() 判断当前是否是最后一轮,errorRaised() 判断之前有没有报告过错误。最后一轮适合做汇总和诊断。为了让多轮处理稳定结束,处理器要做到:
- 能认出已经处理过的元素,不重复生成。
- 不依赖多个处理器之间的执行顺序。
- 在最后一轮停止生成新类型。
- 相同输入产生相同结果,方便增量构建和缓存。
getElementsAnnotatedWith 每一轮只返回本轮新出现的元素,所以上面的 UserMapper 只在第一轮交给处理器,第二轮拿到的是新生成的 UserMapperGenerated。重复生成通常出在处理器自己身上:把元素留到后面的轮次再处理却没记下已经生成过,或者两个处理器、两个元素按命名规则生成了同一个类名。同一次编译中第二次创建同名文件时,Filer 会抛出 FilerException。
4. 代码生成
代码生成把重复的实现交给处理器来写。比如业务代码只声明对象之间的映射接口:
@GenerateMapper
public interface UserMapper {
UserDto toDto(User source);
}
处理器通过 Filer 为它生成实现类:
JavaFileObject file = processingEnv
.getFiler()
.createSourceFile("com.example.UserMapperGenerated", sourceElement);
try (Writer writer = file.openWriter()) {
writer.write("""
package com.example;
public final class UserMapperGenerated implements UserMapper {
@Override
public UserDto toDto(User source) {
return new UserDto(source.id(), source.name());
}
}
""");
}
createSourceFile 的第二个参数 sourceElement 记录这份文件是从哪个元素生成的,供构建工具做增量编译。生成的 UserMapperGenerated 会和业务源码一起编译,运行时调用它,和调用手写的类没有区别:
UserMapper mapper = new UserMapperGenerated();
UserDto dto = mapper.toDto(user);
标准处理器只能新增源码、class 文件或资源文件,不能改动已有的业务源码。Lombok 能给已有类加上 getter,是因为它修改了编译器内部的语法树,也就是编译器表示源码结构的数据。这依赖编译器内部 API,所以升级 JDK 和 IDE 时要额外验证兼容性。
4.1 编译期报错
处理器还能用 Messager 报告错误,并把错误定位到具体的程序元素:
processingEnv.getMessager().printMessage(
Diagnostic.Kind.ERROR,
"mapper method must have exactly one parameter",
methodElement
);
Diagnostic.Kind.ERROR 会让构建失败,错误信息指向 methodElement 对应的方法。签名写得不符合约定,开发者编译时就能看到,不用等到启动或处理请求时才发现。
5. 运行时扫描与注解处理器的比较
两种方案的根本差别在于,类型的发现、约束的校验和调用代码的准备,分别发生在什么时候。选择时,看应用需要多少运行时动态性:
| 维度 | 运行时扫描 | 编译期生成 |
|---|---|---|
| 发现时间 | 应用启动或首次使用 | 源码编译时 |
| 错误出现时间 | 启动或运行时 | 构建时 |
| 调用方式 | 常用反射、代理或动态分派 | 生成的普通类型和直接调用 |
| 扩展方式 | 放入运行时 classpath 即可发现 | 需要在编译阶段看到扩展源码或元数据 |
| 启动成本 | 扫描范围越大,成本越高 | 工作移到构建阶段 |
| 动态性 | 更适合运行时插件和未知类型 | 更适合闭世界和固定应用组成 |
| 调试重点 | 类加载、扫描条件、反射权限 | 生成源码、构建配置、处理轮次 |
编译期生成省下的是运行时的工作,换来的是构建上的维护成本:要管理处理器模块和生成文件,还要让 IDE 集成和增量编译正常工作。启动耗时降下来了,开发和构建流程也变复杂了,两边都要算进去。
6. 混合方案
编译期生成和运行时扫描可以配合使用。应用自身的类型在构建时就已确定,插件类型可能要到运行时才知道,两部分不必采用同一种发现方式。下面三种做法分别保留了不同程度的运行时选择能力。
6.1 编译期索引与运行时装配
候选类型已知、但对象仍要在运行时创建时,可以只生成索引。处理器把候选类型写进清单或资源文件,运行时读索引,只加载这些类型。这样既不用遍历整个 classpath,也不用生成完整的调用代码。
6.2 构建分析与运行时扩展
应用自己的类型提前分析,第三方插件保留运行时发现。比如在构建时固定容器管理的对象(Bean)、路由和序列化器,插件则用 ServiceLoader 或指定目录加载。ServiceLoader 按服务声明查找实现,扩展入口是明确的,常规启动也不需要大范围扫描。
6.3 生成工厂与运行时选择
候选实现已知、运行时才决定用哪一个时,可以生成类型安全的工厂或注册表。应用启动后按配置选择实现,候选范围由生成结果限定,动态选择保留了,动态扫描省掉了。
选择混合方案时,要确认插件是否需要独立安装。如果把插件范围也固定在构建阶段,每新增一个插件都得重新构建应用。
7. Native Image 与 AOT
AOT(Ahead-of-Time)指提前编译。Native Image 在构建时分析程序,生成原生可执行文件。它采用的闭世界假设是:构建时就要知道运行中会用到哪些代码。
问题出在动态行为上。按字符串加载类、反射访问成员、动态代理,这些目标有时没法从静态调用关系推出来,构建时分析不到,运行时就会找不到。所以要么显式注册这些目标,要么让框架生成描述它们的元数据。编译期生成在这里正好有用,它能提前完成这些工作,减少需要手写的运行时配置:
- 根据注解生成直接调用代码。
- 生成序列化器、映射器和依赖注入工厂。
- 为仍需反射的成员生成精确的注册元数据。
- 在构建阶段检查动态代理接口和资源文件。
反过来,长期运行、对启动耗时不敏感、又依赖运行时插件的 JVM 服务,用成熟的运行时模型仍然合适。要不要上 AOT,要同时看启动收益、构建成本和部署方式。
8. 处理器发现与认领规则
处理器写好以后,还得让编译器找到并执行它。Java 17、21 的 javac 默认会搜索注解处理器:没有指定处理器路径时,就在普通 classpath 里找;设置 -proc:none 则关闭注解处理。也可以显式指定处理器和路径:
javac --processor-path processor.jar \
-processor com.example.MapperProcessor \
-d out -s generated src/com/example/UserMapper.java
--processor-path 给出处理器所在的路径,-processor 指定要运行的处理器类。-d out 是 class 文件的输出目录,-s generated 是生成源码的目录。
Java 21 的 javac 在普通 classpath 上隐式发现处理器时,会输出一条提示,建议用 -processor、--processor-path 或 -proc:full 显式启用注解处理。所以在构建配置里显式写出处理器路径更稳妥,Maven 和 Gradle 都有对应的配置项。
自动发现依靠服务配置:classpath 上用 META-INF/services/javax.annotation.processing.Processor 文件,内容是处理器的完整类名;模块中则用 provides 声明。
process 的返回值决定其他处理器还能不能收到同一批注解。返回 true 表示认领传入的注解类型,后续处理器不再收到它们;返回 false 则让后续处理器继续处理。这个返回值和编译成功与否无关,编译错误要通过 Messager 报告。
9. 常见问题
9.1 标准注解处理器能修改原有类吗?
不能。标准 API 只支持读取语言模型、生成新文件和报告诊断,没有修改已有语法树(AST)的可移植接口。要改语法树只能依赖 javac 的内部 API,代价是编译器、JDK 和 IDE 的兼容成本。
9.2 为什么当前轮读不到刚生成的类型?
因为 Filer 创建的新源码要到下一轮才进入语言模型。生成文件之后,处理器要等下一轮再查询完整的新类型。这些文件由编译器继续处理和编译,处理器不需要手动编译。
9.3 编译期生成一定比反射快吗?
不一定,要看实际执行路径,最好测量。生成代码省掉了运行时的成员发现,直接调用也更容易被优化;代价是构建时间、生成代码的体积和生成器的维护。
评估时先分清省下的是启动时的一次性工作,还是每次调用的开销。低频的管理工具迁移过去收益有限,高频的序列化和函数调用路径更值得测量。
9.4 生成代码应该提交到 Git 吗?
能重复生成的文件放在构建目录里,由构建产生,不提交。否则手写源码改了,仓库里的生成结果却还是旧版本。
目标环境没法运行生成器,或者要把生成结果作为稳定源码发布时,可以提交。这时要加一致性校验,确认生成结果和输入源码匹配。
10. 面试题卡片
11. 参考资料
- Java API:Processor
- Java API:AbstractProcessor
- Java API:RoundEnvironment
- Java API:Filer
- Java API:Package javax.lang.model
- javac:Annotation Processing Options
来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明