Java注解处理器详解#

什么是注解处理器？#

注解处理器（Annotation Processor）是Java编译器的一个插件，它在编译时扫描和处理注解，用于生成代码、验证代码或执行其他编译时任务。

注解处理器的应用场景#

代码生成：根据注解生成重复的代码，减少样板代码
代码验证：在编译时验证代码的正确性
资源处理：处理配置文件、资源文件等
文档生成：生成API文档、配置文档等
依赖注入：生成依赖注入的代码

注解处理器的工作原理#

注解处理器的工作原理如下：

编译器在编译过程中扫描源代码，收集所有的注解
编译器将收集到的注解传递给对应的注解处理器
注解处理器处理这些注解，可能会生成新的源代码或资源文件
编译器编译生成的源代码和原始源代码

注解处理器的生命周期#

注解处理器的生命周期包括以下几个阶段：

初始化：调用init()方法，初始化注解处理器
处理注解：调用process()方法，处理注解
完成：所有注解处理完成后，注解处理器结束

创建注解处理器#

1. 定义注解#

首先，需要定义一个或多个注解，用于标记需要处理的元素。

1
import java.lang.annotation.ElementType;
2
import java.lang.annotation.Retention;
3
import java.lang.annotation.RetentionPolicy;
4
import java.lang.annotation.Target;
5

6
@Target(ElementType.TYPE)
7
@Retention(RetentionPolicy.SOURCE)
8
public @interface GenerateBuilder {
9
}

2. 实现注解处理器#

然后，需要实现javax.annotation.processing.AbstractProcessor类，重写其中的方法。

1
import javax.annotation.processing.*;
2
import javax.lang.model.SourceVersion;
3
import javax.lang.model.element.Element;
4
import javax.lang.model.element.TypeElement;
5
import javax.tools.Diagnostic;
6
import java.util.Set;
7

8
@SupportedAnnotationTypes("com.example.GenerateBuilder")
9
@SupportedSourceVersion(SourceVersion.RELEASE_8)
10
public class BuilderProcessor extends AbstractProcessor {
11

12
    private Filer filer;
13
    private Messager messager;
14

15
    @Override
16
    public synchronized void init(ProcessingEnvironment processingEnv) {
17
        super.init(processingEnv);
18
        filer = processingEnv.getFiler();
19
        messager = processingEnv.getMessager();
20
    }
21

22
    @Override
23
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
24
        for (TypeElement annotation : annotations) {
25
            Set<? extends Element> annotatedElements = roundEnv.getElementsAnnotatedWith(annotation);
26
            for (Element element : annotatedElements) {
27
                if (element instanceof TypeElement) {
28
                    TypeElement typeElement = (TypeElement) element;
29
                    generateBuilder(typeElement);
30
                }
31
            }
32
        }
33
        return true;
34
    }
35

36
    private void generateBuilder(TypeElement typeElement) {
37
        // 生成Builder类的代码
38
        // ...
39
    }
40
}

3. 注册注解处理器#

最后，需要在META-INF/services目录下创建一个名为javax.annotation.processing.Processor的文件，文件内容是注解处理器的全限定名。

1
com.example.BuilderProcessor

注解处理器的核心API#

1. ProcessingEnvironment#

ProcessingEnvironment提供了注解处理器与编译器之间的通信渠道，包含以下核心方法：

getFiler()：获取Filer对象，用于生成文件
getMessager()：获取Messager对象，用于输出消息
getElementUtils()：获取Elements对象，用于操作元素
getTypeUtils()：获取Types对象，用于操作类型
getSourceVersion()：获取源代码版本
getOptions()：获取处理器选项

2. Filer#

Filer用于生成文件，包含以下核心方法：

createSourceFile(String name)：创建源文件
createClassFile(String name)：创建类文件
createResource(JavaFileManager.Location location, String pkg, String relativeName)：创建资源文件

3. Messager#

Messager用于输出消息，包含以下核心方法：

printMessage(Diagnostic.Kind kind, CharSequence msg)：输出消息
printMessage(Diagnostic.Kind kind, CharSequence msg, Element e)：输出与元素相关的消息

4. Elements#

Elements用于操作元素，包含以下核心方法：

getTypeElement(String name)：获取类型元素
getName(String name)：获取名称
getPackageOf(Element e)：获取元素所在的包
toString(Element e)：获取元素的字符串表示
getAllAnnotationMirrors(Element e)：获取元素的所有注解

5. Types#

Types用于操作类型，包含以下核心方法：

isSameType(TypeMirror t1, TypeMirror t2)：检查两个类型是否相同
isSubtype(TypeMirror t1, TypeMirror t2)：检查t1是否是t2的子类型
erasure(TypeMirror t)：获取类型的擦除
boxedClass(PrimitiveType t)：获取基本类型的包装类

6. RoundEnvironment#

RoundEnvironment提供了当前处理轮次的信息，包含以下核心方法：

