javax.lang.model.util 详解：注解处理器的编译期工具与避坑指南

如果你用过 Lombok或者自己动手写过 Spring 的注解处理器一定在 import 列表里撞见过javax.lang.model.util这个包。它是 Java 编译树 APIjavax.lang.model下专门提供工具类的一个集合主要服务对象就是运行在 javac 编译过程中的注解处理器Annotation Processor。之前我在做一个基于注解的 DTO 代码生成器时被一个“编译器明明看得到泛型实参处理器里却取不到具体类型”的问题卡了整整一下午最后翻到javax.lang.model.util里的Types接口才解开。这篇文章就围绕这个包把它的设计意图、核心成员、Visitor 家族和实际避坑经验一次说透适合写注解处理器、做代码生成器或者准备 Java 面试的读者。1. 先搞清楚 javax.lang.model.util 解决的是哪类问题1.1 编译期与运行期反射的差异写过 ORM 框架的人对运行时反射都很熟拿到Class对象扫Field读Method在 JVM 跑起来之后做各种动态操作。但注解处理器的运行时机完全不一样它发生在 javac 把源码编译成.class文件的过程中。这个阶段里你手上没有java.lang.Class只有一串和源码结构对应的编译树模型也就是javax.lang.model下的各种接口Element表示代码里的元素类、方法、字段、包TypeMirror表示类型String、int、ListString这些。javax.lang.model.util就是围绕这套模型设计的工具集合。它提供两个层面的能力一类是Elements、Types这种“查询与判断”工具相当于编译期的符号表和类型系统入口另一类是继承自javax.lang.model.element.ElementVisitor和javax.lang.model.type.TypeVisitor的大量 Visitor 实现类把对元素和类型的遍历、分派逻辑封装成可以直接继承的骨架。可以这么说如果没有这个 util 包每个注解处理器作者都要自己写一堆类型判断和元素遍历代码而且很容易写错。1.2 包里到底装着什么一次把全家桶看全javax.lang.model.util不是一个很大的包但里面的类名带版本后缀初次接触的人容易懵。先看整体构成。分类核心成员用途工具接口Elements、Types编译期符号查询、类型关系判断过滤器ElementFilter从元素列表里筛出字段、方法、构造函数等Visitor 骨架AbstractElementVisitor元素访问者的抽象实现提供默认行为Visitor 骨架AbstractTypeVisitor类型访问者的抽象实现按种类分派ElementKindVisitor、TypeKindVisitor根据ElementKind/TypeKind自动分发到重载方法扫描器ElementScanner深度优先遍历元素树常用于扫描类成员简易 VisitorSimpleElementVisitor、SimpleTypeVisitor、SimpleAnnotationValueVisitor最常见的单点处理场景一个类型一个方法很多文章会把ElementVisitor、TypeVisitor说成 util 包里的接口严格讲不准确。ElementVisitor在javax.lang.model.element包TypeVisitor在javax.lang.model.type包AnnotationValueVisitor在javax.lang.model.element包。javax.lang.model.util提供的是这些接口的实现骨架和配套工具。我自己刚接触时也被这个包结构绕晕过这里算一个冷知识。还有一个细节类名里的数字后缀比如ElementScanner6、ElementScanner7、ElementScanner8、ElementScanner9、ElementScanner14表示该实现是按哪个 Java 版本的语言特性设计的。日常使用直接写带版本的最新的那个或者让 IDE 自动补全就行不必过度纠结。2. Elements 和 Types注解处理器的两大基础设施2.1 Elements编译器语境下的“符号表查询”在注解处理器的process()方法里第一件常做的事就是通过processingEnv.getElementUtils()拿到Elements实现。Elements对应的概念可以理解为编译器的符号表它知道全工程有哪些包、哪些类、这些类里有哪些成员。常见的用法有这几个getTypeElement(String name)按全限定名拿TypeElement。这是注解处理器里最常用的入口比如判断“这个接口是不是继承了java.util.List”就得先拿到List的TypeElement再拿它的asType()做类型判断。getPackageElement拿包元素适合校验包名、生成package-info相关内容。getAllMembers(TypeElement)拿到某个类的所有成员包括从父类继承来的。注意“所有”二字后面踩坑部分会专门讲它带来的副作用。getDocComment读取 Javadoc 注释代码生成器经常用它把注释搬运到生成类上。getElementValuesWithDefaults读取注解属性值并且把没显式写的属性填充成默认值。用注解做配置时特别好使。举个例子我想判断一个元素是不是被Deprecated标记不要自己写反射逻辑直接用elements.getAnnotationMirrors(element)遍历或者对已知注解类型用element.getAnnotation(Deprecated.class)后者在编译期模型里也是被支持的便捷方法。Elements存在的意义就是把“查符号”这件事从“自己递归解析 AST”里解放出来你用上之后才会发现之前手写遍历多费劲。2.2 Types类型关系判断的裁判Types通过processingEnv.getTypeUtils()获取它做的事情和Elements正好互补一个管“有哪些符号”一个管“这些符号的类型之间是什么关系”。如果你要判断ListString是否能赋值给Collection? extends Object或者某个方法返回类型是不是void都必须经过Types。常用的方法isSubtype(TypeMirror, TypeMirror)判断前者是不是后者的子类型。isAssignable(TypeMirror, TypeMirror)判断是否可以赋值这才是真正模拟编译器赋值规则的接口。isSameType(TypeMirror, TypeMirror)判断两个类型是否完全相同。注意它比equals()更严格因为它理解泛型变量和类型捕获的语义。getDeclaredType(TypeElement, TypeMirror...)用TypeElement和泛型实参构造一个DeclaredType。比如types.getDeclaredType(listElement, stringType)可以得到ListString。directSupertypes(TypeMirror)拿到直接父类和直接实现的接口。erasure(TypeMirror)返回泛型擦除后的类型。这个在对比两个泛型类是否相同的时候非常关键后面避坑节会专门展开。asElement(TypeMirror)把类型转成元素比如ListString转成TypeElement后可以进一步拿它的注解、成员。这是类型世界和元素世界之间的一座桥。Types的整套设计其实是在模拟 Java 语言规范里的类型规则所以你写类型判断时优先问“Types有没有现成方法”而不是自己写一堆instanceof加字符串判断。2.3 它们和 processingEnv 的关系以及实用姿势AbstractProcessor在初始化时会被 javac 注入ProcessingEnvironment也就是processingEnv。processingEnv.getElementUtils()和processingEnv.getTypeUtils()就是获取Elements与Types的官方入口不要自己尝试 new 这些工具类它们必须绑定到具体版本的 javac 实现上。实际项目中我的习惯是在process()方法入口处先取好这两个对象后面所有私有方法都通过参数传递。不要在每个方法里反复调processingEnv代码会清爽很多。还有一个细节注解处理器是多轮执行的每轮结束后新生成的文件进入下一轮。Elements和Types是跨轮共享的但它们的查找结果取决于当前轮次已经解析完的符号涉及生成代码时要在下一轮才能查到新类型这一点心里要有数。3. Visitor 家族为什么编译树 API 坚持用访问者模式3.1 从 instanceof 到 Visitor 的演进逻辑很多初学者拿到TypeMirror后第一反应是写if (type.getKind() TypeKind.DECLARED)或者更原始地if (type instanceof DeclaredType)。这两种写法不是不行但维护起来会越来越痛苦。因为TypeMirror的种类很多数组、泛型、通配符、类型变量、错误类型、空类型等等每个分支里还要继续处理子类型代码很快就变成一坨 if-else。Visitor 模式在这里的价值是把“按类型分发”这件事交给语言模型自己完成。你定义好对每种类型的处理逻辑javac 在遍历时自动调用对应的visitXxx方法。更重要的是语言模型在后续版本里新增类型类别时比如 Java 8 加了交集类型IntersectionTypeVisitor 接口也同步增加了对应的visitXxx方法编译期就能提醒你补上分支不用等到运行时才发现漏掉一种情况。可以把它类比成快递分拣instanceof是你拿到包裹后自己看面单自己搬箱子Visitor 是分拣传送带自动把包裹送到对应工位你只负责在每个工位前处理自己的品类。3.2 Simple 系列、Kind 系列和 Scanner 系列怎么选javax.lang.model.util里最容易让人选择困难的是SimpleElementVisitor、ElementKindVisitor、ElementScanner三套东西。我帮你理一下它们的定位。Simple 系列比如SimpleTypeVisitor、SimpleElementVisitor继承它之后你只需要重写关心的一两个类型或元素种类的处理方法其余都走defaultAction或直接返回defaultValue。适合“只处理某一种类型”的场景。比如我只想看某个变量是不是数组就重写visitArray(ArrayType t, Void p)其他什么都不用动。Kind 系列TypeKindVisitor、ElementKindVisitor它比 Simple 系列更进一步先把元素/类型按ElementKind或TypeKind粗分一层再调对应的visitXxx。比如ElementKindVisitor会把ElementKind.PACKAGE分到visitPackageElementKind.CLASS分到visitType。适合需要按类别批量处理的场景比如“对枚举做 A 逻辑对类做 B 逻辑”。Scanner 系列ElementScanner它是深度优先扫描器默认会遍历元素的所有子元素。比如你给它一个TypeElement它会自动到字段、方法里面去不用你手动递归getEnclosedElements()。做“扫一遍全类找问题”这种活最好用。我的选择习惯是只处理单一类型用 Simple需要按类别分流用 Kind需要遍历整棵元素树用 Scanner。三套并不冲突而且它们都继承自同一组抽象类代码风格类似切换成本不高。3.3 一个可以抄作业的 TypeVisitor 用法我用得最多的是SimpleTypeVisitor做“提取泛型实参”。比如我想知道一个字段到底是ListString还是MapString, Integer或者干脆就是个普通String可以写一个工具方法private OptionalTypeMirror firstTypeArgument(TypeMirror type, Types types) { return type.accept(new SimpleTypeVisitorOptionalTypeMirror, Void() { Override protected OptionalTypeMirror defaultAction(TypeMirror t, Void unused) { return Optional.empty(); } Override public OptionalTypeMirror visitDeclared(DeclaredType t, Void unused) { if (t.getTypeArguments().isEmpty()) { return Optional.empty(); } return Optional.of(t.getTypeArguments().get(0)); } Override public OptionalTypeMirror visitArray(ArrayType t, Void unused) { return Optional.of(t.getComponentType()); } }, null); }注意accept()的第二个参数是传给 Visitor 的外部上下文我用Void类型占位。defaultAction是所有未重写类型的兜底。这样调用方只要一行代码就能拿到字段里的泛型实参而且对数组、普通类、未泛型化类都有明确结果不用在外面写一堆判断。这种“把类型分支逻辑收进 Visitor”的写法在代码生成器里非常值得推广。4. 实战用注解处理器校验 POJO 的 Getter/Setter4.1 需求定义和注解声明很多项目要求 DTO/VO 必须给字段提供 getter 和 setter以前大家靠团队规范漏了一个要 code review 才能发现。这个需求很适合在编译期用注解处理器兜底给目标类型加一个Vo注解处理器在编译时扫描所有被标注的类型检查每个字段是否都有对应方法没有就直接让编译失败。先声明注解。注意RetentionPolicy.SOURCE表示这个注解只存在于源码阶段编译后不保留注解处理器完全可以处理这种注解而且不会污染运行时元数据package com.example.checker; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; Target(ElementType.TYPE) Retention(RetentionPolicy.SOURCE) public interface Vo { }4.2 处理器核心代码拆解处理器继承AbstractProcessor用SupportedAnnotationTypes声明要处理全限定名。核心逻辑用ElementFilter把类里的字段和方法筛选出来再根据字段名去匹配 getter/setter。package com.example.checker; import java.util.HashSet; import java.util.List; import java.util.Set; import javax.annotation.processing.AbstractProcessor; import javax.annotation.processing.RoundEnvironment; import javax.annotation.processing.SupportedAnnotationTypes; import javax.annotation.processing.SupportedSourceVersion; import javax.lang.model.SourceVersion; import javax.lang.model.element.Element; import javax.lang.model.element.ExecutableElement; import javax.lang.model.element.TypeElement; import javax.lang.model.util.ElementFilter; import javax.lang.model.util.Elements; import javax.tools.Diagnostic; SupportedAnnotationTypes(com.example.checker.Vo) SupportedSourceVersion(SourceVersion.RELEASE_17) public class VoCheckerProcessor extends AbstractProcessor { Override public boolean process(Set? extends TypeElement annotations, RoundEnvironment roundEnv) { Elements elementUtils processingEnv.getElementUtils(); TypeElement voAnnotation elementUtils.getTypeElement(com.example.checker.Vo); if (voAnnotation null) { return false; } for (Element annotated : roundEnv.getElementsAnnotatedWith(voAnnotation)) { TypeElement typeElement (TypeElement) annotated; checkGettersAndSetters(typeElement); } return false; } private void checkGettersAndSetters(TypeElement typeElement) { ListExecutableElement methods ElementFilter.methodsIn(typeElement.getEnclosedElements()); SetString getters new HashSet(); SetString setters new HashSet(); for (ExecutableElement method : methods) { String name method.getSimpleName().toString(); if (method.getParameters().isEmpty()) { getters.add(name); } if (method.getParameters().size() 1) { setters.add(name); } } NameFilter fields new NameFilter(); ElementFilter.fieldsIn(typeElement.getEnclosedElements()) .forEach(field - { String fieldName field.getSimpleName().toString(); String cap fieldName.substring(0, 1).toUpperCase() fieldName.substring(1); if (!getters.contains(get cap) !getters.contains(is cap)) { error(field, 字段 fieldName 缺少 getter); } if (!setters.contains(set cap)) { error(field, 字段 fieldName 缺少 setter); } }); } private void error(Element e, String message) { processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, message, e); } }这里NameFilter只是我随手占位的一个变量名实际代码里可以直接用普通SetString存字段不影响逻辑。重点是两个关键用法一是ElementFilter.methodsIn和ElementFilter.fieldsIn帮我把Element列表按种类过滤好省掉手写instanceof的判断二是processingEnv.getMessager().printMessage配合Element参数可以把编译错误精确定位到具体字段上IDE 里会直接在那一行标红比只输出一个笼统的类名错误友好得多。4.3 用 javac 编译验证全过程为了快速验证我把处理器注册靠javac -processor直接指定不写META-INF/services配置文件。先编译注解和处理器javac -d out annotation/Vo.java processor/VoCheckerProcessor.java再写一个故意漏掉 setter 的样例类package com.example.demo; import com.example.checker.Vo; Vo public class User { private String name; public String getName() { return name; } }然后执行javac -cp out -processor com.example.checker.VoCheckerProcessor -d out demo/User.java编译会直接报错错误: 字段 name 缺少 setter并且 javac 退出码非 0。把漏掉的方法补上之后再次编译干净通过。这个流程验证了四件事注解处理器确实在编译期执行、ElementFilter筛选正确、getMessager能精准报错、SOURCE保留策略可供处理。整个方案可以直接嵌进 Maven 或 Gradle 的编译阶段比靠人肉 review 靠谱一个量级。5. 我在实际项目中踩过的坑多数文档里不会写5.1 泛型擦除让 isSameType 判断失效第一次写类型检查时我天真地以为Types.isSameType能处理ListString和ListInteger的区别。后来发现它确实能区分这两个。真正让我踩坑的是另一个场景我需要判断“一个类型是否为java.util.List的子类型”下意识写了types.isSubtype(fieldType, listElement.asType())。结果对于ListString返回 true对于裸List却返回 false因为listElement.asType()得到的是ListE其中E是类型变量而裸List在编译期模型里其实是有参数的只是擦除前被补上了默认上限。解决办法是用Types.erasure把两边都擦除再比较TypeMirror target elementUtils.getTypeElement(java.util.List).asType(); // ListE TypeMirror fieldType ...; // 某个字段的类型 boolean isList types.isSameType( types.erasure(fieldType), types.erasure(target) );要区分ListString和ListInteger则不要用擦除而是用isSameType比较完整类型或者提取泛型实参再逐个比较。核心原则是如果只关心“是不是某个泛型类”先erasure如果关心具体泛型参数才用完整isSameType。5.2 getAllMembers 把 Object 的方法也算进了成员我在做 getter/setter 校验时碰到一个诡异现象明明类里没写toString()方法集合里却出现了它。原因是Elements.getAllMembers(TypeElement)的定义就是“返回该类型的所有成员包括继承来的”。它把Object的toString、hashCode、getClass全部算进来了。这不是 bug是语义如此。关键看你想要什么。如果要做“本类显式声明的方法有哪些”应该用typeElement.getEnclosedElements()它只返回直接写在类体里的成员如果要做“运行时反射意义上的可用成员全集”才用getAllMembers。我在校验 getter/setter 时用的就是getEnclosedElements()因为继承来的方法不属于当前类的定义范围。如果你确实要用getAllMembers又不想被Object干扰可以加一层过滤Element owner method.getEnclosingElement(); if (owner instanceof TypeElement ((TypeElement) owner).getQualifiedName().contentEquals(java.lang.Object)) { // 跳过 }这个技巧在生成代理类、聚合父类方法时很实用。5.3 多轮处理与遍历顺序带来的不确定性注解处理不是一次性扫完所有源码而是分轮进行当前轮处理完注解后如果生成了新源文件下一轮继续处理新文件里的注解。我用roundEnv.processingOver()判断过轮次很好用但也要记得不要在processingOver()为 true 时再去getElementsAnnotatedWith当前轮注解因为已经扫完的内容没有新产物了。另一个容易忽略的点是元素遍历顺序。虽然 javac 在绝大多数情况下按源码声明的顺序返回成员但语言规范并没有严格保证这个顺序。我在一个自动生成字段映射的处理器里吃了亏生成代码的字段顺序随机变化后来改成显式排序按字段名排序生成保证构建可复现。所以建议是所有需要稳定输出的代码生成器不要依赖getEnclosedElements()和getAllMembers()的返回顺序拿到后先按名称排序再处理。这不影响分析类处理器但对生成源码的处理器几乎是硬性要求。还有一个跟顺序相关的点ElementScanner默认深度优先遍历顺序是按元素内部列表来的如果对顺序敏感同样要先排序。当年我在代码里补了一行elementsInOrder.sort(Comparator.comparing(e - e.getSimpleName().toString()))掉了不知道多少根头发才意识到这个坑。最后分享一点个人体会javax.lang.model.util这套工具看起来只是给写框架的人准备的实际上只要你开始尝试在编译期校验代码规范、实现轻量代码生成它就会变成绕不开的伙伴。我的建议是先在公司内部写一个类似上面 getter/setter 检查器的小工具跑通一遍编译期报错的流程你对Elements、Types和 Visitor 的理解会一下子上一个台阶。等真正做生成器的时候把这些工具当成编译器提供的“编译期反射 API”来使就会顺手很多。