Java注解编译期处理AbstractProcessor详解

àì夳堔傛蜴生んèń 2024-03-24 14:13 53阅读 0赞

#### 文章目录 ####

*   *  概述
     *  注解处理器
     *   *  注解处理流程
         *  AbstractProcessor
         *   *  getSupportedOptions()
             *  getSupportedAnnotationTypes
             *  getSupportedSourceVersion
             *  init初始化
             *  process 处理方法
     *  如何注册注解处理器
     *  如何调试编译期代码
     *  Maven相关配置(指定生效的Processor)
     *  注意事项
     *  自定义注解处理器范例
     *   *  范例一： 自动生成Build构造器
         *  范例二：
     *  如何给编译期设置入参

### 概述 ###

我们接触的注解主要分为以下两类

1.  **运行时注解**：通过反射在运行时动态处理注解的逻辑
2.  **编译时注解**：通过注解处理器在编译期动态处理相关逻辑

平时我们接触的框架大部分都是运行时注解，比如：@Autowire @Resoure @Bean 等等。

那么我们平时有接触过哪些编译期注解呢，`@Lombok` `@AutoService` 等等

像这些**编译时注解**的作用都是自动生成代码，一是为了**提高编码的效率**，二是**避免在运行期大量使用反射**，通过在编译期利用反射生成辅助类和方法以供运行时使用。

那这些编译器注解都是如何运行的呢? 又是怎么自动生成代码的呢？

我们今天来详细介绍一下，不过再介绍之前，可以先简单了解一下Java注解的基本概念  
[Java注解][Java]

### 注解处理器 ###

#### 注解处理流程 ####

注解编译期处理流程最关键的一个类就是**Processor** ，它是注解处理器的接口类，我们所有需要对编译期处理注解的逻辑都需要实现这个**Processor**接口，当然，**AbstractProcessor** 抽象类帮我们写好了大部分都流程，所以我们只需要实现这个抽象类就可以很方便的定义一个**注解处理器**；

注解处理流程由多轮完成。每一轮都从编译器在源文件中搜索**注解**并选择适合这些注解的 **注解处理器(AbstractProcessor)** 开始。每个**注解处理器**依次在相应的源上被调用。

如果在此过程中生成了任何文件，则将以生成的文件作为输入开始另一轮。这个过程一直持续到处理阶段没有新文件生成为止。

注解处理器的处理步骤：

*  在java编译器中构建；
 *  编译器开始执行未执行过的注解处理器；
 *  循环处理注解元素(Element)，找到被该注解所修饰的类，方法，或者属性；
 *  生成对应的类，并写入文件；
 *  判断是否所有的注解处理器都已执行完毕，如果没有，继续下一个注解处理器的执行(回到步骤1)。

图TODO

#### AbstractProcessor ####

这是注解处理器的核心抽象类，我们主要来看看里面的方法

##### getSupportedOptions() #####

默认的实现是 从注解`SupportedOptions`获取值，该值是一个字符数组，例如

@SupportedOptions({
        "name","age"})
    public class SzzTestProcessor extends AbstractProcessor {
        
    }

不过貌似该接口并没有什么用处。

有资料表示 该可选参数可以从processingEnv获取到参数。

String resultPath = processingEnv.getOptions().get(参数);

实际上这个获取的参数是编译期通过入参 `-Akey=name` 设置的，跟getSupportedOptions没有什么关系。

##### getSupportedAnnotationTypes #####

获取当前的**注解处理类**能够处理哪些注解类型，默认实现是从`SupportedAnnotationTypes`注解里面获取；  
注解值是个字符串数组 String \[\] ;  
匹配上的注解,会通过当前的**注解处理类**的 process方法传入。

例如下面使用 \* 通配符支持所有的注解

@SupportedAnnotationTypes("*")
    @SupportedSourceVersion(SourceVersion.RELEASE_11)
    public class PrintingProcessor extends AbstractProcessor {
        
    
    }

又或者可以直接重写这个接口

@Override
      public ImmutableSet<String> getSupportedAnnotationTypes() {
        
        return ImmutableSet.of(AutoService.class.getName());
      }

最终他们生效的地方就是用来做过滤，因为处理的时候会获取到所有的注解，然后根据这个配置来获取自己能够处理的注解。

##### getSupportedSourceVersion #####

获取该注解处理器最大能够支持多大的版本，默认是从注解 `SupportedSourceVersion`中读取，或者自己重写方法，如果都没有的话 默认值是 **RELEASE\_6**

