Java 注解详解

一、注解的本质

注解的本质是继承了 Annotation 的接口，如下示例：

public interface Override extends Annotation{
    
}

注解可以理解为一种特殊的标注，利用注解，可以执行编译检测、生成辅助代码等等。

总而言之，注解作为标注，本身没有意义，它依赖解析器来实现它的价值。

二、注解的作用

注解的用途有很多，我们使用的很多第三库都使用了注解，如 ButterKnife、EventBus、ARouter。

这样说太过笼统，我们可以把 Java 代码从编译到运行分为几个阶段，来分析不同阶段注解如何发挥作用。

1. 编译期

即 java 代码编译成 class 字节码之前。该时期注解发挥作用的例子有很多。

如 @Override 注解会在该时期检测父类中是否有同名方法，检测不通过则编译失败。

EventBus3.0 也在该时期通过扫描获取 @Subscribe() 注解并解析、处理其中所包含的信息，然后生成 java 类来保存所有订阅者关于订阅的信息。

以上例子中，注解在编译期间即可发挥价值，编译成 class 后反而不再需要。因此注解提供了生命周期参数（元注解 Retention）来决定注解保留的阶段。这里生命周期参数对应 RetentionPolicy.SOURCE。即注解在编译期保留，但编译成 class 则丢弃。

Retention 用来定义注解的生命周期，RetentionPolicy.SOURCE 是它的参数之一，这个后续会讲，不用深究。

虽然 EventBus3.0 在编译期处理注解，但这不代表 EventBus3.0 使用的 @Subscribe() 注解生命周期为 RetentionPolicy.SOURCE，相反，它的生命周期为 RetentionPolicy.RUNTIME，这是因为 EventBus3.0 不止在编译期处理订阅者，如果运行时发现没有该订阅，还会尝试通过反射获取。

2. 字节码期

即通过解析字节码中的注解，达成特定功能。

这个我见的实例还真不多。

不过我能想到的场景是，字节码插桩时，通过分析注解，插入特定代码。

这里注解在 class 及之前均可见，JVM 加载后不再需要。对应注解的生命周期参数为 RetentionPolicy.CLASS，即注解会写入 class 文件，但是在类加载后丢弃。

3. 运行期

运行时通过反射获取被注解的函数、变量等，然后依据注解类型做特殊处理。

如 EventBus 2.x，在调用注册后，会通过反射将该 Object 内注解的函数及其参数保存起来，以供后续事件总线跳转。

这里注解要求在运行时可见，对应注解的生命周期参数为 RetentionPolicy.RUNTIME，即注解会一直保留到运行时。

作用总结

下图说明了注解在对应阶段发挥对应作用的实例，以及注解在不同阶段对应的生命周期参数。

注解

三、元注解

即定义注解的注解，上面生命周期参数即为元注解之一。Java 有以下几个元注解：

元注解	作用
@Target	定义注解的作用范围
@Retention	定义注解的生命周期
@Documented	定义注解是否应当被包含在 JavaDoc 文档中
@Inherited	定义是否允许子类继承该注解

下面分析常用的 @Target 和 @Retention。

1、@Target

修饰注解的作用范围，它有以下可选值：

取值	作用
ElementType.TYPE	允许被修饰的注解作用在类、接口和枚举上
ElementType.FIELD	允许作用在属性字段上
ElementType.METHOD	允许作用在方法上
ElementType.PARAMETER	允许作用在方法参数上
ElementType.CONSTRUCTOR	允许作用在构造器上
ElementType.LOCAL_VARIABLE	允许作用在本地局部变量上
ElementType.ANNOTATION_TYPE	允许作用在注解上
ElementType.PACKAGE	允许作用在包上

2、@Retention

描述注解的生命周期。它的取值有如下三个：

① RetentionPolicy.SOURCE：

编译器可见，不会写入到 class 里。

② RetentionPolicy.CLASS：

class 可见，类加载后丢弃。

③ RetentionPolicy.RUNTIME：

永久保存，运行时可以反射获取。

RUNTIME 反射相比 SOURCE 编译期处理注解逻辑，运行效率必然有所影响。所以很多第三方开源库选择 SOURCE 期处理注解。

四、元注解的实战

虽然编译期处理注解常见于第三方库，但需要借助 APT（注解处理器）来完成。APT 不是本文重点，后续会单出博客来讲，所以这里实战选择 运行时通过反射处理注解。

本次实战的目的在于实现类似 ButterKnife 的效果，即通过注解代替 findViewById。

1、定义注解

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Binding {

    int value();
}

注解的作用范围设置为成员变量；注解的生命周期因为要运行时反射，所以设置为 RUNTIME；value 即我们 findViewById() 时要用到的 id。

2、定义注解解析器

下面是一个简单的注解解析器。

public class BindingHelper {

    public static void binding(Activity aty) {
        if (aty == null) {
            return;
        }
        Class clazz = aty.getClass();
        Field[] fields = clazz.getDeclaredFields();
        // 1.遍历成员变量
        for (Field field : fields) {
            field.setAccessible(true);
            // 2.判断该变量是否被Binding注解了
            if (field.isAnnotationPresent(Binding.class)) {
                Binding binding = field.getAnnotation(Binding.class);
                // 3.判断field是否是view类型
                if (binding != null && View.class.isAssignableFrom(field.getType())) {
                    int id = binding.value();
                    try {
                        // 4.findViewById
                        field.set(aty, aty.findViewById(id));
                    } catch (IllegalAccessException e) {
                        e.printStackTrace();
                    }
                }
            }
        }
    }
}

