Java 编译时注解 —— 入门教程

Love The Way You Lie 2023-09-29 19:22 6阅读 0赞

为什么要写这一系列的博客呢？

因为在 Android 开发的过程中， 泛型，反射，注解这些知识进场会用到，几乎所有的框架至少都会用到上面的一两种知识，如 Gson 就用到泛型，反射，注解，Retrofit 也用到泛型，反射，注解 。学好这些知识对我们进阶非常重要，尤其是阅读开源框架源码或者自己开发开源框架。

[java Type 详解][java Type]

[java 反射机制详解][java]

[注解使用入门（一）][Link 1]

[Android 自定义编译时注解1 - 简单的例子][Android _1 -]

[Android 编译时注解 —— 语法详解][Android _ _]

[带你读懂 ButterKnife 的源码][ButterKnife]

经过前面的介绍，相信大家对注解有了一定的了解了。

根据注解使用方法和用途，我们可以将Annotation分为三类：

*  JDK内置系统注解（如 @SuppressWarnings(“deprecation”)，@override 等）
 *  元注解 如（@Documented ，@Retention() ，@Target()，@Documented ）
 *  自定义注解 （自己实现的的注解）

### 元注解 ###

*元注解 解析说明*

*  @Documented 是否会保存到 Javadoc 文档中
 *  @Retention 保留时间，可选值， 默认为 CLASS
    
    > SOURCE（源码时），CLASS（编译时），RUNTIME（运行时）
 *  @Target 可以用来修饰哪些程序元素，如 TYPE, METHOD, CONSTRUCTOR, FIELD, PARAMETER 等，未标注则表示可修饰所有

ANONOTATION_TYPE(注解类型声明），
    PACKAGE（包）
    TYPE （类，包括enum及接口，注解类型）
    METHOD （方法）
    CONSTRUCTOR （构造方法）
    FIFLD （成员变量）
    PARAMATER （参数）
    LOCAL_VARIABLE （局部 变量）

*  @Inherited 是否可以被继承，默认为 false

需要注意的是注解是不可以继承的，@Inherited 的意思是 加入我们把注解应用到 A 类中，B 类继承 A ，那么 B 可以扫描到 A 的注解。

#### 注解的继承”（依赖倒置？） ####

这里讲的继承并不是通过@Inherited修饰的注解。

这个“继承”是一个注解的使用技巧，使用上的感觉类似于依赖倒置，来自于ButterKnife源码。

先看代码。

@Target(METHOD)
    @Retention(CLASS)
    @ListenerClass(
        targetType = "android.view.View",
        setter = "setOnClickListener",
        type = "butterknife.internal.DebouncingOnClickListener",
        method = @ListenerMethod(
            name = "doClick",
            parameters = "android.view.View"
        )
    )
    public @interface OnClick {
          /** View IDs to which the method will be bound. */
          int[] value() default { View.NO_ID };
    }

这是ButterKnife的OnClick 注解。特殊的地方在于@OnClick修饰了注解@ListenerClass，并且设置了一些只属于@OnClick的属性。

那这样的作用是什么呢？

凡是修饰了@OnClick的地方，也就自动修饰了@ListenerClass。类似于@OnClick是@ListenerClass的子类。而ButterKnife有很多的监听注解@OnItemClick、@OnLongClick等等。

这样在做代码生成时，不需要再单独考虑每一个监听注解，只需要处理@ListenerClass就OK。如 @interface OnItemClick 等。

@Target(METHOD)
    @Retention(CLASS)
    @ListenerClass(
        targetType = "android.widget.AdapterView<?>",
        setter = "setOnItemClickListener",
        type = "android.widget.AdapterView.OnItemClickListener",
        method = @ListenerMethod(
            name = "onItemClick",
            parameters = {
                "android.widget.AdapterView<?>",
                "android.view.View",
                "int",
                "long"
            }
        )
    )
    public @interface OnItemClick {
      /** View IDs to which the method will be bound. */
      @IdRes int[] value() default { View.NO_ID };
    }

--------------------

### 自定义注解 ###

一个简单的自定义注解例子

@Documented()
    // 表示是基于编译时注解的
    @Retention(RetentionPolicy.CLASS)
    // 表示可以作用于成员变量，类、接口
    @Target({ElementType.FIELD, ElementType.TYPE}) 
    public @interface Seriable {
         
     
    }

指定默认值

@Documented()
    // 表示是基于编译时注解的
    @Retention(RetentionPolicy.CLASS)
    // 表示可以作用于成员变量，类、接口
    @Target({ElementType.FIELD, ElementType.TYPE}) 
    public @interface Seriable {
         int id();
         String name() default "test";
    }
    
    //使用
    @Seriable(id = 1) //name有默认值可以不写
    class Test{
    }

关于怎样自定义一个注解，可以参看这一篇博客，[Android 自定义编译时注解1 - 简单的例子][Android _1 -]

--------------------

### 处理器类Processor编写 ###

自定义注解后，需要编写Processor类处理注解。Processor 继承自 AbstractProcessor 的类。我们主要需要处理以下连个方法。

*  public Set getSupportedAnnotationTypes()
 *  public abstract boolean process(Set<? extends TypeElement> annotations,  
    RoundEnvironment roundEnv);

#### getSupportedAnnotationTypes 方法 ####

重写 getSupportedAnnotationTypes 方法：告知Processor哪些注解需要处理。返回一个Set集合，集合内容为 *自定义注解的包名+类名*。

建议项目中这样编写：

@Override
    public Set<String> getSupportedAnnotationTypes() {
        Set<String> types = new LinkedHashSet<>();
        //需要全类名
        types.add(Seriable.class.getCanonicalName()); 
        types.add(Println.class.getCanonicalName());
        return types;
    }

另外如果注解数量很少的话，可以通过另一种方式实现：

//在只有一到两个注解需要处理时，可以这样编写：
    @SupportedAnnotationTypes({"com.example.Seriable"})
    @SupportedSourceVersion(SourceVersion.RELEASE_7)
    public class JsonProcessor extends AbstractProcessor {
    }

#### process 方法 ####

process 方法，这个方法是所有方法中最关键的一个方法，他用来处理注解的相关信息，比如提取注解的信息，存进 map 集合或者生成代码等。

@Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
    
        return false;
    }