@SupportedSourceVersion(SourceVersion.RELEASE_11)
    public class PrintingProcessor extends AbstractProcessor {
        
    
    }

**或者重写(推荐 , 获取最新的版本)**

@Override
      public SourceVersion getSupportedSourceVersion() {
        
        //设置为能够支持最新版本
        return SourceVersion.latestSupported();
      }

##### init初始化 #####

init是初始化方法，这个方法传入了ProcessingEnvironment 对象。一般我们不需要去重写它，直接使用抽象类就行了。  
当然你也可以根据自己的需求来重新

@Override
        public synchronized void init(ProcessingEnvironment pe) {
        
            super.init(pe);
            System.out.println("SzzTestProcessor.init.....");
            // 可以获取到编译器参数（下面两个是一样的）
            System.out.println(processingEnv.getOptions());
            System.out.println(pe.getOptions());
    
        }

可以获取到很多信息，例如**获取编译器自定义参数**， 自定义参数的设置请看下面的 **如何给编译期设置入参** 部分

一些参数说明

<table> 
 <thead> 
  <tr> 
   <th>方法</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Elements getElementUtils()</td> 
   <td>返回实现Elements接口的对象，用于操作元素的工具类。</td> 
  </tr> 
  <tr> 
   <td>Filer getFiler()</td> 
   <td>返回实现Filer接口的对象，用于创建文件、类和辅助文件。</td> 
  </tr> 
  <tr> 
   <td>Messager getMessager()</td> 
   <td>返回实现Messager接口的对象，用于报告错误信息、警告提醒。</td> 
  </tr> 
  <tr> 
   <td>Map&lt;String,String&gt; getOptions()</td> 
   <td>返回指定的参数选项。</td> 
  </tr> 
  <tr> 
   <td>Types getTypeUtils()</td> 
   <td>返回实现Types接口的对象，用于操作类型的工具类。</td> 
  </tr> 
 </tbody> 
</table>

##### process 处理方法 #####

process方法提供了两个参数，第一个是我们请求处理注解类型的集合（也就是我们通过重写getSupportedAnnotationTypes方法所指定的注解类型），第二个是有关当前和上一次循环的信息的环境。

返回值表示这些注解是否由此 Processor 声明  
如果返回 true，则这些注解不会被后续 Processor 处理；  
如果返回 false，则这些注解可以被后续的 Processor 处理。

@Override
        public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        
            System.out.println("SzzTestProcessor.process.....;");
    
            return false;
        }

我们可以通过RoundEnvironment接口获取注解元素，注意annotations只是注解类型，并不知道哪些实例被注解标记了，RoundEnvironment是可以知道哪些被注解标记了的。

<table> 
 <thead> 
  <tr> 
   <th>方法</th> 
   <th>描述</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>Set&lt;? extends Element&gt; getElementsAnnotatedWith(Class&lt;? extends Annotation&gt; a)</td> 
   <td>返回被指定注解类型注解的元素集合。</td> 
  </tr> 
  <tr> 
   <td>Set&lt;? extends Element&gt; getElementsAnnotatedWith(TypeElement a)</td> 
   <td>返回被指定注解类型注解的元素集合。</td> 
  </tr> 
  <tr> 
   <td>processingOver()</td> 
   <td>如果循环处理完成返回true，否则返回false。</td> 
  </tr> 
 </tbody> 
</table>

关于这部分的使用介绍，请看下面的**自定义注解处理器范例**

### 如何注册注解处理器 ###

上面介绍了注解处理器的一些核心方法，那么我们**如何注册注解处理器呢**？

并不是说我们实现了**AbstractProcessor**类就会生效，由于**注解处理器(AbstractProcessor)** 是在编译期执行的，而且它是作为一个Jar包的形式来生效，所以我们需要将**注解处理器**作为一个单独的Module来打包。  
然后在需要使用到**注解处理器**的Module引用。

这个**注解处理器** 所在Module打包的时候需要注意：

因为AbstractProcessor本质上是通过**ServiceLoader**来加载的(SPI), 所以想要被成功注册上。则有两种方式

**一、配置SPI**

1.  在`resource/META-INF.services`文件夹下创建一个名为`javax.annotation.processing.Processor`的文件；里面的内容就是你的**注解处理器**的全限定类名  
    ![在这里插入图片描述][a3df4d33a96447c3b009f3ed668d5890.png]
