简介：围绕 Lombok 注解处理器与编译期字节码操作的代码资源，面向具备 Java 基础的后端开发者，旨在讲清 Lombok 如何借助编译阶段的注解处理能力，自动生成 getter、setter、构造器、equals、hashCode 等样板代码，并提示使用边界与常见兼容性问题。压缩包共 40 个文件，大小约 88KB，以 Java 源文件、class 字节码、XML 配置和 JAR 依赖为主，另有 bpmn、dmn 等流程与规则示例文件，覆盖从注解定义、处理器实现到 IDE 插件协作的完整实验路径；工程采用多模块结构，便于按功能拆分阅读。已有 665 人学习下载，适合希望掌握 Lombok 内部机制或自行扩展自定义注解处理器的开发者。通过实际运行代码，可直观对照源码与生成后的字节码，理解 ASM 库在编译期间插入方法的具体时机，也能看到自定义注解处理器的扩展写法，为排查第三方库兼容性问题提供实践参考。1. Lombok：一个在编译期「改写源码」的黑客式注解处理器很多开发者第一次接触 Lombok 时，会以为@Getter是 IDE 补全出来的，或是运行时的反射魔法。真相恰好相反：你的.java源文件里从未存在过getName()，但.class文件里确实有它——它是 javac 编译到一半时，被一个跑在注解处理器队列里的程序，直接往编译器内部语法树上画上去的。无论把 lombok 软件/插件装成 IDE 组件还是构建依赖，它的执行位置都只有一个：javac 的注解处理引擎。弄懂它怎么进编译器、为什么能改树，你在 JDK 升级翻车、构建找不到 getter 这类问题上，就能一眼定位根源，而不是靠换版本碰运气。2. 注解处理的边界：为什么标准 API 只能「新增」而不能「修改」2.1 JSR 269 的轮次模型：编译被拆成了多轮问答javac 的注解处理机制来自 JSR 269（Java Annotation Processing），它本质上是在编译流程中间插入了一个「多轮问答」循环。每一轮，javac 把当前可见的注解交给对应处理器；处理器可以读注解所在元素的信息，也可以通过Filer生成新的.java或.class文件。只要这一轮有新的文件产生，javac 就再开一轮，直到某一轮没有任何新文件产出，进入最后一轮（last round），处理引擎退出，编译继续走类型检查和字节码生成。轮次javac 做什么处理器能做第 1 轮解析源码，收集注解读取符号、生成新文件第 N 轮编译新文件，再次收集注解继续读取、继续生成最后一轮没有新文件了收尾清理，随后退出关键点在于处理器手里的输入：Elements（只读符号模型）和RoundEnvironment（当轮环境）。你可以问「这个类有哪些字段、字段类型是什么」，但没有一条 API 能回答「给这个类加一个方法」。这不是 API 设计疏漏，而是刻意划定的边界：编译单元的所有权归编译器，处理器只是旁路观察者，只能往旁边「新增」，不能回头「修改」已有的树。// 一个符合 JSR 269 的处理器：只能生成新文件，不能改已有类 public final class GenProcessor extends AbstractProcessor { @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { for (TypeElement annotation : annotations) { for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) { // element 是编译单元里的类/字段/方法 // 能读它的修饰符、名字、类型，但无法往它的方法列表里塞东西 // 想产出代码只能走 Filer： // Filer filer = processingEnv.getFiler(); // filer.createSourceFile("com.example.Generated"); } } return true; // 声明本轮注解已被自己消费 } }这段代码里，roundEnv.getElementsAnnotatedWith(annotation)返回的元素对读取完全开放，但任何「写入现有类型」的操作都没有对应 API。Filer创建的新文件还会受「类型重复」约束——如果你生成一个与已有类同名的类，会直接编译报错。所以标准注解处理的世界观是「增量」的：你可以基于现有代码生成新类型，但永远无法回到现有类型内部去改造它。2.2 为什么「生成新类」或「运行时增强」都救不了 Lombok顺着这个边界往下想，Lombok 似乎有三条路可以绕。第一条是「生成一个平行的类」，比如FooGetter，把 getter 都放在里面——这毫无意义，调用方写的是foo.getName()，没人会去实例化一个平行的工具类。第二条是「改继承结构」，让Foo继承一个带 getter 的基类——这会破坏原有类型语义，Java 单继承也经不起这么折腾。第三条是运行时字节码增强（ASM 或动态代理），但那只对通过代理创建的实例生效，直接new Foo()走的是原始字节码，方法表里没有就是没有，反射也救不回来。所以摆在 Lombok 面前的路只剩一条：修改 javac 自己持有的那棵 AST。JSR 269 确实给了处理器一个看见 AST 的窗口——Trees.instance(processingEnv)之后可以调用getTree(element)——但com.sun.source.tree是只读接口，写操作没有承诺。真正的修改能力藏在 javac 的实现类里：com.sun.tools.javac.tree.JCTree的节点类暴露了公开字段，比如JCClassDecl.defs就是类的成员声明列表，谁拿到这个字段，谁就能改树。Lombok 选择的就是这条路：放弃稳定 API，直接操作编译器内部实现。这也是它此后一切兼容性问题的总根源。提示：判断一个注解处理框架是「标准派」还是「Lombok 派」，只看它是否依赖com.sun.tools.javac就够。标准派只碰javax.annotation.processing.*和javax.lang.model.*，而 Lombok 的核心逻辑几乎全在lombok.javac包底下。3. 侵入式改造：Lombok 怎么混进 javac 并改写 AST3.1 入口伪装：AnnotationProcessorHider 与自研类加载器先从入口看。Lombok 的 jar 里，META-INF/services/javax.annotation.processing.Processor指向的不是大家以为的lombok.core.AnnotationProcessor，而是一个叫lombok.launch.AnnotationProcessorHider$AnnotationProcessor的壳类。为什么套壳？因为 javac 的注解处理引擎用标准ServiceLoader发现处理器，壳类必须能被系统类加载器加载；但 Lombok 真正要访问的com.sun.tools.javac.*内部类，在 JDK 9 引入模块系统后默认不对外导出。如果让真实处理器直接挂在系统类加载器下，一碰JCTree就会抛IllegalAccessError。壳类的破解办法是「自己加载自己」：它内部实现了一个ShadowClassLoader，把lombok.core底下的真实处理器重新加载一遍。这个加载器的关键动作是绕过模块边界的访问检查——在较新的 JDK 上，常见做法是借道sun.misc.Unsafe打开jdk.compiler模块内部包的访问权限，再在内存里直接定义lombok.javac.*的类。这样真实处理器所在的类加载域与 javac 内部类一致，私有字段随便碰。这也是为什么每次 JDK 大版本更新，Lombok 都要跟着发新版——内部模块的访问规则一变，撬锁姿势就得跟着换。// 壳类的高度简化示意（真实实现比这复杂得多） public final class AnnotationProcessorHider { public static class AnnotationProcessor extends AbstractProcessor { private final Processor realProcessor; public AnnotationProcessor() { // 用自研加载器绕过模块边界，加载 lombok.core 里的真正实现 ClassLoader shadow = ShadowClassLoader.create(getClass().getClassLoader()); this.realProcessor = newInstance(shadow, "lombok.core.AnnotationProcessor"); } @Override public void init(ProcessingEnvironment env) { realProcessor.init(env); // 把 javac 给的编译环境透传进去 } @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { return realProcessor.process(annotations, roundEnv); // 真正干活 } } }注意init(ProcessingEnvironment env)透传的这个env：在 javac 里它的实现类是JavacProcessingEnvironment。真实处理器拿到它之后，会从里面挖出Context——javac 的全局上下文对象，类似一个内部 IOC 容器——再从Context提出TreeMaker、Names、Symtab这些核心服务。整个入侵的起点就是这个Context：拿到它，等于拿到了编译器全部内部依赖的钥匙串。3.2 JavacAST 与 TreeMaker：给编译器准备的语法树手术台拿到Context之后，Lombok 的工作可以概括成三句话：把编译单元包成自己的树结构、定位要改的节点、用TreeMaker造出新节点并塞进父节点的成员列表。javac 的 AST 长这样：一个编译单元对应JCCompilationUnit，下面挂JCClassDecl（类声明），类声明里有个公开字段defs，里面装着JCVariableDecl（字段）、JCMethodDecl（方法）等成员节点。所谓「加一个 getter」，本质就是往JCClassDecl.defs这个List<JCTree>末尾append一个新拼出来的JCMethodDecl。拼装不是靠写字符串再 parse，而是用TreeMaker这个语法树工厂一个个参数构造：// 用 javac 内部 TreeMaker 组装 getter 的简化示意 TreeMaker make = TreeMaker.instance(context); // javac 的语法树工厂 Names names = Names.instance(context); // 符号名表 JCMethodDecl buildGetter(JCVariableDecl field) { return make.MethodDef( make.Modifiers(Flags.PUBLIC), // public names.fromString("get" + capitalize(field.name)), // getName make.Type(field.type), // 返回类型 = 字段类型 List.nil(), // 泛型参数 List.nil(), // 形参列表 List.nil(), // 抛出异常列表 make.Block(0, List.of( make.Return( make.Select(make.Ident(names.fromString("this")), field.name)))), // return this.name; null // 默认值 ); }方法体的组装最值得看：return this.name;在 AST 里是一个JCReturn，里面包着一个JCFieldAccess，它由「this标识符」和「字段名」组合而成。Lombok 不是写代码字符串，它在用 javac 自己的积木搭一颗和手写源码等价的语法树。搭完后defs.append(...)塞回类声明，对 javac 来说这颗树和 parse 出来的树没有任何区别，后续类型检查、重载决议、字节码生成照常执行——这就是整个编译期改写能成立的根基。3.3 为什么是改 AST，而不是改字节码同样在编译期动手脚，还有一条路是等.class生成后用 ASM 改字节码。Lombok 没选它，原因有三。第一，类型检查的时机：生成的方法必须参与编译器的重载决议和泛型推导，改字节码发生在类型检查之后，错误永远晚一步暴露；改 AST 是「先改树再编译」，语义最接近手写源码。第二，IDE 的增量编译器也是一套 javac，同样接受 AST 修改，所以 IDE 里的补全和报错都不会失真；字节码方案会绕过 IDE 静态分析，体验直接崩坏。第三，注解联动：@Getter生成的方法上有时要挂@Deprecated等注解，AST 阶段可以一并组装，字节码阶段再补救就太迟了。所以「改 AST」不是激进，是让生成物具备完整一等公民语义的唯一正解。4. 处理器分发与实现：从 @Getter 到字节码的完整链路4.1 HandlerLibrary：注解到处理器的映射表Lombok 的 jar 里塞了几十个处理器，各管各的注解。加载它们的容器叫HandlerLibrary，通过 SPI 扫描lombok.handlers.*包下所有处理器实现，每个实现类声明自己关心哪些注解。这份「注解 → 处理器 → 生成物」的映射决定了你写一个注解时背后发生什么：注解处理器生成物@Getter/@SetterHandleGetter / HandleSetter类里的方法节点@ToStringHandleToString重写的toString()@EqualsAndHashCodeHandleEqualsAndHashCode一对方法@BuilderHandleBuilder内部 builder 类 + 静态builder()@Slf4jHandleLog一个log字段声明process进入后，Lombok 先做「解析」（Resolution）。这不只是看注解字面量，还包括把@Getter(lazy = true)这类属性读出来、把字符串名字映射成符号表里的Name。解析必须「懒」——被注解引用的类型可能还没生成，要留到最后一刻才真正落到 AST 上。// 处理链骨架：真实类名与分工（简化示意） public final class LombokProcessor extends AbstractProcessor { private HandlerLibrary handlers; @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { Resolution r = JavacResolution.create(processingEnv, roundEnv); for (TypeElement annotation : annotations) { for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) { // 1. 找到对应 Handler，比如 @Getter -> HandleGetter Handler<?> handler = handlers.get(annotation.getQualifiedName()); // 2. 解析注解属性成符号/类型（懒解析，类可能还没生成） r.resolve(element); // 3. 从只读 Element 反查到 AST 节点，包装成 JavacNode JCTree tree = (JCTree) trees.getTree(element); JavacNode node = new JavacNode(tree, ...); handlers.handle(annotation, node); } } return false; // 不认领注解，允许别的处理器继续观察 } }最后一行return false是个细节：标准处理器返回true表示「这注解我认领了」，Lombok 故意返回false，因为它不想阻止其他框架同时观察同一个注解。这侧面说明它把自己定位成「并行改造者」，而不是注解的所有者。4.2 postRound 延迟：为什么改树要拖到最后一刻最容易被忽略也最关键的是时机。Lombok 不在process()里立刻改树，而是把所有要生成的节点装进队列，等一轮处理彻底结束（javac 的postRound回调）时统一画到 AST 上。原因有两个。第一，完整性。@Getter所在类的父类可能是另一个处理器在上一轮生成的，字段类型可能来自还没编译的新文件。第一轮就急着生成 getter，类型检查时那些符号还不存在，直接编译失败；拖到收尾，所有符号都沉淀完了，出错概率最小。第二，去重。如果边解析边改树，javac 可能因为新文件又开一轮，同一批注解再次被看到，getter 就生成两遍。集中到postRound只跑一次，天然避免重复。// 延迟执行结构（lombok.javac 包里的真实机制，简化示意） class JavacAST { private final List<Runnable> postRoundTasks = new ArrayList<>(); void deferUntilPostRound(Runnable task) { postRoundTasks.add(task); // 先记账，不立即执行 } void postRound() { for (Runnable task : postRoundTasks) task.run(); // 统一改树 postRoundTasks.clear(); } }这个「先收集、后执行」的模型，是 Lombok 与其他注解生成器最大的分野。你看到的所有@Data生成的一大坨方法，其实都是在同一个时间点、基于同一批解析结果批量写入 AST 的，所以它们之间不会出现「部分方法生成、部分没生成」的中间态。4.3 链路落地：一段 getter 的完整生平把前三节串起来，一个@Getter的生命周期是这样的：源码里class Foo { @Getter private String name; }被 javac 解析成JCCompilationUnit，注解处理引擎命中AnnotationProcessorHider；壳类加载真实处理器，透传JavacProcessingEnvironment；LombokProcessor.process找到HandleGetter，把name字段的 AST 节点包装成JavacNode，解析注解属性（确认没有lazy、没有AccessLevel.NONE），然后deferUntilPostRound排队；一轮结束后，HandleGetter用TreeMaker拼出public String getName(){ return this.name; }对应的JCMethodDecl，append进JCClassDecl.defs；javac 继续走类型检查和代码生成，getName进入方法表。验证这条链路不需要读源码，编译后直接反编译：# 编译后检查字节码方法表 javap -p target/classes/Foo.classclass Foo { private java.lang.String name; public Foo(); public java.lang.String getName(); # 源码里不存在，但字节码里有了 }javap -p列出所有方法（含私有和编译器生成的）。getName()出现在这里，就证明整条链路是「编译期改树 + 正常代码生成」的产物，而不是运行时任何魔法。这也顺带解释了一个常见困惑：为什么 Lombok 生成的代码在调试时看不到源码——因为它在.java里真的不存在，你看到的class文件本身就是唯一真相。5. 避坑：Lombok 与 JDK 迭代里的经典翻车现场Lombok 这类侵入式框架，翻车现场几乎都集中在 JDK 版本、处理器发现机制、注解联动三个维度。挑五条最有代表性的记录下来，每条都按「现象 → 原因 → 解决」讲透。5.1 换了 JDK 版本就编译失败现象：项目原本好好的，某天把本机 JDK 升到新大版本，构建工具一跑就抛java.lang.IllegalAccessError或NoSuchMethodError，报错位置通常在lombok.javac相关类里。原因：Lombok 直接访问com.sun.tools.javac.*，而 javac 的内部类结构和模块访问规则每个 JDK 版本都可能变。某个TreeMaker方法签名调整了，某个内部包不再允许反射，老版本 Lombok 当场崩。这是侵入式方案的必然代价，不是偶发 bug。解决：升级 Lombok 到与当前 JDK 匹配的新版本，并在构建配置里锁死 JDK 版本，保证 CI 和本地不出现大版本分叉；暂时升不了级的，宁可把 JDK 钉在旧版本，也别让两侧各用各的。5.2 构建工具里找不到 getter，IDE 却好好的现象：IDE 里编译、跳转、补全全部正常，但命令行构建一跑就报「找不到符号getName()」。原因：IDE 的增量编译器内置了一套 javac，默认扫描 classpath 上的注解处理器；而新版 JDK（从 23 开始）的命令行javac默认不再隐式发现 classpath 上的处理器。没有显式声明处理器路径时，Lombok 压根没被加载，IDE 与命令行走的是两套不同的发现逻辑。解决：在构建配置里显式声明 Lombok 的处理器依赖并开启完整处理模式；用裸javac验证时显式传入-proc:full -processor lombok.launch.AnnotationProcessorHider$AnnotationProcessor，先确认「处理器到底跑没跑」，再谈代码问题。5.3 自定义处理器读不到 Lombok 生成的方法现象：自己写了一个注解处理器，想读@Data类里的 getter 做二次生成，结果Element里翻遍只有源码里写过的字段和方法。原因：Lombok 改的是 javac 的 AST，没有生成新文件，也不会触发新的处理轮次。按 JSR 269 标准语义，你的处理器只能看到「源码和已生成文件里真实存在」的符号，AST 被改过不会同步进其他处理器的符号视图。这不是缺陷，是工作方式决定的。解决：需要消费 Lombok 生成结果的下游处理不能放在同一编译流程里。先delombok展开成真实源码，再把自己的处理器挂到第二次编译上，两个阶段解耦。5.4@Data与@Builder联用把无参构造搞没了现象：一个类同时标了@Data和@Builder，之前所有new Foo()的调用点全部编译失败。原因：@Builder会生成一个全参构造器供 builder 灌值，而@Data期望类里有无参构造兜底（主要是序列化框架要用）。两个注解各自为政，叠加之后全参有了、无参没了。解决：显式补上@NoArgsConstructor和@AllArgsConstructor，把构造器策略完全握在自己手里；类里已有手写构造器时同理。处理这类问题的一个通用思路是：把隐式行为显式化，不确定性立刻消失。5.5 delombok 辅助排查的通用姿势现象：怀疑某个生成规则不对，比如@Getter(lazy = true)生成的字段命名和预期不符，盯着 class 文件反编译也绕晕。原因：lazy的处理会引入额外字段和判空逻辑，AST 生成物经过字节码编译后已经变形，直接看产物很难反推生成规则。解决：用 Lombok 自带的delombok工具把注解展开成普通 Java 文件：java -jar lombok.jar delombok src -d delomboked-out。执行后@Getter变成真实的getX()，@Builder展开成完整的内部类。拿「期望写法」和「展开结果」对拍，一眼就能看出是处理器没跑、版本不匹配，还是生成逻辑本身的问题。这套姿势同样适用于前四条，先展开再定位，永远比对着报错信息猜快。6. 设计取舍：用编译器私有 API 换开发体验，这笔账怎么算Lombok 的设计取舍本质上是一道选择题：要「源码极简」的开发体验，就得绑定 javac 私有 API；要「跨版本稳如老狗」的兼容性，就得放弃@Data这类注解。二者不可能兼得，因为 JSR 269 的稳定公共 API 天生不支持修改已有类型。Lombok 选择押注前者，把兼容性风险转嫁给发布节奏：每次 JDK 新版本预览出来，作者团队就要适配内部类变动。这也是社区里一直有人呼吁「把 Lombok 功能收进 JDK」却始终没成型的核心原因——收进去意味着编译器团队要维护一套稳定的 AST 修改契约，成本远高于单点适配。作为使用方，这笔账怎么算才不亏？我给自己定了三条硬规矩。第一，把 Lombok 版本与 JDK 版本写成显式约束，放进构建配置，禁止「CI 一套版本、本机一套版本」。第二，对生成代码有强校验的场景，用javap -p查验方法表，必要时把delombok展开后的源码提交进仓库，让魔法变成可 review 的普通代码。第三，自己写注解处理器时，默认走标准 JSR 269 生成新文件；只有生成物必须嵌进原有类型时，才去碰com.sun.tools.javac，而且要清醒知道这条路没有兼容性承诺。如果手上拿到的是这份资源的源码包，建议先在本地把示例工程编译一遍，用javap和delombok两条命令把生成代码摊开，再回去对照lombok.javac包里的处理器实现逐行读，效果远好于只看结论。从那以后，我每次遇到「编译期魔法」类的诡异报错，第一件事永远是先javap -p看 class 文件的方法表——确认代码到底生成没有，再谈是版本问题、处理器没跑还是生成逻辑不对。这个习惯帮我筛掉了至少一半的无效排查，希望帮到你。本文还有配套的精品资源，点击获取
简介：围绕 Lombok 注解处理器与编译期字节码操作的代码资源，面向具备 Java 基础的后端开发者，旨在讲清 Lombok 如何借助编译阶段的注解处理能力，自动生成 getter、setter、构造器、equals、hashCode 等样板代码，并提示使用边界与常见兼容性问题。压缩包共 40 个文件，大小约 88KB，以 Java 源文件、class 字节码、XML 配置和 JAR 依赖为主，另有 bpmn、dmn 等流程与规则示例文件，覆盖从注解定义、处理器实现到 IDE 插件协作的完整实验路径；工程采用多模块结构，便于按功能拆分阅读。已有 665 人学习下载，适合希望掌握 Lombok 内部机制或自行扩展自定义注解处理器的开发者。通过实际运行代码，可直观对照源码与生成后的字节码，理解 ASM 库在编译期间插入方法的具体时机，也能看到自定义注解处理器的扩展写法，为排查第三方库兼容性问题提供实践参考。1. Lombok：一个在编译期「改写源码」的黑客式注解处理器很多开发者第一次接触 Lombok 时，会以为@Getter是 IDE 补全出来的，或是运行时的反射魔法。真相恰好相反：你的.java源文件里从未存在过getName()，但.class文件里确实有它——它是 javac 编译到一半时，被一个跑在注解处理器队列里的程序，直接往编译器内部语法树上画上去的。无论把 lombok 软件/插件装成 IDE 组件还是构建依赖，它的执行位置都只有一个：javac 的注解处理引擎。弄懂它怎么进编译器、为什么能改树，你在 JDK 升级翻车、构建找不到 getter 这类问题上，就能一眼定位根源，而不是靠换版本碰运气。2. 注解处理的边界：为什么标准 API 只能「新增」而不能「修改」2.1 JSR 269 的轮次模型：编译被拆成了多轮问答javac 的注解处理机制来自 JSR 269（Java Annotation Processing），它本质上是在编译流程中间插入了一个「多轮问答」循环。每一轮，javac 把当前可见的注解交给对应处理器；处理器可以读注解所在元素的信息，也可以通过Filer生成新的.java或.class文件。只要这一轮有新的文件产生，javac 就再开一轮，直到某一轮没有任何新文件产出，进入最后一轮（last round），处理引擎退出，编译继续走类型检查和字节码生成。轮次javac 做什么处理器能做第 1 轮解析源码，收集注解读取符号、生成新文件第 N 轮编译新文件，再次收集注解继续读取、继续生成最后一轮没有新文件了收尾清理，随后退出关键点在于处理器手里的输入：Elements（只读符号模型）和RoundEnvironment（当轮环境）。你可以问「这个类有哪些字段、字段类型是什么」，但没有一条 API 能回答「给这个类加一个方法」。这不是 API 设计疏漏，而是刻意划定的边界：编译单元的所有权归编译器，处理器只是旁路观察者，只能往旁边「新增」，不能回头「修改」已有的树。// 一个符合 JSR 269 的处理器：只能生成新文件，不能改已有类 public final class GenProcessor extends AbstractProcessor { @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { for (TypeElement annotation : annotations) { for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) { // element 是编译单元里的类/字段/方法 // 能读它的修饰符、名字、类型，但无法往它的方法列表里塞东西 // 想产出代码只能走 Filer： // Filer filer = processingEnv.getFiler(); // filer.createSourceFile("com.example.Generated"); } } return true; // 声明本轮注解已被自己消费 } }这段代码里，roundEnv.getElementsAnnotatedWith(annotation)返回的元素对读取完全开放，但任何「写入现有类型」的操作都没有对应 API。Filer创建的新文件还会受「类型重复」约束——如果你生成一个与已有类同名的类，会直接编译报错。所以标准注解处理的世界观是「增量」的：你可以基于现有代码生成新类型，但永远无法回到现有类型内部去改造它。2.2 为什么「生成新类」或「运行时增强」都救不了 Lombok顺着这个边界往下想，Lombok 似乎有三条路可以绕。第一条是「生成一个平行的类」，比如FooGetter，把 getter 都放在里面——这毫无意义，调用方写的是foo.getName()，没人会去实例化一个平行的工具类。第二条是「改继承结构」，让Foo继承一个带 getter 的基类——这会破坏原有类型语义，Java 单继承也经不起这么折腾。第三条是运行时字节码增强（ASM 或动态代理），但那只对通过代理创建的实例生效，直接new Foo()走的是原始字节码，方法表里没有就是没有，反射也救不回来。所以摆在 Lombok 面前的路只剩一条：修改 javac 自己持有的那棵 AST。JSR 269 确实给了处理器一个看见 AST 的窗口——Trees.instance(processingEnv)之后可以调用getTree(element)——但com.sun.source.tree是只读接口，写操作没有承诺。真正的修改能力藏在 javac 的实现类里：com.sun.tools.javac.tree.JCTree的节点类暴露了公开字段，比如JCClassDecl.defs就是类的成员声明列表，谁拿到这个字段，谁就能改树。Lombok 选择的就是这条路：放弃稳定 API，直接操作编译器内部实现。这也是它此后一切兼容性问题的总根源。提示：判断一个注解处理框架是「标准派」还是「Lombok 派」，只看它是否依赖com.sun.tools.javac就够。标准派只碰javax.annotation.processing.*和javax.lang.model.*，而 Lombok 的核心逻辑几乎全在lombok.javac包底下。3. 侵入式改造：Lombok 怎么混进 javac 并改写 AST3.1 入口伪装：AnnotationProcessorHider 与自研类加载器先从入口看。Lombok 的 jar 里，META-INF/services/javax.annotation.processing.Processor指向的不是大家以为的lombok.core.AnnotationProcessor，而是一个叫lombok.launch.AnnotationProcessorHider$AnnotationProcessor的壳类。为什么套壳？因为 javac 的注解处理引擎用标准ServiceLoader发现处理器，壳类必须能被系统类加载器加载；但 Lombok 真正要访问的com.sun.tools.javac.*内部类，在 JDK 9 引入模块系统后默认不对外导出。如果让真实处理器直接挂在系统类加载器下，一碰JCTree就会抛IllegalAccessError。壳类的破解办法是「自己加载自己」：它内部实现了一个ShadowClassLoader，把lombok.core底下的真实处理器重新加载一遍。这个加载器的关键动作是绕过模块边界的访问检查——在较新的 JDK 上，常见做法是借道sun.misc.Unsafe打开jdk.compiler模块内部包的访问权限，再在内存里直接定义lombok.javac.*的类。这样真实处理器所在的类加载域与 javac 内部类一致，私有字段随便碰。这也是为什么每次 JDK 大版本更新，Lombok 都要跟着发新版——内部模块的访问规则一变，撬锁姿势就得跟着换。// 壳类的高度简化示意（真实实现比这复杂得多） public final class AnnotationProcessorHider { public static class AnnotationProcessor extends AbstractProcessor { private final Processor realProcessor; public AnnotationProcessor() { // 用自研加载器绕过模块边界，加载 lombok.core 里的真正实现 ClassLoader shadow = ShadowClassLoader.create(getClass().getClassLoader()); this.realProcessor = newInstance(shadow, "lombok.core.AnnotationProcessor"); } @Override public void init(ProcessingEnvironment env) { realProcessor.init(env); // 把 javac 给的编译环境透传进去 } @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { return realProcessor.process(annotations, roundEnv); // 真正干活 } } }注意init(ProcessingEnvironment env)透传的这个env：在 javac 里它的实现类是JavacProcessingEnvironment。真实处理器拿到它之后，会从里面挖出Context——javac 的全局上下文对象，类似一个内部 IOC 容器——再从Context提出TreeMaker、Names、Symtab这些核心服务。整个入侵的起点就是这个Context：拿到它，等于拿到了编译器全部内部依赖的钥匙串。3.2 JavacAST 与 TreeMaker：给编译器准备的语法树手术台拿到Context之后，Lombok 的工作可以概括成三句话：把编译单元包成自己的树结构、定位要改的节点、用TreeMaker造出新节点并塞进父节点的成员列表。javac 的 AST 长这样：一个编译单元对应JCCompilationUnit，下面挂JCClassDecl（类声明），类声明里有个公开字段defs，里面装着JCVariableDecl（字段）、JCMethodDecl（方法）等成员节点。所谓「加一个 getter」，本质就是往JCClassDecl.defs这个List<JCTree>末尾append一个新拼出来的JCMethodDecl。拼装不是靠写字符串再 parse，而是用TreeMaker这个语法树工厂一个个参数构造：// 用 javac 内部 TreeMaker 组装 getter 的简化示意 TreeMaker make = TreeMaker.instance(context); // javac 的语法树工厂 Names names = Names.instance(context); // 符号名表 JCMethodDecl buildGetter(JCVariableDecl field) { return make.MethodDef( make.Modifiers(Flags.PUBLIC), // public names.fromString("get" + capitalize(field.name)), // getName make.Type(field.type), // 返回类型 = 字段类型 List.nil(), // 泛型参数 List.nil(), // 形参列表 List.nil(), // 抛出异常列表 make.Block(0, List.of( make.Return( make.Select(make.Ident(names.fromString("this")), field.name)))), // return this.name; null // 默认值 ); }方法体的组装最值得看：return this.name;在 AST 里是一个JCReturn，里面包着一个JCFieldAccess，它由「this标识符」和「字段名」组合而成。Lombok 不是写代码字符串，它在用 javac 自己的积木搭一颗和手写源码等价的语法树。搭完后defs.append(...)塞回类声明，对 javac 来说这颗树和 parse 出来的树没有任何区别，后续类型检查、重载决议、字节码生成照常执行——这就是整个编译期改写能成立的根基。3.3 为什么是改 AST，而不是改字节码同样在编译期动手脚，还有一条路是等.class生成后用 ASM 改字节码。Lombok 没选它，原因有三。第一，类型检查的时机：生成的方法必须参与编译器的重载决议和泛型推导，改字节码发生在类型检查之后，错误永远晚一步暴露；改 AST 是「先改树再编译」，语义最接近手写源码。第二，IDE 的增量编译器也是一套 javac，同样接受 AST 修改，所以 IDE 里的补全和报错都不会失真；字节码方案会绕过 IDE 静态分析，体验直接崩坏。第三，注解联动：@Getter生成的方法上有时要挂@Deprecated等注解，AST 阶段可以一并组装，字节码阶段再补救就太迟了。所以「改 AST」不是激进，是让生成物具备完整一等公民语义的唯一正解。4. 处理器分发与实现：从 @Getter 到字节码的完整链路4.1 HandlerLibrary：注解到处理器的映射表Lombok 的 jar 里塞了几十个处理器，各管各的注解。加载它们的容器叫HandlerLibrary，通过 SPI 扫描lombok.handlers.*包下所有处理器实现，每个实现类声明自己关心哪些注解。这份「注解 → 处理器 → 生成物」的映射决定了你写一个注解时背后发生什么：注解处理器生成物@Getter/@SetterHandleGetter / HandleSetter类里的方法节点@ToStringHandleToString重写的toString()@EqualsAndHashCodeHandleEqualsAndHashCode一对方法@BuilderHandleBuilder内部 builder 类 + 静态builder()@Slf4jHandleLog一个log字段声明process进入后，Lombok 先做「解析」（Resolution）。这不只是看注解字面量，还包括把@Getter(lazy = true)这类属性读出来、把字符串名字映射成符号表里的Name。解析必须「懒」——被注解引用的类型可能还没生成，要留到最后一刻才真正落到 AST 上。// 处理链骨架：真实类名与分工（简化示意） public final class LombokProcessor extends AbstractProcessor { private HandlerLibrary handlers; @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) { Resolution r = JavacResolution.create(processingEnv, roundEnv); for (TypeElement annotation : annotations) { for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) { // 1. 找到对应 Handler，比如 @Getter -> HandleGetter Handler<?> handler = handlers.get(annotation.getQualifiedName()); // 2. 解析注解属性成符号/类型（懒解析，类可能还没生成） r.resolve(element); // 3. 从只读 Element 反查到 AST 节点，包装成 JavacNode JCTree tree = (JCTree) trees.getTree(element); JavacNode node = new JavacNode(tree, ...); handlers.handle(annotation, node); } } return false; // 不认领注解，允许别的处理器继续观察 } }最后一行return false是个细节：标准处理器返回true表示「这注解我认领了」，Lombok 故意返回false，因为它不想阻止其他框架同时观察同一个注解。这侧面说明它把自己定位成「并行改造者」，而不是注解的所有者。4.2 postRound 延迟：为什么改树要拖到最后一刻最容易被忽略也最关键的是时机。Lombok 不在process()里立刻改树，而是把所有要生成的节点装进队列，等一轮处理彻底结束（javac 的postRound回调）时统一画到 AST 上。原因有两个。第一，完整性。@Getter所在类的父类可能是另一个处理器在上一轮生成的，字段类型可能来自还没编译的新文件。第一轮就急着生成 getter，类型检查时那些符号还不存在，直接编译失败；拖到收尾，所有符号都沉淀完了，出错概率最小。第二，去重。如果边解析边改树，javac 可能因为新文件又开一轮，同一批注解再次被看到，getter 就生成两遍。集中到postRound只跑一次，天然避免重复。// 延迟执行结构（lombok.javac 包里的真实机制，简化示意） class JavacAST { private final List<Runnable> postRoundTasks = new ArrayList<>(); void deferUntilPostRound(Runnable task) { postRoundTasks.add(task); // 先记账，不立即执行 } void postRound() { for (Runnable task : postRoundTasks) task.run(); // 统一改树 postRoundTasks.clear(); } }这个「先收集、后执行」的模型，是 Lombok 与其他注解生成器最大的分野。你看到的所有@Data生成的一大坨方法，其实都是在同一个时间点、基于同一批解析结果批量写入 AST 的，所以它们之间不会出现「部分方法生成、部分没生成」的中间态。4.3 链路落地：一段 getter 的完整生平把前三节串起来，一个@Getter的生命周期是这样的：源码里class Foo { @Getter private String name; }被 javac 解析成JCCompilationUnit，注解处理引擎命中AnnotationProcessorHider；壳类加载真实处理器，透传JavacProcessingEnvironment；LombokProcessor.process找到HandleGetter，把name字段的 AST 节点包装成JavacNode，解析注解属性（确认没有lazy、没有AccessLevel.NONE），然后deferUntilPostRound排队；一轮结束后，HandleGetter用TreeMaker拼出public String getName(){ return this.name; }对应的JCMethodDecl，append进JCClassDecl.defs；javac 继续走类型检查和代码生成，getName进入方法表。验证这条链路不需要读源码，编译后直接反编译：# 编译后检查字节码方法表 javap -p target/classes/Foo.classclass Foo { private java.lang.String name; public Foo(); public java.lang.String getName(); # 源码里不存在，但字节码里有了 }javap -p列出所有方法（含私有和编译器生成的）。getName()出现在这里，就证明整条链路是「编译期改树 + 正常代码生成」的产物，而不是运行时任何魔法。这也顺带解释了一个常见困惑：为什么 Lombok 生成的代码在调试时看不到源码——因为它在.java里真的不存在，你看到的class文件本身就是唯一真相。5. 避坑：Lombok 与 JDK 迭代里的经典翻车现场Lombok 这类侵入式框架，翻车现场几乎都集中在 JDK 版本、处理器发现机制、注解联动三个维度。挑五条最有代表性的记录下来，每条都按「现象 → 原因 → 解决」讲透。5.1 换了 JDK 版本就编译失败现象：项目原本好好的，某天把本机 JDK 升到新大版本，构建工具一跑就抛java.lang.IllegalAccessError或NoSuchMethodError，报错位置通常在lombok.javac相关类里。原因：Lombok 直接访问com.sun.tools.javac.*，而 javac 的内部类结构和模块访问规则每个 JDK 版本都可能变。某个TreeMaker方法签名调整了，某个内部包不再允许反射，老版本 Lombok 当场崩。这是侵入式方案的必然代价，不是偶发 bug。解决：升级 Lombok 到与当前 JDK 匹配的新版本，并在构建配置里锁死 JDK 版本，保证 CI 和本地不出现大版本分叉；暂时升不了级的，宁可把 JDK 钉在旧版本，也别让两侧各用各的。5.2 构建工具里找不到 getter，IDE 却好好的现象：IDE 里编译、跳转、补全全部正常，但命令行构建一跑就报「找不到符号getName()」。原因：IDE 的增量编译器内置了一套 javac，默认扫描 classpath 上的注解处理器；而新版 JDK（从 23 开始）的命令行javac默认不再隐式发现 classpath 上的处理器。没有显式声明处理器路径时，Lombok 压根没被加载，IDE 与命令行走的是两套不同的发现逻辑。解决：在构建配置里显式声明 Lombok 的处理器依赖并开启完整处理模式；用裸javac验证时显式传入-proc:full -processor lombok.launch.AnnotationProcessorHider$AnnotationProcessor，先确认「处理器到底跑没跑」，再谈代码问题。5.3 自定义处理器读不到 Lombok 生成的方法现象：自己写了一个注解处理器，想读@Data类里的 getter 做二次生成，结果Element里翻遍只有源码里写过的字段和方法。原因：Lombok 改的是 javac 的 AST，没有生成新文件，也不会触发新的处理轮次。按 JSR 269 标准语义，你的处理器只能看到「源码和已生成文件里真实存在」的符号，AST 被改过不会同步进其他处理器的符号视图。这不是缺陷，是工作方式决定的。解决：需要消费 Lombok 生成结果的下游处理不能放在同一编译流程里。先delombok展开成真实源码，再把自己的处理器挂到第二次编译上，两个阶段解耦。5.4@Data与@Builder联用把无参构造搞没了现象：一个类同时标了@Data和@Builder，之前所有new Foo()的调用点全部编译失败。原因：@Builder会生成一个全参构造器供 builder 灌值，而@Data期望类里有无参构造兜底（主要是序列化框架要用）。两个注解各自为政，叠加之后全参有了、无参没了。解决：显式补上@NoArgsConstructor和@AllArgsConstructor，把构造器策略完全握在自己手里；类里已有手写构造器时同理。处理这类问题的一个通用思路是：把隐式行为显式化，不确定性立刻消失。5.5 delombok 辅助排查的通用姿势现象：怀疑某个生成规则不对，比如@Getter(lazy = true)生成的字段命名和预期不符，盯着 class 文件反编译也绕晕。原因：lazy的处理会引入额外字段和判空逻辑，AST 生成物经过字节码编译后已经变形，直接看产物很难反推生成规则。解决：用 Lombok 自带的delombok工具把注解展开成普通 Java 文件：java -jar lombok.jar delombok src -d delomboked-out。执行后@Getter变成真实的getX()，@Builder展开成完整的内部类。拿「期望写法」和「展开结果」对拍，一眼就能看出是处理器没跑、版本不匹配，还是生成逻辑本身的问题。这套姿势同样适用于前四条，先展开再定位，永远比对着报错信息猜快。6. 设计取舍：用编译器私有 API 换开发体验，这笔账怎么算Lombok 的设计取舍本质上是一道选择题：要「源码极简」的开发体验，就得绑定 javac 私有 API；要「跨版本稳如老狗」的兼容性，就得放弃@Data这类注解。二者不可能兼得，因为 JSR 269 的稳定公共 API 天生不支持修改已有类型。Lombok 选择押注前者，把兼容性风险转嫁给发布节奏：每次 JDK 新版本预览出来，作者团队就要适配内部类变动。这也是社区里一直有人呼吁「把 Lombok 功能收进 JDK」却始终没成型的核心原因——收进去意味着编译器团队要维护一套稳定的 AST 修改契约，成本远高于单点适配。作为使用方，这笔账怎么算才不亏？我给自己定了三条硬规矩。第一，把 Lombok 版本与 JDK 版本写成显式约束，放进构建配置，禁止「CI 一套版本、本机一套版本」。第二，对生成代码有强校验的场景，用javap -p查验方法表，必要时把delombok展开后的源码提交进仓库，让魔法变成可 review 的普通代码。第三，自己写注解处理器时，默认走标准 JSR 269 生成新文件；只有生成物必须嵌进原有类型时，才去碰com.sun.tools.javac，而且要清醒知道这条路没有兼容性承诺。如果手上拿到的是这份资源的源码包，建议先在本地把示例工程编译一遍，用javap和delombok两条命令把生成代码摊开，再回去对照lombok.javac包里的处理器实现逐行读，效果远好于只看结论。从那以后，我每次遇到「编译期魔法」类的诡异报错，第一件事永远是先javap -p看 class 文件的方法表——确认代码到底生成没有，再谈是版本问题、处理器没跑还是生成逻辑不对。这个习惯帮我筛掉了至少一半的无效排查，希望帮到你。本文还有配套的精品资源，点击获取