Java APT（Annotation Processing Tool）是一种在 Java 编译阶段处理注解的工具。APT 会在编译阶段扫描源代码中的注解，并根据这些注解生成代码、资源文件或其他输出，从而实现代码自动生成、配置生成、校验逻辑等功能。

一、APT 是什么？

APT 全称是 Annotation Processing Tool，它是 Java 编译器的一部分，用于在编译阶段处理注解（Annotations）。APT 允许开发者编写自定义的注解处理器（Annotation Processor），并在编译期间根据注解生成额外的代码或资源。

1.1 注解处理的生命周期

APT 的工作发生在编译阶段，具体是在 javac 编译 .java 文件为 .class 文件之前。在这个阶段，注解处理器可以：

• 扫描和处理源码中的注解；
• 生成新的 Java 源文件（.java）或资源文件；
• 修改已有的代码（不推荐，通常通过生成代码来替代）。

二、APT 的核心组件

2.1 注解（Annotation）

Java 注解是一种元数据形式，可以添加到类、方法、字段等元素上。例如：

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.TYPE)
public @interface MyAnnotation {
}

2.2 注解处理器（Annotation Processor）

需要编写一个类实现 javax.annotation.processing.Processor 接口，或者继承 AbstractProcessor 类。

@SupportedAnnotationTypes("com.example.MyAnnotation")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class MyAnnotationProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (TypeElement annotation : annotations) {
            Set<? extends Element> elements = roundEnv.getElementsAnnotatedWith(annotation);
            for (Element element : elements) {
                // 处理被注解的类、方法等
                System.out.println("Found annotated element: " + element);
                // 生成代码
                generateCode(element);
            }
        }
        return true;
    }

    private void generateCode(Element element) {
        // 使用 JavaPoet 或手动拼接生成 Java 源文件
    }
}

2.3 注册处理器

可以在 resources/META-INF/services/javax.annotation.processing.Processor 文件中注册你的处理器：

com.example.MyAnnotationProcessor

三、APT 的使用场景

APT 常用于以下场景：

四、APT 的优缺点

优点：

• 提升开发效率：自动生成重复代码；
• 减少运行时开销：处理在编译期完成，不影响运行时性能；
• 编译期检查：可以在编译时进行类型安全检查；
• 与 IDE 集成良好。

缺点：

• 学习曲线陡峭：需要理解注解、处理器、代码生成等机制；
• 调试困难：APT 错误信息可能不直观；
• 生成代码维护困难：如果生成代码结构复杂，调试和维护成本高；
• 影响编译速度：注解处理器复杂或过多会拖慢编译速度。

五、APT 工具推荐

六、简单示例：用 JavaPoet 生成代码

private void generateCode(Element element) {
    TypeSpec generatedClass = TypeSpec.classBuilder("GeneratedClass")
            .addMethod(MethodSpec.methodBuilder("sayHello")
                    .addStatement("System.out.println($S)", "Hello from " + element.getSimpleName())
                    .build())
            .build();

    JavaFile javaFile = JavaFile.builder("com.example", generatedClass).build();

    try {
        javaFile.writeTo(processingEnv.getFiler());
    } catch (IOException e) {
        e.printStackTrace();
    }
}

编译后会生成：

package org.example.apt;

public class GeneratedClass {
    public void sayHello() {
        System.out.println("Hello from MyClass");
    }
}

七、总结

APT 是 Java 编译期处理注解的强大工具，广泛用于现代 Java/Kotlin 框架中。通过 APT，你可以：

• 自动生成代码；
• 提高开发效率；
• 实现编译期安全检查；
• 构建插件化、模块化的架构。

虽然学习成本较高，但掌握后可以极大提升开发效率和系统设计能力。