2.  设置编译期间禁止处理 Process，之所以这样做是因为，如果你不禁止Process，ServiceLoader就会去加载你刚刚设置的**注解处理器**，但是因为是在编译期，Class文件被没有被成功加载，所以会抛出下面的异常
    
        服务配置文件不正确, 或构造处理程序对象javax.annotation.processing.Processor: Provider org.example.SzzTestProcessor not found时抛出异常错误
    
    如果是用Maven编译的话，请加上如下配置 `<compilerArgument>-proc:none</compilerArgument>`
    
        <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <version>3.5.1</version>
                        <configuration>
                            <source>1.8</source>
                            <target>1.8</target>
                        </configuration>
                        <executions>
                            <execution>
                                <id>default-compile</id>
                                <configuration>
                                    <compilerArgument>-proc:none</compilerArgument>
                                </configuration>
                            </execution>
                            <execution>
                                <id>compile-project</id>
                                <phase>compile</phase>
                                <goals>
                                    <goal>compile</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
3.  注解处理器打包成功，就可以提供给别的Module使用了

**二、使用@AutoService 自动配置SPI的配置文件**

@AutoService 是Google开源的一个小插件，它可以自动的帮我们生成`META-INF/services` 的文件,也就不需要你去手动的创建配置文件了。

当然，上面的 `<compilerArgument>-proc:none</compilerArgument>`参数也不需要了。

所以也就不会有编译期上述的问题`xxx not found`问题了。因为编译的时候`META-INF/services` 还没有配置你的**注解处理器**，也就不会抛出加载异常了。

例如下面，使用@AutoService(Processor.class)，他会自动帮我们生成对应的配置文件。

@AutoService(Processor.class)
    public class SzzBuildProcessor extends AbstractProcessor {
        
    
    }

![在这里插入图片描述][082ed57867b042d183c46360f8cf7875.png]

另外，实际上 **@AutoService** 自动生成配置文件也是通过AbstractProcessor来实现的。

具体的使用方式请看 ：[@AutoService 详解][AutoService]

### 如何调试编译期代码 ###

在我们自己写了注解处理器之后，可能想要调试，那么编译期的调试跟运行期的调试不一样。

请看：[如何在IDEA中调试编译期源码][IDEA]

### Maven相关配置(指定生效的Processor) ###

如果你使用的是Maven来编译，那么有一些参数可以设置

比如**指定注解处理器生效** 、代码生成的源路径。默认是 `target/generated-sources/annotations`

除非特殊情况，一般不需要设置这些参数。

<build>
        <plugins>
    
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                    
                    <generatedSourcesDirectory>${
        project.build.directory} /generated-sources/</generatedSourcesDirectory>
                     
                    <annotationProcessors>
                        <annotationProcessor>
                                org.example.SzzTestProcessor
                        </annotationProcessor>
                    </annotationProcessors>
                </configuration>
            </plugin>
    
        </plugins>
    </build>

### 注意事项 ###

**注解**和**注解处理器**是单独的module：**注解处理器**只需要在编译的时候使用，注解的Module只需要引入注解处理器的Jar包就行了。因此我们需要将注解处理器分离为单独的module。

并且打包的时候请先打包**注解处理器**的Module.

自定义Processor类最终是通过打包成jar，在编译过程中调用的。

### 自定义注解处理器范例 ###

#### 范例一： 自动生成Build构造器 ####

**1. 需求描述**

假设我们的注释用户模块中有一些简单的 POJO 类，其中包含几个字段：

public class Company {
        
    
        private String name;
    
        private String email ;
        
    }
    
    public class Personal {
        
    
        private String name;
    
        private String age;
    }

我们想创建对应的构建器帮助类来更流畅地实例化POJO类

Company company = new CompanyBuilder()
                    .setName("ali").build();
            Personal personal = new PersonalBuilder()
                    .setName("szz").build();

**2. 需求分析**

如果没有POJO都要手动的去创建对应的Build构建器，未免太繁杂了，我们可以通过注解的形式，去自动的帮我们的POJO类生成对应的Build构建器，但是当然不是每个都生成，按需生成；

1.  定义一个 @BuildProperty 注解，在需要生成对应的setXX方法的方法上标记注解
2.  自定义 **注解处理器**扫描@BuildProperty注解，按照需求自动生成Build构建器。例如CompanyBuilder
    
        public class CompanyBuilder {
              
        
            private Company object = new Company();
        
            public Company build() {
              
                return object;
            }
        
            public CompanyBuilder setName(java.lang.String value) {
              
                object.setName(value);
                return this;
            }
        
        }

