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

Java注解与代码生成工具的结合

2021-10-036.3k 阅读

Java 注解基础

什么是 Java 注解

Java 注解（Annotation）是从 Java 5.0 引入的一种元数据机制，它允许我们在代码中添加额外的信息，这些信息可以在编译期、运行期等不同阶段被读取和使用。注解本质上是一种特殊的接口，它通过 @interface 关键字来定义。例如，我们常见的 @Override 注解，用于告诉编译器被注解的方法是重写父类的方法，如果方法签名与父类不匹配，编译器会报错。

注解的定义与基本结构

定义一个简单的注解如下：

public @interface MyAnnotation {
    // 注解元素，类似于接口中的方法
    String value() default "";
    int count() default 0;
}

在上述例子中，MyAnnotation 是一个自定义注解，它包含两个注解元素 value 和 count。value 类型为 String，默认值为空字符串；count 类型为 int，默认值为 0。

使用注解时，我们可以这样写：

public class MyClass {
    @MyAnnotation(value = "Hello", count = 5)
    public void myMethod() {
        // 方法体
    }
}

注解的保留策略

注解有三种保留策略，通过 Retention 元注解来指定，定义在 java.lang.annotation.RetentionPolicy 枚举中：

  1. SOURCE：注解只保留在源文件中，编译时会被丢弃，不会出现在字节码文件中。例如 @Override 注解，它只对编译器有意义，在运行时并不需要。
@Retention(RetentionPolicy.SOURCE)
public @interface SourceAnnotation {
    // 注解元素
}
  1. CLASS：注解保留在字节码文件中，但在运行时 JVM 不会读取。这是默认的保留策略。许多编译时处理的注解会采用这种策略，例如 @Deprecated 注解，编译器可以根据它生成警告信息，但运行时不需要额外处理。
@Retention(RetentionPolicy.CLASS)
public @interface ClassAnnotation {
    // 注解元素
}
  1. RUNTIME：注解不仅保留在字节码文件中，在运行时 JVM 也可以读取。这种注解通常用于需要在运行时根据注解信息进行动态处理的场景，例如 Spring 框架中的 @Autowired 注解。
@Retention(RetentionPolicy.RUNTIME)
public @interface RuntimeAnnotation {
    // 注解元素
}

元注解

元注解是用于注解其他注解的注解。Java 提供了几种元注解，除了前面提到的 @Retention 外，还有：

  1. @Target：用于指定注解可以应用的目标类型，例如类、方法、字段等。定义在 java.lang.annotation.ElementType 枚举中。
@Target({ElementType.METHOD, ElementType.FIELD})
public @interface TargetAnnotation {
    // 注解元素
}

上述 @TargetAnnotation 只能应用在方法和字段上。 2. @Documented：表示该注解会被包含在 Java 文档中。如果一个注解被 @Documented 修饰，那么使用该注解的元素在生成 Java 文档时，注解信息也会被包含进去。

@Documented
public @interface DocumentedAnnotation {
    // 注解元素
}
  1. @Inherited：表示该注解具有继承性。如果一个类使用了被 @Inherited 修饰的注解，那么它的子类也会自动拥有该注解。不过需要注意的是，这个继承只对类有效，对接口和成员无效。
@Inherited
public @interface InheritedAnnotation {
    // 注解元素
}
  1. @Repeatable：从 Java 8 开始引入，用于表示一个注解可以在同一目标上多次使用。首先需要定义一个容器注解，然后在重复注解上使用 @Repeatable 指向容器注解。
// 容器注解
public @interface MyRepeatedAnnotations {
    MyRepeatedAnnotation[] value();
}

// 可重复注解
@Repeatable(MyRepeatedAnnotations.class)
public @interface MyRepeatedAnnotation {
    String value();
}

使用方式如下：

public class RepeatableClass {
    @MyRepeatedAnnotation("Value1")
    @MyRepeatedAnnotation("Value2")
    public void repeatableMethod() {
        // 方法体
    }
}

代码生成工具概述

代码生成的需求与场景