getElementsAnnotatedWith(TypeElement a)：获取被指定注解标记的元素
getElementsAnnotatedWithAny(Set<? extends TypeElement> annotations)：获取被任何指定注解标记的元素
processingOver()：检查处理是否完成
errorRaised()：检查是否有错误发生

生成代码的示例#

生成Builder类#

下面是一个生成Builder类的注解处理器示例：

1
import javax.annotation.processing.*;
2
import javax.lang.model.SourceVersion;
3
import javax.lang.model.element.*;
4
import javax.lang.model.type.TypeMirror;
5
import javax.tools.Diagnostic;
6
import javax.tools.JavaFileObject;
7
import java.io.IOException;
8
import java.io.Writer;
9
import java.util.List;
10
import java.util.Set;
11

12
@SupportedAnnotationTypes("com.example.GenerateBuilder")
13
@SupportedSourceVersion(SourceVersion.RELEASE_8)
14
public class BuilderProcessor extends AbstractProcessor {
15

16
    private Filer filer;
17
    private Messager messager;
18
    private Elements elementUtils;
19

20
    @Override
21
    public synchronized void init(ProcessingEnvironment processingEnv) {
22
        super.init(processingEnv);
23
        filer = processingEnv.getFiler();
24
        messager = processingEnv.getMessager();
25
        elementUtils = processingEnv.getElementUtils();
26
    }
27

28
    @Override
29
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
30
        for (TypeElement annotation : annotations) {
31
            Set<? extends Element> annotatedElements = roundEnv.getElementsAnnotatedWith(annotation);
32
            for (Element element : annotatedElements) {
33
                if (element instanceof TypeElement) {
34
                    TypeElement typeElement = (TypeElement) element;
35
                    generateBuilder(typeElement);
36
                }
37
            }
38
        }
39
        return true;
40
    }
41

42
    private void generateBuilder(TypeElement typeElement) {
43
        String className = typeElement.getSimpleName().toString();
44
        String packageName = getPackageName(typeElement);
45
        String builderClassName = className + "Builder";
46

47
        try {
48
            JavaFileObject javaFileObject = filer.createSourceFile(packageName + "." + builderClassName);
49
            Writer writer = javaFileObject.openWriter();
50

51
            // 生成包声明
52
            if (!packageName.isEmpty()) {
53
                writer.write("package " + packageName + ";\n\n");
54
            }
55

56
            // 生成类声明
57
            writer.write("public class " + builderClassName + " {\n");
58

59
            // 生成字段
60
            List<? extends Element> members = typeElement.getEnclosedElements();
61
            for (Element member : members) {
62
                if (member.getKind() == ElementKind.FIELD) {
63
                    VariableElement field = (VariableElement) member;
64
                    String fieldName = field.getSimpleName().toString();
65
                    TypeMirror fieldType = field.asType();
66
                    String fieldTypeName = fieldType.toString();
67
                    writer.write("    private " + fieldTypeName + " " + fieldName + ";\n");
68
                }
69
            }
70

71
            // 生成setter方法
72
            for (Element member : members) {
73
                if (member.getKind() == ElementKind.FIELD) {
74
                    VariableElement field = (VariableElement) member;
75
                    String fieldName = field.getSimpleName().toString();
76
                    TypeMirror fieldType = field.asType();
77
                    String fieldTypeName = fieldType.toString();
78
                    String methodName = "with" + capitalize(fieldName);
79
                    writer.write("\n    public " + builderClassName + " " + methodName + "(" + fieldTypeName + " " + fieldName + ") {\n");
80
                    writer.write("        this." + fieldName + " = " + fieldName + ";\n");
81
                    writer.write("        return this;\n");
82
                    writer.write("    }\n");
83
                }
84
            }
85

86
            // 生成build方法
87
            writer.write("\n    public " + className + " build() {\n");
88
            writer.write("        return new " + className + "(this);\n");
89
            writer.write("    }\n");
90

91
            // 生成结束
92
            writer.write("}\n");
93
            writer.close();
94

95
            // 生成目标类的构造方法
96
            generateConstructor(typeElement, builderClassName);
97

98
        } catch (IOException e) {
99
            messager.printMessage(Diagnostic.Kind.ERROR, "Error generating builder: " + e.getMessage(), typeElement);
100
        }
101
    }
102

103
    private void generateConstructor(TypeElement typeElement, String builderClassName) throws IOException {
104
        String className = typeElement.getSimpleName().toString();
105
        String packageName = getPackageName(typeElement);
106

107
        // 获取原始类的源代码
108
        // 注意：这只是一个示例，实际实现可能需要更复杂的处理
109
        // 例如，使用JavaParser等库来解析和修改源代码
110

111
        messager.printMessage(Diagnostic.Kind.NOTE, "Please add a constructor to " + className + " that takes a " + builderClassName + " parameter.");
112
    }