**3. 编码**

创建一个注解处理器Module：**szz-test-processor-handler**

@BuildProperty

@Target(ElementType.METHOD) // 注解用在方法上
    @Retention(RetentionPolicy.SOURCE) // 尽在Source处理期间可用，运行期不可用
    public @interface BuildProperty {
        
    }

**注解处理器**

@SupportedAnnotationTypes("org.example.BuildProperty") // 只处理这个注解；
    public class SzzBuildProcessor extends AbstractProcessor {
        
    
        @Override
        public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        
            System.out.println("SzzBuildProcessor.process ;");
    
            for (TypeElement annotation : annotations) {
        
                // 获取所有被该注解 标记过的实例
                Set<? extends Element> annotatedElements = roundEnv.getElementsAnnotatedWith(annotation);
    
                // 按照需求 检查注解使用的是否正确 以set开头，并且参数只有一个
                Map<Boolean, List<Element>> annotatedMethods = annotatedElements.stream().collect(
                        Collectors.partitioningBy(element ->
                                ((ExecutableType) element.asType()).getParameterTypes().size() == 1
                                        && element.getSimpleName().toString().startsWith("set")));
    
                List<Element> setters = annotatedMethods.get(true);
                List<Element> otherMethods = annotatedMethods.get(false);
    
                // 打印注解使用错误的case
                otherMethods.forEach(element ->
                        processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR,
                                "@BuilderProperty 注解必须放到方法上并且是set开头的单参数方法", element));
    
                if (setters.isEmpty()) {
        
                    continue;
                }
    
    
                Map<String ,List<Element>> groupMap = new HashMap();
    
                // 按照全限定类名分组。一个类创建一个Build
                setters.forEach(setter ->{
        
                    // 全限定类名
                    String className = ((TypeElement) setter
                            .getEnclosingElement()).getQualifiedName().toString();
                    List<Element> elements = groupMap.get(className);
                    if(elements != null){
        
                        elements.add(setter);
                    }else {
        
                        List<Element> newElements = new ArrayList<>();
                        newElements.add(setter);
                        groupMap.put(className,newElements);
                    }
                });
    
                
                groupMap.forEach((groupSetterKey,groupSettervalue)->{
        
                    //获取 类名SimpleName 和 set方法的入参
                    Map<String, String> setterMap = groupSettervalue.stream().collect(Collectors.toMap(
                            setter -> setter.getSimpleName().toString(),
                            setter -> ((ExecutableType) setter.asType())
                                    .getParameterTypes().get(0).toString()
                    ));
                    try {
        
                        // 组装XXXBuild类。并创建对应的类文件
                        writeBuilderFile(groupSetterKey,setterMap);
                    } catch (IOException e) {
        
                        throw new RuntimeException(e);
                    }
    
                });
            }
    
            // 返回false 表示 当前处理器处理了之后 其他的处理器也可以接着处理，返回true表示，我处理完了之后其他处理器不再处理
            return true;
        }
    
        private void writeBuilderFile(
                String className, Map<String, String> setterMap)
                throws IOException {
        
    
            String packageName = null;
            int lastDot = className.lastIndexOf('.');
            if (lastDot > 0) {
        
                packageName = className.substring(0, lastDot);
            }
    
            String simpleClassName = className.substring(lastDot + 1);
            String builderClassName = className + "Builder";
            String builderSimpleClassName = builderClassName
                    .substring(lastDot + 1);
    
            JavaFileObject builderFile = processingEnv.getFiler()
                    .createSourceFile(builderClassName);
    
            try (PrintWriter out = new PrintWriter(builderFile.openWriter())) {
        
    
                if (packageName != null) {
        
                    out.print("package ");
                    out.print(packageName);
                    out.println(";");
                    out.println();
                }
    
                out.print("public class ");
                out.print(builderSimpleClassName);
                out.println(" {");
                out.println();
    
                out.print("    private ");
                out.print(simpleClassName);
                out.print(" object = new ");
                out.print(simpleClassName);
                out.println("();");
                out.println();
    
                out.print("    public ");
                out.print(simpleClassName);
                out.println(" build() {");
                out.println("        return object;");
                out.println("    }");
                out.println();
    
                setterMap.entrySet().forEach(setter -> {
        
                    String methodName = setter.getKey();
                    String argumentType = setter.getValue();
    
                    out.print("    public ");
                    out.print(builderSimpleClassName);
                    out.print(" ");
                    out.print(methodName);
    
                    out.print("(");
    
                    out.print(argumentType);
                    out.println(" value) {");
                    out.print("        object.");
                    out.print(methodName);
                    out.println("(value);");
                    out.println("        return this;");
                    out.println("    }");
                    out.println();
                });
    
                out.println("}");
            }
        }
    
        @Override
        public synchronized void init(ProcessingEnvironment processingEnv) {
        
            super.init(processingEnv);
            System.out.println("----------");
    
            System.out.println(processingEnv.getOptions());
    
        }
        @Override
        public SourceVersion getSupportedSourceVersion() {
        
            return SourceVersion.latestSupported();
        }
    
    
    }

