JSR 269实践

一、背景

如果你有使用过lombok和mapStruct等类似插件，对其实现原理好奇，那这篇文章可以帮助你了解它们的实现原理和套路。

二、JSR 269

JSR 269: Pluggable Annotation Processing API(https://www.jcp.org/en/jsr/detail?id=269)
在JSR 269 之前可以使用注解，但必须借助反射机制，而反射的方法局限性较大，由于必须定义@Retention为RetentionPolicy.RUNTIME，只能在运行期通过反射来获取注解值，使得运行时代码效率降低。其次，如果想在编译阶段利用注解来进行一些检查，对用户的某些不合理代码给出错误报告，反射的使用方法就无能为力了。
而 JSR 269 之后我们可以在 Javac的编译期利用注解做这些事情。所以我们发现核心的区分是在运行期 or 编译期。

三、自定义注解ToBeTested

实现一个自定义的注解toBeTested，标记在方法中，注解的作用在被标注方法的方法体前增加一行固定的打印，打印内容有toBeTested中内容指定。示例：

public class Bean {
    @ToBeTested(owner = "sunquan")
    public void test() {
        System.out.println("abc");
    }
}

在上述类中标记注解后，对应生成的字节码文件经反编译后为：

public class Bean {
    public Bean() {
    }

    @ToBeTested(
        owner = "sunquan"
    )
    public void test() {
    	//修改AST后，会自动增加的一行打印
        System.out.println("Method test invoke by sunquan.");
        System.out.println("abc");
    }
}

即源代码自动增加了一行System.out.println(“Method test invoke by sunquan.”);

四、注解处理器ToBeTestedProcessor

先定义ToBeTested注解

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ToBeTested {
    String owner() default "sunquan";
}

定义注解处理类继承AbstractProcessor

package com.zte.sunquan.demo.sapi;

import java.util.Set;
import javax.annotation.processing.AbstractProcessor;
import javax.annotation.processing.ProcessingEnvironment;
import javax.annotation.processing.Processor;
import javax.annotation.processing.RoundEnvironment;
import javax.annotation.processing.SupportedAnnotationTypes;
import javax.lang.model.element.Element;
import javax.lang.model.element.TypeElement;
import javax.tools.Diagnostic;

import com.google.auto.service.AutoService;
import com.sun.tools.javac.model.JavacElements;
import com.sun.tools.javac.processing.JavacProcessingEnvironment;
import com.sun.tools.javac.tree.JCTree;
import com.sun.tools.javac.tree.TreeMaker;
import com.sun.tools.javac.util.Context;
import com.sun.tools.javac.util.List;
import com.zte.sunquan.demo.sapi.annotation.ToBeTested;

@SupportedAnnotationTypes("com.zte.sunquan.demo.sapi.annotation.ToBeTested")
@AutoService(Processor.class)
@SupportedSourceVersion(SourceVersion.RELEASE_8)
public class ToBeTestedProcessor extends AbstractProcessor {
    private void note(String msg) {
        processingEnv.getMessager().printMessage(Diagnostic.Kind.NOTE, msg);
    }

    @Override
    public synchronized void init(ProcessingEnvironment processingEnvironment) {
        super.init(processingEnvironment);
    }

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        final Context context = ((JavacProcessingEnvironment) processingEnv).getContext();
        final JavacElements elementUtils = (JavacElements) processingEnv.getElementUtils();
        final TreeMaker treeMaker = TreeMaker.instance(context);
        Set<? extends Element> elements = roundEnv.getElementsAnnotatedWith(ToBeTested.class);
        if (elements == null || elements.size() == 0) {
            return true;
        }
        for (Element element : elements) {
            ToBeTested annotation = element.getAnnotation(ToBeTested.class);
            String owner = annotation.owner();
            JCTree.JCMethodDecl jcMethodDecl = (JCTree.JCMethodDecl) elementUtils.getTree(element);
            treeMaker.pos = jcMethodDecl.pos;
            //修改AST的逻辑
            jcMethodDecl.body = treeMaker.Block(0, List.of(
                    treeMaker.Exec(
                            treeMaker.Apply(
                                    List.<JCTree.JCExpression>nil(),
                                    treeMaker.Select(
                                            treeMaker.Select(
                                                    treeMaker.Ident(
                                                            elementUtils.getName("System")
                                                    ),
                                                    elementUtils.getName("out")
                                            ),
                                            elementUtils.getName("println")
                                    ),
                                    List.<JCTree.JCExpression>of(
                                            treeMaker.Literal("Method " + element.getSimpleName() + " invoke by " + owner + ".")
                                    )
                            )
                    ),
                    jcMethodDecl.body));
        }
        return true;
    }
}

