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

2020-08-23 本文已影响0人彭旭锐

前言

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

延伸文章

关于反射，请阅读：《Java | 反射：在运行时访问类型信息（含 Kotlin）》
关于注解处理器（APT），请阅读：《Java | 注解处理器（APT）原理解析 & 实践》
关于编译过程，请阅读：《Java | 聊一聊编译过程（编译前端 & 编译后端）》
关于Class文件，请阅读：《Java | 请概述一下 Class 文件的结构》

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章）—— 周志明著