MK
摩柯社区 - 一个极简的技术知识社区
AI 面试

Java注解处理器与代码生成技术

2022-06-285.0k 阅读

Java注解处理器基础

注解概述

在Java中，注解（Annotation）是一种元数据形式，它为我们在代码中添加额外信息提供了一种便捷的方式。这些信息可以在编译期、运行期被读取并利用。例如，@Override注解用于标识子类中重写父类的方法，编译器会检查该方法是否确实重写了父类的方法，如果不是则报错。又如@Deprecated注解，标记一个类、方法或字段已过时，当其他代码使用这些被标记的元素时，编译器会发出警告。

Java内置了一些基本注解，同时我们也可以自定义注解。自定义注解通过@interface关键字来定义，如下是一个简单的自定义注解示例：

public @interface MyAnnotation {
    String value() default "";
}

这里定义了一个名为MyAnnotation的注解，它有一个名为value的元素，默认值为空字符串。使用时可以这样：

@MyAnnotation("Hello, Annotation!")
public class MyClass {
    // 类的内容
}

注解处理器的概念

注解处理器（Annotation Processor）是在编译期处理注解的工具。当Java编译器编译代码时，它会检查代码中的注解，并调用相应的注解处理器来处理这些注解。注解处理器可以读取、修改和生成代码。例如，我们可以编写一个注解处理器，根据自定义注解生成一些辅助代码，比如为标记了特定注解的类自动生成Getter和Setter方法，或者生成数据库访问层的代码。

编写简单的注解处理器

入门示例：简单的日志注解处理器

我们先来创建一个简单的日志注解处理器。首先定义一个日志注解：

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

@Retention(RetentionPolicy.SOURCE)
@Target(ElementType.METHOD)
public @interface Logging {
    String value() default "";
}

这个注解Logging用于方法上，且仅保留在源代码阶段。

接下来编写注解处理器：

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import java.util.Set;

@SupportedAnnotationTypes("Logging")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class LoggingProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (TypeElement annotation : annotations) {
            for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                if (element.getKind() == ElementKind.METHOD) {
                    Logging logging = element.getAnnotation(Logging.class);
                    processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, "Logging method: " + element.getSimpleName() + " with value: " + logging.value());
                }
            }
        }
        return true;
    }
}

这个注解处理器LoggingProcessor继承自AbstractProcessor。@SupportedAnnotationTypes指定它处理Logging注解，@SupportedSourceVersion指定支持的Java版本为Java 8。process方法是注解处理器的核心，它遍历所有被Logging注解标记的元素（这里是方法），并打印出方法名和注解的value值。

要使用这个注解处理器，我们需要将其打包成一个Jar文件，并在编译时指定该处理器。假设我们有一个使用Logging注解的类：

public class MyService {
    @Logging("This is a log message for doWork method")
    public void doWork() {
        // 方法逻辑
    }
}

编译时可以使用命令：javac -processor LoggingProcessor MyService.java。这样，在编译MyService.java时，注解处理器LoggingProcessor就会被调用，处理@Logging注解。

深入理解注解处理器

处理流程与环境

  1. 处理流程
    • 当Java编译器开始编译代码时，它会检测到代码中的注解。对于每一轮编译（可能有多轮，因为注解处理器可能会生成新的源文件触发新一轮编译），编译器会调用所有注册的注解处理器的process方法。
    • 注解处理器在process方法中处理被注解标记的元素。处理完成后，如果注解处理器生成了新的源文件，编译器会启动新一轮编译，重新调用注解处理器，直到没有新的源文件生成或者所有注解处理器返回false表示不再有需要处理的内容。
  2. ProcessingEnvironment
    • processingEnv是在注解处理器中非常重要的一个对象，它通过init方法传递给注解处理器。processingEnv提供了很多有用的工具和信息，例如：
      • Messager：用于向用户报告错误、警告或其他信息，如前面示例中processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, "Logging method...")。
      • Filer：用于生成新的源文件、类文件等。我们可以使用Filer在编译期生成Java源文件，后续编译器会对生成的源文件进行编译。
      • Elements：提供了操作元素（如类、方法、字段等）的工具。例如，我们可以通过Elements获取元素的修饰符、类型等信息。
      • Types：用于处理类型相关的操作，比如判断两个类型是否相等、获取类型的超类等。