3、调用

public class MainActivity extends AppCompatActivity {

    @Binding(value = R.id.tvTitle)
    private TextView mTitleView;

    @Binding(R.id.tvContent)
    private TextView mContentView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        BindingHelper.binding(this);

        mTitleView.setText("测试标题");
        mContentView.setText("测试内容");
    }
}

以上便使用注解自动完成了成员变量的 findViewById。

其它说明

Android 开发中经常用到注解代替枚举，如下：

@StringDef({Color.RED, Color.BLUE})
@Retention(RetentionPolicy.SOURCE)
public @interface Color {

    String RED = "#FF0000";
    String BLUE = "#0000FF";
}

其中 @StringDef 是 Android 提供的注解，并非元注解，只有定义了它才能实现编译告警，但也只是告警，仍然可以编译通过。

五、Java 常用注解

除元注解外，JDK 还预定义了另外三种注解。

1、@Override

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.SOURCE)
public @interface Override {
}

修饰方法为重写方法。

2、@Deprecated

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
}

标记成员变量、方法、包等等过时。使用过时方法不会导致编译不通过，仅仅是警告：JDK 已经不再推荐使用该方法或者类，建议使用其它替代者。

3、@SuppressWarnings

@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
public @interface SuppressWarnings {
    String[] value();
}

取消编译器告警。

六、Android 常用注解

同样，Android support library 也提供了属于 Android 自己的注解库 -- support-annotations。

使用 Android 注解库需要添加依赖

dependencies {
    implementation 'com.android.support:support-annotations:28.0.0'
}

需要注意俩点：

如果模块依赖于某个注解处理器，必须使用 annotationProcessor 依赖项配置来添加该依赖项。
如果使用的是 appcompat 库，则无需添加 support-annotations 依赖项，因为 appcompat 库已经依赖于注解库。

1、Typedef 注解

如 @StringDef、@IntDef、@LongDef 等等。

@Retention(SOURCE)
@Target({ANNOTATION_TYPE})
public @interface StringDef {
    String[] value() default {};
    boolean open() default false;
}

该类注释可以确保特定参数、返回值或字段引用一组特定的常量，另外还提供了代码补全功能。

用法参考元注解实战 -- 其它说明。

2、Null 性注解

@Nullable @NonNull

@Documented
@Retention(CLASS)
@Target({METHOD, PARAMETER, FIELD, LOCAL_VARIABLE, ANNOTATION_TYPE, PACKAGE})
public @interface Nullable {
}

@Documented
@Retention(CLASS)
@Target({METHOD, PARAMETER, FIELD, LOCAL_VARIABLE, ANNOTATION_TYPE, PACKAGE})
public @interface NonNull {
}

标记参数、返回值等等是否可为空。常用，就不举例子了...

3、资源注解

如 @LayoutRes、@StringRes、@DrawableRes、@DimenRes、@ColorRes 和 @InterpolatorRes。

@Documented
@Retention(CLASS)
@Target({METHOD, PARAMETER, FIELD, LOCAL_VARIABLE})
public @interface LayoutRes {
}

用于限定参数、返回值等的资源类型。最常见的，setContentView(int id)：

@Override
public void setContentView(@LayoutRes int layoutResID) {
    getDelegate().setContentView(layoutResID);
}

4.其它 Android 注解

其它 Android 注解可以参考我的另一篇博客，或参考官网。

以前写的 Android 注解博客对注解理解不完全，有些概念混淆视听，但对 Android 各个注解的说明、测试仍有参考价值。

七、总结

Java 提供了元注解，来限定注解的各个属性。如 @Target、@Retention。
Java 还利用元注解创建了另外几种注解。如 @Override、@Deprecated、@SuppressWarnings。
Android 为方便开发、协作，也利用元注解创建了自己的注解库。如 @Nullable、@CallSuper、@Keep 等等。

注解在不同生命周期里，有不同的实现价值的方式。如：
SOURCE 注解在编译期，可以通过 APT 扫描注解，辅助生成特定 Java 代码；（例：ARouter 生成路由文件）
CLASS 注解在字节码期，获取注解后，实现特定代码插桩。（例：在指定注解下插入日志代码）
RUNTIME 注解在运行期，可以通过反射获取注解，实现指定功能。（例：自定义注解 findViewById；EventBus 反射获取注解的订阅者）

注意： RUNTIME 包括了 SOURCE 的生命周期范围，但开发时应本着最小暴露的原则，可以 SOURCE 期使用的注解，没必要设置成 RUNTIME 一直保留下去，这也是出于安全考虑。

本文为了实现简单，讲解了如何利用生命周期为 RUNTIME 的注解来实现 findViewById() 功能。
下一篇将通过学习 APT，讲解如何利用生命周期为 SOURCE 的注解来辅助生成 Java 代码。

[TOC]