113

114
    private String getPackageName(TypeElement typeElement) {
115
        PackageElement packageElement = elementUtils.getPackageOf(typeElement);
116
        return packageElement.getQualifiedName().toString();
117
    }
118

119
    private String capitalize(String str) {
120
        if (str == null || str.isEmpty()) {
121
            return str;
122
        }
123
        return str.substring(0, 1).toUpperCase() + str.substring(1);
124
    }
125
}

使用注解处理器#

使用注解处理器的示例：

1
@GenerateBuilder
2
public class Person {
3
    private String name;
4
    private int age;
5
    private String email;
6

7
    // 需要手动添加一个接受Builder参数的构造方法
8
    public Person(PersonBuilder builder) {
9
        this.name = builder.name;
10
        this.age = builder.age;
11
        this.email = builder.email;
12
    }
13

14
    // getter方法
15
    public String getName() {
16
        return name;
17
    }
18

19
    public int getAge() {
20
        return age;
21
    }
22

23
    public String getEmail() {
24
        return email;
25
    }
26
}
27

28
// 使用Builder
29
public class Main {
30
    public static void main(String[] args) {
31
        Person person = new PersonBuilder()
32
                .withName("张三")
33
                .withAge(25)
34
                .withEmail("zhangsan@example.com")
35
                .build();
36
        System.out.println(person.getName());
37
        System.out.println(person.getAge());
38
        System.out.println(person.getEmail());
39
    }
40
}

注解处理器的最佳实践#

1. 处理多轮次#

注解处理器可能会被调用多次，每轮处理可能会生成新的源代码，这些源代码也需要被处理。

1
@Override
2
public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
3
    // 只处理非空的注解集
4
    if (annotations.isEmpty()) {
5
        return false;
6
    }
7

8
    // 处理注解
9
    // ...
10

11
    return true;
12
}

2. 错误处理#

应该适当处理错误，并使用Messager输出错误消息。

1
if (someCondition) {
2
    messager.printMessage(Diagnostic.Kind.ERROR, "错误消息", element);
3
    return false;
4
}

3. 资源管理#

生成文件后，应该关闭所有打开的资源。

1
JavaFileObject javaFileObject = filer.createSourceFile(className);
2
try (Writer writer = javaFileObject.openWriter()) {
3
    // 生成代码
4
    // ...
5
} catch (IOException e) {
6
    messager.printMessage(Diagnostic.Kind.ERROR, "Error generating file: " + e.getMessage());
7
}

4. 性能优化#

缓存计算结果，避免重复计算
只处理需要处理的元素
使用适当的数据结构，提高查找效率

5. 可测试性#

将生成代码的逻辑与注解处理的逻辑分离
编写单元测试，测试生成的代码

6. 文档化#

为注解处理器添加Javadoc，说明其用途和使用方法
为生成的代码添加注释，说明其生成方式和用途

常见陷阱#

1. 无限循环#

如果注解处理器生成的代码也包含被处理的注解，可能会导致无限循环。

2. 类型擦除#

在处理泛型类型时，需要考虑类型擦除的影响。

3. 跨模块处理#

注解处理器只能处理当前模块的代码，不能处理其他模块的代码。

4. 版本兼容性#

不同版本的Java可能对注解处理器的API有不同的支持。

5. 调试困难#

注解处理器在编译时运行，调试比较困难。

6. 依赖问题#

注解处理器可能依赖其他库，但这些库需要在编译时可用。

注解处理器的替代方案#

1. Lombok#

Lombok是一个流行的库，它使用注解处理器来减少样板代码。

2. JavaParser#

JavaParser是一个库，用于解析和修改Java源代码。

3. ByteBuddy#

ByteBuddy是一个库，用于在运行时生成和修改Java类。

4. ASM#

ASM是一个低级库，用于操作Java字节码。

总结#

注解处理器是Java编译器的一个强大插件，它可以在编译时处理注解，生成代码或执行其他任务。注解处理器广泛应用于代码生成、依赖注入、文档生成等场景。

本文介绍了注解处理器的基本概念、工作原理、创建方法和最佳实践。希望本文能够帮助你更好地理解和使用注解处理器。

练习#

编写一个注解处理器，生成一个简单的Builder类。
编写一个注解处理器，生成 equals() 和 hashCode() 方法。
编写一个注解处理器，生成 toString() 方法。
编写一个注解处理器，验证方法的参数是否符合要求。
编写一个注解处理器，生成一个简单的工厂类。
编写一个注解处理器，生成一个简单的单例类。
编写一个注解处理器，生成一个简单的观察者模式的代码。
编写一个注解处理器，生成一个简单的命令模式的代码。
编写一个注解处理器，生成一个简单的策略模式的代码。
编写一个注解处理器，生成一个简单的模板方法模式的代码。

溪谷回声

这里是鹁鸪的思考之地

Java注解处理器详解