注解的保留策略与目标

  1. 保留策略（RetentionPolicy）
    • SOURCE：注解仅保留在源文件中，编译时被丢弃。像@Override注解通常就是这种保留策略，它主要用于给编译器提供信息，编译后的字节码中并不需要它。
    • CLASS：注解保留在编译后的字节码中，但运行时JVM不会读取。这种策略适用于一些编译期处理的注解，例如一些用于代码优化、生成辅助代码的注解，运行时不需要额外处理。
    • RUNTIME：注解保留在编译后的字节码中，并且运行时JVM可以读取。像@Component注解在Spring框架中，运行时通过反射来获取被该注解标记的类，用于实例化和管理Bean。
  2. 目标（ElementType）
    • TYPE：可以应用于类、接口、枚举等类型。例如，我们可以定义一个注解用于标记某个类是一个特定类型的服务类。
    • METHOD：用于方法。如前面的@Logging注解就是用于方法上。
    • FIELD：应用于字段。比如可以定义一个注解用于标记数据库表中的字段。
    • PARAMETER：用于方法参数。例如可以定义一个注解用于验证方法参数。
    • CONSTRUCTOR：用于构造函数。
    • LOCAL_VARIABLE：用于局部变量。虽然使用场景相对较少，但在某些特定需求下，比如标记局部变量用于特定的调试或分析目的。
    • ANNOTATION_TYPE：用于注解类型本身，即可以给一个注解再添加注解。
    • PACKAGE：用于包声明，在package - info.java文件中使用，可用于给整个包添加元数据。

代码生成技术

使用Filer生成源文件

  1. 基本步骤
    • 在注解处理器中，要生成源文件，首先需要获取Filer对象，它来自processingEnv。例如：Filer filer = processingEnv.getFiler();
    • 然后使用filer.createSourceFile方法来创建一个新的源文件。该方法接受一个字符串参数，即生成的源文件的全限定名。例如，要生成一个名为GeneratedClass的类，位于com.example包下，可以这样调用：
JavaFileObject sourceFile = filer.createSourceFile("com.example.GeneratedClass");
  • 接下来，我们需要向生成的源文件中写入内容。可以通过sourceFile.openWriter()获取一个Writer对象，然后使用Writer对象进行文本写入。例如：
try (Writer writer = sourceFile.openWriter()) {
    writer.write("package com.example;\n");
    writer.write("public class GeneratedClass {\n");
    writer.write("    public void generatedMethod() {\n");
    writer.write("        System.out.println(\"This is a generated method.\");\n");
    writer.write("    }\n");
    writer.write("}\n");
} catch (IOException e) {
    processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Error generating source file: " + e.getMessage());
}
  1. 生成复杂代码示例 假设我们有一个Entity注解，用于标记数据库实体类，并且我们希望根据这个注解自动生成数据库访问层的代码（简化示例）。首先定义Entity注解：
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface Entity {
    String tableName();
}

然后编写注解处理器：

import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.tools.JavaFileObject;
import java.io.IOException;
import java.io.Writer;
import java.util.Set;

@SupportedAnnotationTypes("Entity")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class EntityProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (TypeElement annotation : annotations) {
            for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                if (element.getKind() == ElementKind.CLASS) {
                    Entity entity = element.getAnnotation(Entity.class);
                    String entityClassName = element.getSimpleName().toString();
                    String tableName = entity.tableName();
                    generateDaoClass(entityClassName, tableName);
                }
            }
        }
        return true;
    }

    private void generateDaoClass(String entityClassName, String tableName) {
        Filer filer = processingEnv.getFiler();
        try {
            JavaFileObject sourceFile = filer.createSourceFile("com.example.dao." + entityClassName + "Dao");
            try (Writer writer = sourceFile.openWriter()) {
                writer.write("package com.example.dao;\n");
                writer.write("public class " + entityClassName + "Dao {\n");
                writer.write("    public void save(" + entityClassName + " entity) {\n");
                writer.write("        // 这里可以编写保存到数据库的逻辑，使用表名：" + tableName + "\n");
                writer.write("    }\n");
                writer.write("}\n");
            }
        } catch (IOException e) {
            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Error generating DAO class: " + e.getMessage());
        }
    }
}

如果我们有一个实体类：

@Entity(tableName = "users")
public class User {
    // 用户类的字段和方法
}

编译时使用javac -processor EntityProcessor User.java，就会在com.example.dao包下生成UserDao类，其中包含一个save方法的框架，虽然这里只是简单的示例，实际中可以根据需求填充更复杂的数据库操作逻辑。

使用代码生成工具库

  1. AutoValue
    • AutoValue是Google开源的一个用于生成值类（Value Class）的工具库。值类通常是不可变的，并且主要用于存储数据。使用AutoValue，我们只需要定义一个抽象类，使用@AutoValue注解标记，然后定义抽象方法来表示类的属性。AutoValue会自动生成实现类，包括构造函数、equals、hashCode和toString方法等。
    • 例如，定义一个Person类：
import com.google.auto.value.AutoValue;

@AutoValue
public abstract class Person {
    public abstract String name();
    public abstract int age();