public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        //   第一步，根据我们自定义的注解拿到 elememts set 集合
        Set<? extends Element> elememts = roundEnv.getElementsAnnotatedWith(Seriable.class);
        TypeElement typeElement;
        VariableElement variableElement;
     
        //  第二步： 根据 element 的类型做相应的处理，并存进 map 集合
        for (Element element : elememts) {
            ElementKind kind = element.getKind();
            // 判断该元素是否为类
            if (kind == ElementKind.CLASS) {
                typeElement = (TypeElement) element;
                // 判断该元素是否为成员变量
            } else if (kind == ElementKind.FIELD) {
                variableElement = (VariableElement) element;
               
            
            }
        }
    
      
    
        return true;
    }

### Element ###

元素，虽有通过注解取得的元素都以 Element 等待处理,它的具体类型与我们通过 @Target 来标记的具有一定的联系。

官方的解释是这样的：

> Represents a program element such as a package, class, or method.Each element represents a static, language-level construct  
> (and not, for example, a runtime construct of the virtual machine)

表示程序元素如包、类或者方法。每个元素代表一个静态语言级构造(例如,而不是运行时构建的虚拟机）

例如：

// 第一步，根据我们自定义的注解拿到 elememts set 集合
        Set<? extends Element> elememts = roundEnv.getElementsAnnotatedWith(Seriable.class);
        TypeElement typeElement;
        VariableElement variableElement;
     
        //  第二步： 根据 element 的类型做相应的处理，并存进 map 集合
        for (Element element : elememts) {
            ElementKind kind = element.getKind();
            // 判断该元素是否为类
            if (kind == ElementKind.CLASS) {
                typeElement = (TypeElement) element;
                // 判断该元素是否为成员变量
            } else if (kind == ElementKind.FIELD) {
                variableElement = (VariableElement) element;
               
            
            }
        }

#### Element 的子类 ####

Element 的子类有：

*  ExecutableElement

表示某个类或接口的方法、构造方法或初始化程序（静态或实例），包括注释类型元素。

对应@Target(ElementType.METHOD) @Target(ElementType.CONSTRUCTOR)

*  PackageElement;

表示一个包程序元素。提供对有关包极其成员的信息访问。

对应@Target(ElementType.PACKAGE)

*  TypeElement;

表示一个类或接口程序元素。提供对有关类型极其成员的信息访问。

对应@Target(ElementType.TYPE)

**注意：枚举类型是一种类，而注解类型是一种接口。**

*  TypeParameterElement;

表示一般类、接口、方法或构造方法元素的类型参数。

对应@Target(ElementType.PARAMETER)

*  VariableElement;

表示一个字段、enum常量、方法或构造方法参数、局部变量或异常参数。

对应 @Target(ElementType.LOCAL\_VARIABLE)

#### 判断 Element 具体属于哪一种子类 ####

我们可以通过 element.getKind(); 来得到 Element 到底是哪一种类别，该方法返回 ElementKind 类型，我们在根据 ElementKind 即可得出 Element 到底是哪种类别。

ElementKind kind = element.getKind();
    // 判断该元素是否为类
    if (kind == ElementKind.CLASS) {
        typeElement = (TypeElement) element;
    } else if (kind == ElementKind.FIELD) {
       variableElement = (VariableElement) element;
    }

看到这里，想起前面的一篇博客 [java Type 详解][java Type] ，我们需要注意 Type 与 Element 的区别。

**Type 是用来处理泛型的，Element 是用来处理注解的。**

--------------------

### 题外话 ###

注解语法暂时介绍到这里，以后想到新的，会逐步更新到这篇博客，下一篇，将分析 ButterKnife 源码。

### **相关博客推荐** ###

[java Type 详解][java Type]

[java 反射机制详解][java]

[注解使用入门（一）][Link 1]

[Android 自定义编译时注解1 - 简单的例子][Android _1 -]

[Android 编译时注解 —— 语法详解][Android _ _]

[带你读懂 ButterKnife 的源码][ButterKnife]

扫一扫，欢迎关注我的微信公众号 **stormjun94（徐公码字）**， 目前是一名程序员，不仅分享 Android开发相关知识，同时还分享技术人成长历程，包括个人总结，职场经验，面试经验等，希望能让你少走一点弯路。

![c3b15414b23f957ac9383e9e169fe86e.jpeg][]

[java Type]: http://blog.csdn.net/gdutxiaoxu/article/details/68926515
[java]: http://blog.csdn.net/gdutxiaoxu/article/details/68947735
[Link 1]: http://blog.csdn.net/gdutxiaoxu/article/details/52017033
[Android _1 -]: http://blog.csdn.net/gdutxiaoxu/article/details/70244169
[Android _ _]: http://blog.csdn.net/gdutxiaoxu/article/details/70822023
[ButterKnife]: http://blog.csdn.net/gdutxiaoxu/article/details/71512754
[c3b15414b23f957ac9383e9e169fe86e.jpeg]: https://img-blog.csdnimg.cn/img_convert/c3b15414b23f957ac9383e9e169fe86e.jpeg