你写 @Data 就白得一堆 getter；写一个接口，MapStruct 就帮你生成实现类；写 @Inject，Dagger 就把依赖关系连好——这些代码你从来没写过，但它们确实存在于最终产物里。干这件事的技术就是注解处理器（APT）。这一章带你手写一个能跑的处理器，并讲清 Java/Kotlin 世界里 APT、kapt、KSP 三条路线的关系，以及 JDK 23 那个让 Lombok 集体"静默失效"的变更。

注解处理器是什么：编译期生成代码的另一条路

是什么：注解处理器是 javac 在编译过程中回调的一类插件。它实现 javax.annotation.processing.Processor（通常继承 AbstractProcessor），能读到源码里的类型和注解信息，也能写出新的 .java 源文件让编译器继续编译。

为什么值得学：它和"运行时反射"是解决同一类问题的两条路，而 APT 在三个维度上更优：

怎么用：一个处理器的最小组成只有三部分：① 一个注解、② 一个 Processor 实现类、③ 一个注册文件（告诉 javac 去哪找这个处理器）。下一节我们把它完整写出来。

手写一个能跑的注解处理器

是什么：我们要实现的功能很简单：给一个类标注 @GenerateInfo("xxx")，处理器自动生成一个 类名Info.java，里面带上类名和注解里的字符串。麻雀虽小，但 APT 的全部关键机制都在里面。

① 定义注解：注意 RetentionPolicy.SOURCE

// src/com/example/apt/GenerateInfo.java
package com.example.apt;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * SOURCE 策略：注解只存在于源码，不进 class 文件。
 * 既然代码在编译期就生成好了，运行时没必要再带着这个注解。
 */
@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface GenerateInfo {
    String value();
}

② 处理器实现：读注解 → 用 Filer 生成源码

// src/com/example/apt/InfoProcessor.java
package com.example.apt;

import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.Filer;
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.TypeElement;
import javax.tools.Diagnostic;
import java.io.IOException;
import java.io.Writer;
import java.util.Set;

// 声明"我处理哪个注解"和"我支持到哪个源码版本"（后者不写会有编译警告）
@SupportedAnnotationTypes("com.example.apt.GenerateInfo")
@SupportedSourceVersion(SourceVersion.RELEASE_21)
public class InfoProcessor extends AbstractProcessor {

    @Override
    public boolean process(Set<? extends TypeElement> annotations,
                              RoundEnvironment roundEnv) {
        // 取出所有被 @GenerateInfo 标注的元素（这里限定只能标在类上，所以就是类）
        for (Element e : roundEnv.getElementsAnnotatedWith(GenerateInfo.class)) {
            TypeElement type = (TypeElement) e;
            GenerateInfo ann = type.getAnnotation(GenerateInfo.class);

            String pkg = processingEnv.getElementUtils()
                    .getPackageOf(type).getQualifiedName().toString();
            String simple = type.getSimpleName().toString();
            String genName = simple + "Info";

            // 用 Filer 创建源文件；第二个参数是"由谁引发的生成"，用于报错定位
            Filer filer = processingEnv.getFiler();
            try (Writer w = filer
                    .createSourceFile(pkg + "." + genName, type)
                    .openWriter()) {
                w.write("package " + pkg + ";\n\n");
                w.write("/** 由 InfoProcessor 自动生成，请勿手工修改。 */\n");
                w.write("public final class " + genName + " {\n");
                w.write("    public static final String NAME = \"" + simple + "\";\n");
                w.write("    public static final String VALUE = \"" + ann.value() + "\";\n");
                w.write("    private " + genName + "() {}\n");
                w.write("}\n");
            } catch (IOException ex) {
                // 关键：处理器里"报错"要用 Messager，它会把错误挂到对应的源码元素上
                processingEnv.getMessager().printMessage(
                        Diagnostic.Kind.ERROR,
                        "生成 " + genName + " 失败：" + ex.getMessage(), type);
            }
        }
        return true;   // 认领这些注解：别的处理器就不用再看它们了
    }
}

③ 注册处理器：在 META-INF/services 里写一行

# 文件路径（必须是这个全名，javac 按 Java 的 SPI 规则来查找）
# src/META-INF/services/javax.annotation.processing.Processor

# 文件内容就一行：处理器的全限定类名
com.example.apt.InfoProcessor

# 进阶：项目里处理器多了之后，这个文件要手工维护很烦，
# 可以用 Google 的 @AutoService(Processor.class) 让它自动生成这一行。

④ 使用它：App.java 里直接用还没生成的 AppInfo

// src/com/example/apt/App.java
package com.example.apt;

@GenerateInfo("hello apt")
public class App {
    public static void main(String[] args) {
        // AppInfo 此刻还不存在，是处理器在编译过程中"变"出来的
        System.out.println(AppInfo.NAME + " -> " + AppInfo.VALUE);
    }
}

⑤ 编译与运行：注意"先编处理器、再用处理器编业务代码"这个顺序

# 第 1 步：把"注解 + 处理器"编出来，编它的时候不需要跑处理器（-proc:none）
javac -d processor-out -proc:none \
      src/com/example/apt/GenerateInfo.java \
      src/com/example/apt/InfoProcessor.java
cp -r src/META-INF processor-out/

# 第 2 步：用刚才的处理器编译业务代码
#   -processorpath  处理器自己的 jar/目录（不要混进业务类路径）
#   -s gen          生成出来的 .java 源码放哪（想看生成结果就靠它）
javac -d app-out -s gen -processorpath processor-out src/com/example/apt/App.java