**4. 注册注解处理器**

![在这里插入图片描述][af976c28c06e4c50af82f9fc336c99bc.png]

**5. 配置编译参数**

因为这里选择的是手动配置了 `META-INF.services`; 所以我们需要配置一下编译期间忽略Processor；  
主要参数就是

如下所示

<build>
            <pluginManagement>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-compiler-plugin</artifactId>
                        <version>3.5.1</version>
                        <configuration>
                            <source>1.8</source>
                            <target>1.8</target>
                        </configuration>
                        <executions>
                            <execution>
                                <id>default-compile</id>
                                <configuration>
                                    <compilerArgument>-proc:none</compilerArgument>
                                </configuration>
                            </execution>
                            <execution>
                                <id>compile-project</id>
                                <phase>compile</phase>
                                <goals>
                                    <goal>compile</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
    
                 </plugins>
    
            </pluginManagement>
    
        </build>

**6. 执行编译打包**

mvn install一下, 其他Module就可以引用了。

**7. Demo Module 依赖注解处理器**

创建一个新的Module： **szz-test-demo** ; 让它依赖上面的 **szz-test-processor-handler**

并在Company的一些方法上使用注解。  
![在这里插入图片描述][387a4953829742e29c16599dea672356.png]

**8. Demo Module 进行编译，会自动生成BuildCompany类**

Demo Module 编译之后，就会在target文件夹生成BuildXXX类。 并且只有我们用注解BuildProperty标记了的方法才会生成对应的方法。  
而且如果注解BuildProperty使用的方式不对，我们也会打印出来了异常。  
![在这里插入图片描述][b91cdf2904644e67a4df7da1d50b42eb.png]

#### 范例二： ####

待补充。

### 如何给编译期设置入参 ###

在init初始化的接口中，我们可以获取到编译器的一些自定义参数;

String verify = processingEnv.getOptions().get("自定义key");

注意这个获取到的编译器参数只能获取的是以`-A开头`的参数，因为是过滤之后的

![在这里插入图片描述][97e7fca83d104774ad781d9e566b746b.png]

那么这个自定义参数从哪里设置的呢？

**如果你是IDEA 编译**

`-Akey=value 或者 -Akey`

![在这里插入图片描述][c23cd1507e26482aacc920a498eeda46.png]

**如果是用Maven编译**

![在这里插入图片描述][394e58cfdeaa4509a1ba54abe62a2bea.png]

[Java]: https://blog.csdn.net/u010634066/article/details/80384125
[a3df4d33a96447c3b009f3ed668d5890.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/a91a4640b3da4d1abe7cbb025a281fb8.png
[082ed57867b042d183c46360f8cf7875.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/ed79d2d615f74efca376eaaeff6920b4.png
[AutoService]: https://szzdzhp.blog.csdn.net/article/details/129923721
[IDEA]: https://szzdzhp.blog.csdn.net/article/details/129948032
[af976c28c06e4c50af82f9fc336c99bc.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/47e6a153a01849c7b44a06d970cd34d5.png
[387a4953829742e29c16599dea672356.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/444a0d0c83a64114b763fef4e95da69f.png
[b91cdf2904644e67a4df7da1d50b42eb.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/92c58b8b2dbc4ce1b5724b89cebb868b.png
[97e7fca83d104774ad781d9e566b746b.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/a8654694e7684b23868b8675606124d5.png
[c23cd1507e26482aacc920a498eeda46.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/a07d7d3f488a47a691ca002d3d5c5658.png
[394e58cfdeaa4509a1ba54abe62a2bea.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/24/34e159ef38054880bddf28a0dfb68104.png