Android注解--初探

为什么要学注解

要想看懂很多开源库，如Arouter, dagger,Butter Knife等，不得不先看懂注解；
想更好地提升开发效率和代码质量，注解可以帮上很大的忙；

本文主要介绍注解开发的大概概念，算是入个门，如果想实践，请关注后续文章

一、什么是注解

java.lang.annotation，接口 Annotation，在JDK5.0及以后版本引入。
注解是代码里的特殊标记，这些标记可以在编译、类加载、运行时被读取，并执行相应的处理。通过使用Annotation，开发人员可以在不改变原有逻辑的情况下，在源文件中嵌入一些补充的信息。代码分析工具、开发工具和部署工具可以通过这些补充信息进行验证、处理或者进行部署。

在运行时读取需要使用Java反射机制进行处理。

Annotation不能运行，它只有成员变量，没有方法。Annotation跟public、final等修饰符的地位一样，都是程序元素的一部分，Annotation不能作为一个程序元素使用。
其实大家都是用过注解的，只是可能没有过深入了解它的原理和作用，比如肯定见过@Override,@Deprecated等。

1、注解的作用

注解将一些本来重复性的工作，变成程序自动完成，简化和自动化该过程。比如用于生成Java doc，比如编译时进行格式检查，比如自动生成代码等，用于提升软件的质量和提高软件的生产效率。

2、注解都有哪些

平时我们使用的注解有来自JDK里包含的，也有Android SDK里包含的，也可以自定义。

2.1、JDK定义的元注解

Java提供了四种元注解，专门负责新注解的创建工作，即注解其他注解。

@target 定义了Annotation所修饰的对象范围

ElementType.CONSTRUCTOR:用于描述构造器
ElementType.FIELD:用于描述域
ElementType.LOCAL_VARIABLE:用于描述局部变量
ElementType.METHOD:用于描述方法
ElementType.PACKAGE:用于描述包
ElementType.PARAMETER:用于描述参数
ElementType.TYPE:用于描述类、接口(包括注解类型) 或enum声明

@retention 定义了该Annotation被保留的时间长短，取值

RetentionPoicy.SOURCE:注解只保留在源文件，当Java文件编译成class文件的时候，注解被遗弃；用于做一些检查性的操作，比如 @Override 和 @SuppressWarnings
RetentionPoicy.CLASS:注解被保留到class文件，但jvm加载class文件时候被遗弃，这是默认的生命周期；用于在编译时进行一些预处理操作，比如生成一些辅助代码（如 ButterKnife）
RetentionPoicy.RUNTIME:注解不仅被保存到class文件中，jvm加载class文件之后，仍然存在；用于在运行时去动态获取注解信息。

@documented 标记注解，用于描述其它类型的注解应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化，不用赋值。

@inherited 标记注解，允许子类继承父类的注解。这里一开始有点理解不了，需要断句一下，允许子类继承父类的注解。示例：

Target(value = ElementType.TYPE)  
@Retention(RetentionPolicy.RUNTIME)  
@Inherited  
public @interface Sample {   
    public String name() default "";      
}


@Sample  
class Test{  
}  

class Test2 extents Test{  
}

这样类Test2其实也有注解@sample 。

2.2 JDK内置的其他注解

Android 开发中经常使用各种资源常量 R.XXX 来引用各种资源。例如图片资源和字符串资源。这些常量都是 int 类型的，在代码检测的时候没法判断引用的资源是否有错误，比如本来需要一个字符串资源，结果在代码写的时候用了一个颜色资源，这种情况只有通过测试才能发现，有些极端情况可能测试也不容易发现。资源类型注解就是为了解决该问题的，资源注解包含如下几种：

资源类型注解

@AnimatorRes 表明该参数、变量或者函数返回值应该是一个 Animator 类型的资源
@AnimRes 表明该参数、变量或者函数返回值应该是一个 Anim 类型的资源
@AnyRes 表明该参数、变量或者函数返回值应该是一个任意类型的资源
@ArrayRes 表明该参数、变量或者函数返回值应该是一个 Array 类型的资源
@AttrRes 表明该参数、变量或者函数返回值应该是一个 attribute 类型的资源
@BoolRes 表明该参数、变量或者函数返回值应该是一个布尔类型的资源
@ColorInt 表明该参数、变量或者函数返回值应该是一个颜色值而不是颜色资源引用，例如应该是一个 AARRGGBB 的整数值。
@ColorRes 表明该参数、变量或者函数返回值应该是一个 color 类型的资源，而不是颜色值。注意和 ColorInt 区别
@DimenRes 表明该参数、变量或者函数返回值应该是一个 dimension 类型的资源
@DrawableRes 表明该参数、变量或者函数返回值应该是一个 drawable 类型的资源
@FractionRes 表明该参数、变量或者函数返回值应该是一个 fraction 类型的资源
@IdRes 表明该参数、变量或者函数返回值应该是一个资源的 ID 类型
@IntegerRes 表明该参数、变量或者函数返回值应该是一个整数类型的资源
@LayoutRes 表明该参数、变量或者函数返回值应该是一个 layout 布局文件类型的资源
@MenuRes 表明该参数、变量或者函数返回值应该是一个 menu 类型的资源
@PluralsRes 表明该参数、变量或者函数返回值应该是一个 plurals 类型的资源
@RawRes 表明该参数、变量或者函数返回值应该是一个 raw 类型的资源
@StringRes 表明该参数、变量或者函数返回值应该是一个字符串类型的资源
@StyleableRes 表明该参数、变量或者函数返回值应该是一个 styleable 类型的资源
@StyleRes 表明该参数、变量或者函数返回值应该是一个 style 类型的资源
@TransitionRes 表明该参数、变量或者函数返回值应该是一个 transition 类型的资源
@XmlRes 表明该参数、变量或者函数返回值应该是一个 XML 类型的资源

线程注解类型

线程注解用来检测一个函数是否在指定类型的线程中执行。有四个：

@UiThread
@MainThread
@WorkerThread
@BinderThread

注意：其中 @UiThread 和 @MainThread 是可替换用的，大部分应用中，这两个是一样的。
如果一个类中的所有函数都在同一个线程内执行，可以在类名称上面用这个注解即可。

权限注解类型

@RequiresPermission 用来表明该函数执行需要一个或者多个权限，如果你没有声明这些权限，则会给出警告。例如：

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
    public abstract void setWallpaper(Bitmap bitmap) throws IOException;

    @RequiresPermission(allOf = {
            Manifest.permission.READ_HISTORY_BOOKMARKS,
            Manifest.permission.WRITE_HISTORY_BOOKMARKS})
    public static final void updateVisitedHistory(ContentResolver cr, String url, boolean real) {

    }

    @RequiresPermission(anyOf = {
            Manifest.permission.READ_HISTORY_BOOKMARKS,
            Manifest.permission.WRITE_HISTORY_BOOKMARKS})
    public static final void updateHistory(ContentResolver cr, String url, boolean real) {

    }

如果只要满足多个权限中的一个，用 anyOf；如果要满足多个权限，用 allOf.

参数为空性限制类：用于限制参数是否可以为空

@NonNull
@Nullable

类型范围限制类：用于限制标注值的值范围

@FloatRang
@IntRange

其他的功能性注解：

@CallSuper
@CheckResult
@ColorInt
@Dimension
@Keep
@Px
@RequiresApi
@RequiresPermission
@RestrictTo
@Size
@VisibleForTesting