如果你用过 Lombok，或者自己动手写过 Spring 的注解处理器，一定在 import 列表里撞见过javax.lang.model.util这个包。它是 Java 编译树 API（javax.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、List<String>这些）。
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 | 深度优先遍历元素树，常用于扫描类成员 |
| 简易 Visitor | SimpleElementVisitor、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正好互补：一个管“有哪些符号”，一个管“这些符号的类型之间是什么关系”。如果你要判断List<String>是否能赋值给Collection<? extends Object>，或者某个方法返回类型是不是void，都必须经过Types。
常用的方法：
isSubtype(TypeMirror, TypeMirror)：判断前者是不是后者的子类型。isAssignable(TypeMirror, TypeMirror)：判断是否可以赋值，这才是真正模拟编译器赋值规则的接口。isSameType(TypeMirror, TypeMirror)：判断两个类型是否完全相同。注意它比equals()更严格，因为它理解泛型变量和类型捕获的语义。getDeclaredType(TypeElement, TypeMirror...)：用TypeElement和泛型实参构造一个DeclaredType。比如types.getDeclaredType(listElement, stringType)可以得到List<String>。directSupertypes(TypeMirror)：拿到直接父类和直接实现的接口。erasure(TypeMirror)：返回泛型擦除后的类型。这个在对比两个泛型类是否相同的时候非常关键，后面避坑节会专门展开。asElement(TypeMirror)：把类型转成元素，比如List<String>转成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 加了交集类型IntersectionType），Visitor 接口也同步增加了对应的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分到visitPackage，ElementKind.CLASS分到visitType。适合需要按类别批量处理的场景，比如“对枚举做 A 逻辑，对类做 B 逻辑”。
Scanner 系列（ElementScanner）：它是深度优先扫描器，默认会遍历元素的所有子元素。比如你给它一个TypeElement，它会自动到字段、方法里面去，不用你手动递归getEnclosedElements()。做“扫一遍全类找问题”这种活最好用。
我的选择习惯是：只处理单一类型，用 Simple；需要按类别分流，用 Kind；需要遍历整棵元素树，用 Scanner。三套并不冲突，而且它们都继承自同一组抽象类，代码风格类似，切换成本不高。
3.3 一个可以抄作业的 TypeVisitor 用法
我用得最多的是SimpleTypeVisitor做“提取泛型实参”。比如我想知道一个字段到底是List<String>还是Map<String, Integer>，或者干脆就是个普通String，可以写一个工具方法：
private Optional<TypeMirror> firstTypeArgument(TypeMirror type, Types types) { return type.accept(new SimpleTypeVisitor<Optional<TypeMirror>, Void>() { @Override protected Optional<TypeMirror> defaultAction(TypeMirror t, Void unused) { return Optional.empty(); } @Override public Optional<TypeMirror> visitDeclared(DeclaredType t, Void unused) { if (t.getTypeArguments().isEmpty()) { return Optional.empty(); } return Optional.of(t.getTypeArguments().get(0)); } @Override public Optional<TypeMirror> visitArray(ArrayType t, Void unused) { return Optional.of(t.getComponentType()); } }, null); }注意accept()的第二个参数是传给 Visitor 的外部上下文，我用Void类型占位。defaultAction是所有未重写类型的兜底。这样调用方只要一行代码就能拿到字段里的泛型实参，而且对数组、普通类、未泛型化类都有明确结果，不用在外面写一堆判断。这种“把类型分支逻辑收进 Visitor”的写法，在代码生成器里非常值得推广。
4. 实战：用注解处理器校验 POJO 的 Getter/Setter
4.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) { List<ExecutableElement> methods = ElementFilter.methodsIn(typeElement.getEnclosedElements()); Set<String> getters = new HashSet<>(); Set<String> 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只是我随手占位的一个变量名，实际代码里可以直接用普通Set<String>存字段，不影响逻辑。重点是两个关键用法：一是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能处理List<String>和List<Integer>的区别。后来发现它确实能区分这两个。真正让我踩坑的是另一个场景：我需要判断“一个类型是否为java.util.List的子类型”，下意识写了types.isSubtype(fieldType, listElement.asType())。结果对于List<String>返回 true，对于裸List却返回 false，因为listElement.asType()得到的是List<E>，其中E是类型变量，而裸List在编译期模型里其实是有参数的，只是擦除前被补上了默认上限。
解决办法是用Types.erasure把两边都擦除再比较：
TypeMirror target = elementUtils.getTypeElement("java.util.List").asType(); // List<E> TypeMirror fieldType = ...; // 某个字段的类型 boolean isList = types.isSameType( types.erasure(fieldType), types.erasure(target) );要区分List<String>和List<Integer>，则不要用擦除，而是用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”来使，就会顺手很多。