# 第 3 步：看看它到底生成了什么 -- 这一步非常重要，别把生成代码当黑盒
cat gen/com/example/apt/AppInfo.java
#   package com.example.apt;
#   /** 由 InfoProcessor 自动生成，请勿手工修改。 */
#   public final class AppInfo {
#       public static final String NAME = "App";
#       public static final String VALUE = "hello apt";
#       private AppInfo() {}
#   }

# 第 4 步：运行
java -cp app-out com.example.apt.App
# 输出：App -> hello apt

# ── 三个排查用的开关 ──
javac -XprintRounds ...        # 打印每一轮处理了哪些注解（看懂"轮次"必用）
javac -XprintProcessorInfo ... # 打印是哪个处理器在处理哪个注解
javac -proc:only ...           # 只跑处理器、不编译业务代码

处理轮次与 Element API：处理器的"世界观"

是什么：注解处理不是"一轮跑完"，而是循环多轮：第一轮处理原始源码 → 如果生成了新源文件 → 新文件进入第二轮 → 以此类推，直到某一轮没有新文件产生，最后再调用一次 process，此时 roundEnv.processingOver() 返回 true。

为什么必须理解轮次：因为一个非常常见的 bug 就在这里：你在第一轮里想"收集所有被标注的类，然后统一生成一个汇总类"——但第一轮时你只看到了原始源码里的那些类，由其他处理器生成的类还没出现。正确做法是：每轮都收集到自己的集合里，等到 processingOver() 为真时的最后一轮再生成汇总文件。

JDK 23 那个变更：为什么处理器会"静默失效"

是什么：从 2006 年引入注解处理开始，javac 一直默认会把类路径上发现的处理器全都跑一遍。从 JDK 23 起，这个默认行为被改掉了：如果没有显式提供 -processor、--processor-path 或 --processor-module-path 中的任何一个，注解处理就不会执行（需要显式写 -proc:full 才能恢复旧行为）。JDK 21 和 22 只是先打印一条提醒，作为过渡。

为什么这是一件大事：因为大量项目其实一直"依赖巧合"在工作——classpath 里恰好有 Lombok 的 jar，于是处理器被隐式发现并执行了。升级到 JDK 23 后，这种"巧合"消失，报错却是"找不到符号"这种完全指不到根因的形式（因为生成的代码不再产生，而你的源码里引用了它们）。

症状与解法

# ── 症状：一堆"找不到符号"，但代码明明没动过 ──
# App.java:12: 错误: 找不到符号
#     System.out.println(AppInfo.NAME);
#                              ^
#   符号:   变量 AppInfo
# ── 而且不会提示"注解处理器没跑"，这才是最坑的地方 ──

# ── 用 -Xlint:processing 也看不到处理器的信息，正好说明"根本没进注解处理流程" ──
javac -Xlint:processing -cp lombok.jar -d out App.java

# ── 解法一：显式指定处理器路径（推荐，规范做法） ──
javac -processorpath libs/lombok.jar -d out src/com/example/App.java

# ── 解法二：显式声明"我要完整的注解处理"（快速恢复旧行为） ──
javac -proc:full -cp libs/lombok.jar -d out src/com/example/App.java
#   注意：-proc:full 已被向后移植到 JDK 8u / 11u / 17u，老项目可以提前加上做适配

# ── 想彻底关掉注解处理（比如编译一个明确不需要处理器的模块）： ──
javac -proc:none -d out src/com/example/App.java

官方为什么要这么改：因为"类路径上任何一个 jar 只要在 META-INF/services 里注册了处理器，就可以在编译期执行任意代码"——在依赖动辄几百个 jar 的今天，这等于给供应链攻击开了一扇门。改成显式声明之后，构建行为变得可审计、可预测，这本身是件好事。

APT / kapt / KSP：三条路线的取舍

是什么：Java 的注解处理机制（APT）在 Kotlin 时代遇到了麻烦——Kotlin 编译器不是 javac，它不认 javax.annotation.processing 那套。于是社区先后出现了两条路：kapt（把 Kotlin 代码变成 Java 存根，再交给 javac 跑 APT）和 KSP（Kotlin 自己的符号处理 API）。

在构建脚本里怎么声明（Gradle Kotlin DSL）

// ── 纯 Java 项目：就是普通的 annotationProcessor 配置 ──
dependencies {
    compileOnly("org.projectlombok:lombok:1.18.34")        // 注解本身：编译期需要
    annotationProcessor("org.projectlombok:lombok:1.18.34") // 处理器：只在编译期跑
}

// ── Kotlin 项目用 kapt（老方式） ──
// plugins { kotlin("kapt") }
// dependencies { kapt("com.example:my-processor:1.0") }

// ── Kotlin 项目用 KSP（推荐） ──
// plugins { id("com.google.devtools.ksp") version "<Kotlin 版本>-<KSP 版本>" }
//   KSP 的版本号跟 Kotlin 版本绑定，形如 2.1.0-1.0.29，升级 Kotlin 时要一起升
// dependencies { ksp("com.example:my-processor:1.0") }
//   KSP 生成的代码默认在 build/generated/ksp/... 需要的话把它加进源码集：
// kotlin.sourceSets.main { kotlin.srcDir("build/generated/ksp/main/kotlin") }

生态全景：这些你天天用的库，背后都是注解处理器