    public static Person create(String name, int age) {
        return new AutoValue_Person(name, age);
    }
}
  • 这里Person是一个抽象类，通过@AutoValue注解，AutoValue会生成一个名为AutoValue_Person的具体实现类。create方法是一个静态工厂方法，用于创建Person实例。
  1. Lombok
    • Lombok是一个非常流行的Java库，它通过注解来简化Java代码，减少样板代码。例如，使用@Data注解可以自动生成Getter、Setter、equals、hashCode和toString方法。
    • 假设我们有一个Book类：
import lombok.Data;

@Data
public class Book {
    private String title;
    private String author;
}
  • 这里@Data注解让编译器在编译时自动生成title和author的Getter和Setter方法，以及equals、hashCode和toString方法。Lombok的原理也是通过注解处理器在编译期生成代码，从而简化我们的开发工作。

高级注解处理器技术

处理依赖关系

在实际应用中，注解处理器可能需要处理复杂的依赖关系。例如，一个注解可能依赖于其他注解，或者一个注解处理器生成的代码可能依赖于另一个注解处理器生成的代码。

假设我们有两个注解@Component和@Autowired。@Component用于标记一个类是一个组件，@Autowired用于自动注入组件。我们的注解处理器需要确保在处理@Autowired注解时，被注入的组件已经被处理并生成了相应的代码。

  1. 分析依赖
    • 注解处理器可以通过遍历被注解的元素，分析它们之间的依赖关系。例如，在处理@Autowired注解时，它需要找到被注入的组件类，检查该类是否被@Component注解标记，并且是否已经被相应的注解处理器处理。
import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.lang.model.util.Elements;
import java.util.Set;

@SupportedAnnotationTypes({"Component", "Autowired"})
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class DependencyProcessor extends AbstractProcessor {
    private Elements elementUtils;

    @Override
    public synchronized void init(ProcessingEnvironment processingEnv) {
        super.init(processingEnv);
        elementUtils = processingEnv.getElementUtils();
    }

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (TypeElement annotation : annotations) {
            if ("Component".equals(annotation.getSimpleName().toString())) {
                // 处理@Component注解
                for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                    // 生成组件相关代码
                }
            } else if ("Autowired".equals(annotation.getSimpleName().toString())) {
                for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                    // 获取被注入的组件类型
                    TypeElement injectedType = (TypeElement) element.asType().asElement();
                    boolean isComponent = false;
                    for (Element componentElement : roundEnv.getElementsAnnotatedWith(elementUtils.getTypeElement("Component"))) {
                        if (componentElement.equals(injectedType)) {
                            isComponent = true;
                            break;
                        }
                    }
                    if (!isComponent) {
                        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Autowired field requires a Component type.");
                    } else {
                        // 处理自动注入逻辑
                    }
                }
            }
        }
        return true;
    }
}
  1. 处理多轮编译
    • 由于注解处理器可能需要多轮编译来处理依赖关系，所以需要正确处理每一轮编译的结果。例如，如果在第一轮编译中，@Component注解处理器生成了一些组件类，那么在第二轮编译中，@Autowired注解处理器可以使用这些已生成的组件类信息来处理自动注入。注解处理器通过返回true来表示还有更多工作需要在后续轮次中完成，返回false表示当前轮次已经处理完所有相关工作。

与其他工具集成

  1. 与Maven集成
    • 在Maven项目中使用注解处理器，我们需要在pom.xml文件中配置。例如，对于前面的LoggingProcessor，假设它已经打包成logging - processor.jar，可以这样配置：
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven - compiler - plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>com.example</groupId>
                        <artifactId>logging - processor</artifactId>
                        <version>1.0.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>
  • 这里通过annotationProcessorPaths指定了注解处理器的依赖。这样在运行mvn compile时，Maven会自动调用LoggingProcessor处理代码中的@Logging注解。
  1. 与Gradle集成
    • 在Gradle项目中，配置方式略有不同。假设LoggingProcessor的依赖在本地Maven仓库中，可以这样配置：
apply plugin: 'java'

sourceCompatibility = 1.8
targetCompatibility = 1.8

dependencies {
    annotationProcessor group: 'com.example', name: 'logging - processor', version: '1.0.0'
}
  • 这里使用annotationProcessor配置了注解处理器的依赖。运行./gradlew build时，Gradle会调用LoggingProcessor处理相关注解。

实战案例：构建微服务框架的代码生成

需求分析

假设我们要构建一个简单的微服务框架，其中有以下需求：

  1. 定义一个@ServiceEndpoint注解，用于标记微服务的端点方法。这些方法会暴露为HTTP接口。
  2. 定义一个@ServiceComponent注解，用于标记微服务的组件类。
  3. 根据@ServiceEndpoint注解，自动生成HTTP路由相关的代码，例如使用Servlet或者Spring Web等框架的路由配置代码。
  4. 根据@ServiceComponent注解，生成组件的初始化和管理代码，比如将组件注册到一个全局的组件管理器中。