在软件开发过程中，有许多重复、繁琐的代码编写工作，例如数据库访问层的 CRUD（Create, Read, Update, Delete）操作、实体类与 DTO（Data Transfer Object）之间的转换等。手动编写这些代码不仅耗时费力，而且容易出错。代码生成工具可以根据一定的规则和模板，自动生成这些重复代码，提高开发效率，减少人为错误。

例如，在一个基于数据库的 Web 应用中，我们可能有多个实体类，每个实体类都需要对应的数据库访问方法。使用代码生成工具，我们只需要定义好实体类的结构，工具就能自动生成对应的 DAO（Data Access Object）层代码，包含增删改查等基本操作。

常见的代码生成工具

  1. Velocity：是 Apache 软件基金会的一个开源模板引擎，它允许用户使用简单的模板语言来生成各种格式的文本，如 HTML、SQL、Java 代码等。Velocity 的模板语法简单直观，易于学习和使用。例如，我们可以定义一个生成 Java 类的 Velocity 模板：
package $packageName;

public class $className {
    #foreach( $field in $fields )
        private $field.type $field.name;
    #end

    #foreach( $field in $fields )
        public $field.type get$field.capitalizedName() {
            return $field.name;
        }

        public void set$field.capitalizedName( $field.type value ) {
            this.$field.name = value;
        }
    #end
}

在上述模板中，$packageName、$className、$fields 等是模板变量，通过在运行时传入相应的值，就可以生成具体的 Java 类。 2. FreeMarker：也是一个流行的模板引擎，它与 Velocity 类似，但语法略有不同。FreeMarker 的优势在于其强大的表达式语言和对复杂数据结构的支持。例如，生成一个 HTML 页面的 FreeMarker 模板：

<!DOCTYPE html>
<html>
<head>
    <title>${pageTitle}</title>
</head>
<body>
    <h1>${pageTitle}</h1>
    <ul>
        <#list items as item>
            <li>${item}</li>
        </#list>
    </ul>
</body>
</html>

在这个模板中，${pageTitle} 和 <#list items as item> 等是 FreeMarker 的语法，通过传入 pageTitle 和 items 的具体值，可以生成动态的 HTML 页面。 3. JavaPoet：是 Square 公司开源的一个用于生成 Java 源文件的库。它使用 Java 代码来构建 Java 代码，相比模板引擎，它更加类型安全，并且可以利用 IDE 的代码检查和自动完成功能。以下是使用 JavaPoet 生成一个简单 Java 类的示例：

import com.squareup.javapoet.ClassName;
import com.squareup.javapoet.FieldSpec;
import com.squareup.javapoet.JavaFile;
import com.squareup.javapoet.MethodSpec;
import com.squareup.javapoet.TypeSpec;

import java.io.IOException;

import static javax.lang.model.element.Modifier.PRIVATE;
import static javax.lang.model.element.Modifier.PUBLIC;

public class JavaPoetExample {
    public static void main(String[] args) throws IOException {
        FieldSpec nameField = FieldSpec.builder(String.class, "name")
               .addModifiers(PRIVATE)
               .build();

        MethodSpec getNameMethod = MethodSpec.methodBuilder("getName")
               .addModifiers(PUBLIC)
               .returns(String.class)
               .addStatement("return name")
               .build();

        MethodSpec setNameMethod = MethodSpec.methodBuilder("setName")
               .addModifiers(PUBLIC)
               .returns(void.class)
               .addParameter(String.class, "name")
               .addStatement("this.name = name")
               .build();

        TypeSpec personClass = TypeSpec.classBuilder("Person")
               .addModifiers(PUBLIC)
               .addField(nameField)
               .addMethod(getNameMethod)
               .addMethod(setNameMethod)
               .build();

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

        javaFile.writeTo(System.out);
    }
}

上述代码使用 JavaPoet 构建了一个 Person 类，包含一个私有字段 name 以及对应的 get 和 set 方法，并将生成的 Java 代码输出到控制台。

Java 注解与代码生成工具的结合

基于注解驱动的代码生成原理

通过将 Java 注解与代码生成工具相结合，我们可以实现根据代码中的注解信息，自动生成特定的代码。其基本原理是在编译期或运行期读取注解信息，然后根据这些信息调用代码生成工具生成相应的代码。