本篇主要讲套路，具体的处理逻辑代码就不详细介绍。大家可以通过学习javapoet灵活操作最终代码的生成格式。

为什么叫面向 AST 编程呢？因为你的输入是 AST，操作的是各种 AST 节点，输出的还是 AST

构造操作语法树是一件很枯燥的事，本身不是直接以写代码的方式，需要code 到 tree 的对应机制，比如Lombok 则是通过修改 JCTree 去完成其功能的，上文介绍的JavaPoet 库，提供了更友好的 API 去产生 .java 文件的（最终还是要调用 Filer（JSR 269）的接口输出文件）
值得注意的是JavaPoet 只产生新代码，不会修改原有语法树，而 JCTree （即：使用${java.home}/…/lib/tools.jar 的接口）可以让你修改它

这不是一种好的实践，但确实有用

五、round概念

在使用注解处理器时，有个比较重要的概念，就是 round，javac 的编译过程大致为¹：

1、初始化插入式注解处理器(执行 AbstractProcessor 的 init 方法)
2、词法分析，语法分析，输入符号表，产生 JCTree
3、注解处理(执行 AbstractProcessor 的 process 方法 )
4、数据流处理
5、解语法糖
6、字节码生成

在执行完3注解处理后，会判断语法树有没有变动，没有就执行4，有变动则需要回到2再次进行记法分析，直到所有插入式注解处理器都不再更改语法树为止，每一次循环称为一次round

六、三方依赖

        <dependency>
            <groupId>com.google.auto.service</groupId>
            <artifactId>auto-service</artifactId>
            <version>1.0-rc2</version>
        </dependency>
        <dependency>
            <groupId>com.squareup</groupId>
            <artifactId>javapoet</artifactId>
            <version>1.7.0</version>
        </dependency>

        <dependency>
            <groupId>com.sun</groupId>
            <artifactId>tools</artifactId>
            <version>1.8</version>
            <scope>system</scope>
            <systemPath>${java.home}/../lib/tools.jar</systemPath>
        </dependency>

同时在目录META-INF\services\下自动生成了文件javax.annotation.processing.Processor，其中内容为字符串com.zte.sunquan.demo.sapi.ToBeTestedProcessor

相当于告知JVM有注解需要特殊处理

关于注解处理器的机制:
如果compiler插件没有配置注解处理器，则javac编译时会使用ServiceLoader扫描所有classpath:/META-INF/services/javax.annotation.processing.Processor文件，加载文件中的类作为要使用的注解处理器。

反之，如果显示配置了注解处理器(通过<annotationProcessors>或者<annotationProcessorPaths>)，则javac时会添加processor选项或processorpath选项,编译时会使用指定的注解处理器，不再进行扫描。

七、测试

在另一个工程中Bean.java使用注解ToBeTested

public class Bean {
    @ToBeTested(owner = "sunquan")
    public void test() {
        System.out.println("abc");
    }

    public static void main(String[] args) {
        final Bean bean = new Bean();
        bean.test();
    }
}

对应的POM依赖如下：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <groupId>com.zte.sunquan.annotation</groupId>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
<!--                    <compilerArgument>-proc:none</compilerArgument>-->
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>demo-processor</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.google.auto.service</groupId>
            <artifactId>auto-service</artifactId>
            <version>1.0-rc2</version>
        </dependency>
        <!--        <dependency>-->
        <!--            <groupId>com.squareup</groupId>-->
        <!--            <artifactId>javapoet</artifactId>-->
        <!--            <version>1.7.0</version>-->
        <!--        </dependency>-->
        <dependency>
            <groupId>com.sun</groupId>
            <artifactId>tools</artifactId>
            <version>1.8</version>
            <scope>system</scope>
            <systemPath>${java.home}/../lib/tools.jar</systemPath>
        </dependency>
    </dependencies>
</project>

这样在编译Bean.java后生成的代码中，则新增代码：

最终打印输出：

八、调试Debug

由于上述逻辑都是发生在编译期，如何debug注解的处理过程。
在IDE的Run/Debug Configurations中增加Remote配置，如图所示：

打开CMD,进到要编译的项目工程，执行mvnDebug clean install

注解在注解处理代码中打上断点，进入IDE，执行mvnDebug

之前的控制台如正常则会打印

IDE中断点也会生效

---

1. 1～3 为编译器前端，4～6 为编译器后端 ↩︎