Java | 这是一篇全面的注解使用攻略(含 Kotlin)

前言

  • 注解(Annotation)是 JDK 1.5 引进的机制,允许将额外的元数据信息关联到一个声明上。
  • 在这篇文章里,我将带你梳理Java & Kotlin注解的使用攻略,追求简单易懂又不失深度,如果能帮上忙,请务必点赞加关注!

延伸文章


目录

1. 基本概念

  • 问:什么是注解,为什么要使用注解?
    答:注解(Annotation)是一种添加到声明上的元数据(元数据是描述数据的数据)。相对于无注解代码,使用注解可以增强代码可读性、提供编译时检查、甚至可以结合注解处理器(APT)生成字节码。例如:

    void func(@NonNull String str) {
        str.toString(); 这里依然可能抛出 NullPointerException
    }
    func(null); 编译时 Warning
    

    这里使用@NonNull修饰了变量声明,表示参数str应接收一个非空值,否则编译时会警告。需要注意的是,虚拟机不会阻止一个空值传递进func(),方法内部依然可能抛出NullPointerException。如果你不理解,请看注解的本质:

  • 问:说一下注解的本质
    答:注解本质上是附加到声明上的一种额外补充信息,在编译后会被擦除,(有必要时)生成 Class 文件常量池属性,需要注意的是,注解对它所修饰的代码没有直接影响。具体来说,注解分为三种保留等级(Retention),见 2.4 节。


2. 注解的使用

2.1 声明 & 应用

在 Java 中,声明注解需要用到@Interface,注解内可以声明注解参数,用于在应用注解时传递实参。例如:

public @interface MyAnnotation {
    String value(); // 无默认值
    int num() default 1; // 默认值 1
}

以下几点需要注意下:

  • 注解是不能包含方法的(因为注解是附加到声明上的补充信息)
  • 注解实参必须是编译期已知的常量或类引用(因为编译后注解被固化到 Class 文件的注解属性中)
  • 应用注解时,每个注解参数都需要赋值,除非在声明注解时已经声明了默认值。另外,value命名的注解参数,在传值时可以省略参数名,这是一种简便写法,但是仅限给一个参数赋值的情况,例如:
以下三种语法效果相同:
@MyAnnotation("123") String str;
@MyAnnotation(value = "123") String str;
@MyAnnotation(value = "123",num = 1) String str;

在 Kotlin 中,注解的规则基本相同,语法上有所区别:

annotation class MyAnnotation(val value: String, val num: Int = 1)

2.2 元注解

元注解是用来修饰其他注解类型的注解,元注解都需要使用@Target(ANNOTATION_TYPE)修饰,JDK 内置的元注解有:

2.3 注解应用位置

使用@Target来限制注解的应用目标,默认为无限制。当存在多种应用目标时,存在多个时使用{}包裹多个目标,例如:

@Target({FIELD, PARAMETER, LOCAL_VARIABLE})
public @interface MyAnnotation {
}

在 Java 中,注解应用位置在 ElementType枚举中定义;在 Kotlin 中,注解应用位置在AnnotationTarget枚举中定义,Kotlin 的注解应用位置比 Java 更为丰富,具体如下:

引用自《Kotlin核心编程》

另外,考虑到 Kotlin 代码通常都拥有多重含义(例如一个可变属性其实相当于一个背域、一个 setter 和一个 getter),为了更精准控制注解位置,Kotlin 提供了精准注解语法,具体如下:

引用自《Kotlin核心编程》

2.4 注解保留级别

使用@Retention来声明注解的保留等级:

三种注解保留等级

2.5 JDK 内置注解

2.6 Kotlin 内置注解


3. 注解的运行时表示

前面我们提到,注解在编译后擦除,如果注解的保留级别为 CLASS & RUNTIME,在 Class 文件中还会生成对应的注解属性,而RUNTIME注解在类加载过程中会保留在 Class 对象中,因此可以通过反射获取注解信息:

3.1 反射获取运行时注解信息

Java 将注解属性包装为Annotation,所有注解都实现Annotation接口:

public interface Annotation {
    boolean equals(Object var1);

    int hashCode();

    String toString();

    Class<? extends Annotation> annotationType();
}

每一种注解应用目标都提供了getAnnotation()方法获得修饰的注解。
Editting...


4. 注解的应用场景

4.1 代替简单枚举

枚举的本质是特殊的静态成员变量,相对于静态常量,枚举占用内存更大。因此一些简单的枚举应该尽可能用注解代替,例如:

使用枚举:
public enum Type {
    START,END
}

Type type = Type.START;
---------------------------------------------------------
使用注解:
@Target({FIELD, PARAMETER, LOCAL_VARIABLE}) // 严谨起见
@Retention(RetentionPolicy.SOURCE)
@IntDef({Type.START, Type.END})
public @interface Type {
    int START = 0;
    int END = 1;
}

@Type int type = Type.START;

需要注意的是,因为使用了SOURCE注解,所以注解只会在编写源码时提供代码提示,不会影响编译过程。

4.2 运行时注解信息

在运行时,可以通过反射动态获得注解信息(限RUNTIME注解),通常是做一些逻辑判断,具体见第 3 节。

4.3 注解处理器(APT)

注解处理是Java编译前端处理过程中,程序员可控性最强的一个阶段,在很多开源框架中(Glide、EventBus、Tinker、ARouter),都可以看到注解处理器的身影。在这篇文章里,我们详细讨论:《Java | 注解处理器(APT)原理解析 & 实践》,请关注!

4.4 字节码增强

在编译出 Class 文件后,可以通过修改 Class 文件内容来修改程序逻辑,举个例子,我们可以定义一个应用于点击事件方法上的注解,并利用注解参数用来限制点击事件触发频率。在这篇文章里,我们详细讨论:《Android | 使用 AspectJ 限制按钮快速点击》,请关注!


5. 总结

注解是一种添加到声明上的元数据,需要注意的是,注解在编译后被擦除,CLASS & RUNTIME注解会保留到 Class 文件的注解属性中,而RUNTIME注解在类加载后会保存在 Class 对象,可以反射获取。


参考资料

  • 《Kotlin实战》 (第10章)—— [俄] Dmitry Jemerov,Svetlana Isakova 著
  • 《Kotlin 核心编程》(第8章) —— 水滴技术团队 著
  • 《Java编程思想》 (第19、23章)—— [美] Bruce Eckel 著
  • 《深入理解Java虚拟机(第3版)》(第6、8、10章)—— 周志明 著

推荐阅读

感谢喜欢!你的点赞是对我最大的鼓励!欢迎关注彭旭锐的简书!