例如，我们定义一个 @GenerateDao 注解，用于标记需要生成数据库访问层代码的实体类。在编译期，通过注解处理器读取被 @GenerateDao 注解的实体类信息，如类名、字段等，然后使用代码生成工具（如 JavaPoet）生成对应的 DAO 类代码，包含基本的增删改查方法。

实现步骤

  1. 定义注解：首先定义用于驱动代码生成的注解。假设我们要生成数据库访问层代码，定义一个 @GenerateDao 注解如下：
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.TYPE)
public @interface GenerateDao {
    // 数据库表名，如果不指定，默认使用类名小写
    String tableName() default "";
}

这个注解用于标记实体类，tableName 元素用于指定对应的数据库表名，默认值为空字符串，在使用时如果不指定，则会使用类名的小写形式作为表名。

  1. 编写注解处理器：使用 Java 的注解处理 API（javax.annotation.processing）编写一个注解处理器，用于在编译期读取注解信息。以下是一个简单的 GenerateDaoProcessor 示例：
import javax.annotation.processing.*;
import javax.lang.model.SourceVersion;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import java.util.Set;

@SupportedAnnotationTypes("GenerateDao")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class GenerateDaoProcessor 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) {
                if (element instanceof TypeElement) {
                    TypeElement typeElement = (TypeElement) element;
                    GenerateDao generateDao = typeElement.getAnnotation(GenerateDao.class);
                    String tableName = generateDao.tableName();
                    if ("".equals(tableName)) {
                        tableName = typeElement.getSimpleName().toString().toLowerCase();
                    }
                    // 这里可以调用代码生成工具，根据注解信息生成 DAO 代码
                    System.out.println("Generating DAO for " + typeElement.getSimpleName() + " with table name " + tableName);
                }
            }
        }
        return true;
    }
}

在这个处理器中，process 方法会在编译期被调用，它遍历所有被 @GenerateDao 注解的元素，获取注解信息，并可以根据这些信息调用代码生成工具。目前这里只是简单地输出需要生成 DAO 的类名和表名。

  1. 配置注解处理器：为了让编译器识别并使用我们编写的注解处理器，需要在 resources/META-INF/services 目录下创建一个名为 javax.annotation.processing.Processor 的文件，文件内容为注解处理器的全限定类名，即 GenerateDaoProcessor 的全限定类名。

  2. 使用代码生成工具生成代码：这里以 JavaPoet 为例，在注解处理器中调用 JavaPoet 生成具体的 DAO 代码。修改 GenerateDaoProcessor 如下：

import com.squareup.javapoet.ClassName;
import com.squareup.javapoet.FieldSpec;
import com.squareup.javapoet.JavaFile;
import com.squareup.javapoet.MethodSpec;
import com.squareup.javapoet.TypeSpec;

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

import static javax.lang.model.element.Modifier.PRIVATE;
import static javax.lang.model.element.Modifier.PUBLIC;