实现步骤

  1. 定义注解
    • 首先定义@ServiceEndpoint注解：
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.CLASS)
@Target(ElementType.METHOD)
public @interface ServiceEndpoint {
    String path();
    String method() default "GET";
}
  • 然后定义@ServiceComponent注解：
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Retention(RetentionPolicy.CLASS)
@Target(ElementType.TYPE)
public @interface ServiceComponent {
    String name();
}
  1. 编写注解处理器
    • 编写ServiceProcessor注解处理器：
import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.ElementKind;
import javax.lang.model.element.TypeElement;
import javax.tools.JavaFileObject;
import java.io.IOException;
import java.io.Writer;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;

@SupportedAnnotationTypes({"ServiceEndpoint", "ServiceComponent"})
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class ServiceProcessor extends AbstractProcessor {
    private Map<String, String> endpointMap = new HashMap<>();
    private Map<String, String> componentMap = new HashMap<>();

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        for (TypeElement annotation : annotations) {
            if ("ServiceEndpoint".equals(annotation.getSimpleName().toString())) {
                for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                    if (element.getKind() == ElementKind.METHOD) {
                        ServiceEndpoint endpoint = element.getAnnotation(ServiceEndpoint.class);
                        String methodName = element.getSimpleName().toString();
                        endpointMap.put(endpoint.path(), methodName);
                    }
                }
            } else if ("ServiceComponent".equals(annotation.getSimpleName().toString())) {
                for (Element element : roundEnv.getElementsAnnotatedWith(annotation)) {
                    if (element.getKind() == ElementKind.CLASS) {
                        ServiceComponent component = element.getAnnotation(ServiceComponent.class);
                        String className = element.getSimpleName().toString();
                        componentMap.put(component.name(), className);
                    }
                }
            }
        }
        generateRouterCode();
        generateComponentManagerCode();
        return true;
    }

    private void generateRouterCode() {
        Filer filer = processingEnv.getFiler();
        try {
            JavaFileObject sourceFile = filer.createSourceFile("com.example.router.ServiceRouter");
            try (Writer writer = sourceFile.openWriter()) {
                writer.write("package com.example.router;\n");
                writer.write("import javax.servlet.http.HttpServletRequest;\n");
                writer.write("import javax.servlet.http.HttpServletResponse;\n");
                writer.write("public class ServiceRouter {\n");
                writer.write("    public void route(HttpServletRequest request, HttpServletResponse response) {\n");
                for (Map.Entry<String, String> entry : endpointMap.entrySet()) {
                    writer.write("        if (\"" + entry.getKey() + "\".equals(request.getRequestURI())) {\n");
                    writer.write("            // 调用相应的端点方法：" + entry.getValue() + "\n");
                    writer.write("        }\n");
                }
                writer.write("    }\n");
                writer.write("}\n");
            }
        } catch (IOException e) {
            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Error generating router code: " + e.getMessage());
        }
    }

    private void generateComponentManagerCode() {
        Filer filer = processingEnv.getFiler();
        try {
            JavaFileObject sourceFile = filer.createSourceFile("com.example.manager.ServiceComponentManager");
            try (Writer writer = sourceFile.openWriter()) {
                writer.write("package com.example.manager;\n");
                writer.write("import java.util.HashMap;\n");
                writer.write("import java.util.Map;\n");
                writer.write("public class ServiceComponentManager {\n");
                writer.write("    private static Map<String, Object> componentMap = new HashMap<>();\n");
                for (Map.Entry<String, String> entry : componentMap.entrySet()) {
                    writer.write("    public static void register" + entry.getValue() + "() {\n");
                    writer.write("        " + entry.getValue() + " component = new " + entry.getValue() + "();\n");
                    writer.write("        componentMap.put(\"" + entry.getKey() + "\", component);\n");
                    writer.write("    }\n");
                }
                writer.write("    public static Object getComponent(String name) {\n");
                writer.write("        return componentMap.get(name);\n");
                writer.write("    }\n");
                writer.write("}\n");
            }
        } catch (IOException e) {
            processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "Error generating component manager code: " + e.getMessage());
        }
    }
}
  1. 使用注解
    • 假设有一个微服务组件类：
@ServiceComponent(name = "userService")
public class UserService {
    @ServiceEndpoint(path = "/users", method = "GET")
    public String getUsers() {
        // 获取用户列表的逻辑
        return "User list";
    }
}

编译时使用javac -processor ServiceProcessor UserService.java，会生成ServiceRouter和ServiceComponentManager类，分别用于HTTP路由和组件管理。

通过这样的实战案例，我们可以看到如何利用注解处理器和代码生成技术构建一个简单的微服务框架，实现自动化的代码生成，提高开发效率。