跳到主要内容
约 12 分钟3 张卡

Java 注解处理器

注解处理器(Annotation Processor)是编译器在编译阶段调用的插件。它读取类型和注解,校验程序结构,或者生成 Java 源码、class 文件和资源文件。

框架要知道应用里有哪些路由和映射器,可以在启动时扫描 classpath,也可以把一部分发现和校验工作交给注解处理器。后者让错误更早暴露,也能减少启动时的工作。理解这两种方案的取舍,关键是看哪些类型在构建时就已确定,哪些必须等到运行时才能发现。

1. 面试核心​

先记住这几条,再读正文
  • 注解处理器在编译期读取 Element 和 TypeMirror,通过 Messager 报错,通过 Filer 生成文件,无需加载或执行业务代码。卡 · 注解处理模型
  • 处理器生成的新类型会进入后续处理轮次,生成普通资源文件则不会触发新轮次。
  • process 返回 true 表示认领传入的注解类型,后续处理器不再收到这些类型;返回值和编译是否成功无关。
  • Java 17、21 的 javac 默认搜索注解处理器,未指定处理器路径时会搜索普通 classpath。卡 · 处理器发现与认领规则
  • IoC 容器负责对象创建、依赖注入和生命周期,反射为它提供运行时检查和调用能力。卡 · 运行时扫描

2. 运行时扫描​

运行时扫描是框架在应用启动或运行期间查找候选类的过程。例如,应用把路由类放进约定的包并加上注解,框架启动时就到这个范围内查找。下面以通过反射注册路由为例,看看需要做哪些工作:

  1. 确定需要扫描的包、模块或 classpath 位置。
  2. 找出候选类,通过类加载器加载。
  3. 用反射读取类和方法上的运行时注解。
  4. 校验方法签名、访问权限和配置冲突。
  5. 创建对象,把调用信息放进注册表。
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 为什么当前轮读不到刚生成的类型?​

9.3 编译期生成一定比反射快吗?​

9.4 生成代码应该提交到 Git 吗?​

10. 面试题卡片​

11. 参考资料​

来源:Coding 101 原文 · 免费阅读,引用请保留出处。内容使用说明