@SupportedAnnotationTypes("GenerateDao")
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class GenerateDaoProcessor 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) {
                if (element instanceof TypeElement) {
                    TypeElement typeElement = (TypeElement) element;
                    GenerateDao generateDao = typeElement.getAnnotation(GenerateDao.class);
                    String tableName = generateDao.tableName();
                    if ("".equals(tableName)) {
                        tableName = typeElement.getSimpleName().toString().toLowerCase();
                    }

                    // 使用 JavaPoet 生成 DAO 代码
                    ClassName daoClassName = ClassName.get(typeElement.getPackage().getQualifiedName().toString(), typeElement.getSimpleName() + "Dao");
                    TypeSpec daoClass = TypeSpec.classBuilder(daoClassName)
                           .addModifiers(PUBLIC)
                           .addField(FieldSpec.builder(ClassName.get("java.sql", "Connection"), "connection")
                                   .addModifiers(PRIVATE)
                                   .build())
                           .addMethod(MethodSpec.constructorBuilder()
                                   .addModifiers(PUBLIC)
                                   .addParameter(ClassName.get("java.sql", "Connection"), "connection")
                                   .addStatement("this.connection = connection")
                                   .build())
                           .addMethod(MethodSpec.methodBuilder("insert")
                                   .addModifiers(PUBLIC)
                                   .returns(void.class)
                                   .addParameter(ClassName.get(typeElement.getPackage().getQualifiedName().toString(), typeElement.getSimpleName().toString()), "entity")
                                   .addStatement("$T statement = connection.prepareStatement($S)", ClassName.get("java.sql", "PreparedStatement"), "INSERT INTO " + tableName + " VALUES (?,?,?)")
                                   .addStatement("statement.executeUpdate()")
                                   .build())
                           .build();

                    JavaFile javaFile = JavaFile.builder(typeElement.getPackage().getQualifiedName().toString(), daoClass)
                           .build();

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

在上述代码中，使用 JavaPoet 构建了一个简单的 DAO 类，包含一个构造方法和一个 insert 方法。insert 方法使用 PreparedStatement 向数据库表中插入数据，这里假设表有三个字段，实际应用中需要根据实体类的字段动态生成 SQL 语句。javaFile.writeTo(processingEnv.getFiler()) 将生成的 Java 代码写入到指定的文件中。

实际应用案例

假设我们有一个 User 实体类，使用 @GenerateDao 注解标记：

@GenerateDao(tableName = "users")
public class User {
    private int id;
    private String name;
    private String email;

    // getters and setters
    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

当编译这个项目时，注解处理器会读取 @GenerateDao 注解信息，使用 JavaPoet 生成 UserDao 类：

package com.example;

import java.sql.Connection;
import java.sql.PreparedStatement;

public class UserDao {
    private Connection connection;

    public UserDao(Connection connection) {
        this.connection = connection;
    }

    public void insert(User entity) {
        PreparedStatement statement = connection.prepareStatement("INSERT INTO users VALUES (?,?,?)");
        statement.executeUpdate();
    }
}

这样，通过 Java 注解与代码生成工具的结合，我们实现了根据实体类的注解自动生成数据库访问层代码，大大提高了开发效率。

注意事项与优化

性能问题

在使用注解处理器和代码生成工具时，性能是一个需要关注的问题。尤其是在大型项目中，编译时间可能会显著增加。为了优化性能，可以考虑以下几点：

  1. 减少不必要的处理：在注解处理器中，尽量只处理真正需要生成代码的注解，避免对所有注解进行无意义的遍历和处理。例如，可以在注解处理器的 process 方法中添加一些逻辑判断，只对特定类型的注解或特定包下的注解进行处理。
  2. 缓存处理结果：如果某些注解信息或生成的代码片段是重复使用的，可以考虑使用缓存机制。例如，对于一些通用的数据库操作方法（如 insert、update 等），可以在第一次生成后进行缓存，后续再次遇到相同的情况时直接从缓存中获取，而不需要重新生成。

代码维护与可读性

虽然自动生成代码可以提高开发效率，但也可能会带来代码维护和可读性方面的问题。为了应对这些问题：

  1. 遵循统一的编码规范：无论是手动编写的代码还是自动生成的代码，都应该遵循统一的编码规范。这样可以使整个项目的代码风格一致，易于理解和维护。例如，使用相同的命名规则、代码缩进格式等。
  2. 添加注释：在自动生成的代码中添加适当的注释，说明代码的功能和生成逻辑。这样在后续维护时，开发人员可以更容易地理解代码的作用。例如，在 DAO 类的方法中添加注释，说明该方法对应的数据库操作以及参数的含义。

与现有框架的集成

在实际项目中，通常会使用各种框架，如 Spring、Hibernate 等。将基于注解的代码生成工具与现有框架集成时，需要注意以下几点：

  1. 遵循框架的约定：不同的框架有不同的约定和配置方式。例如，Spring 框架有自己的依赖注入、事务管理等机制。在生成代码时，需要遵循这些框架的约定，确保生成的代码能够与框架无缝集成。例如，在生成的 DAO 类中，如果要使用 Spring 的依赖注入，需要按照 Spring 的注解方式（如 @Component、@Autowired 等）进行配置。
  2. 避免冲突：在集成过程中，要注意避免与框架原有的功能和配置产生冲突。例如，框架可能已经有自己的数据库连接管理机制，在生成的 DAO 代码中就不能再重复实现类似的功能，否则可能会导致意想不到的问题。需要仔细研究框架的文档和源码，确保生成的代码与框架的其他部分协调工作。