预知Bug的神器——Support Annotation Library使用详解

Support Annotation Library 是从 Android Support Library 19.1 开始引入的一个全新的函数库，它包含了一系列有用的元注解，用来帮助开发者在编译期间发现可能存在的 Bug。

Annotation Library 默认情况下不会包含在工程中，如果我们的 SDK 已经安装了 Android Support Repository，那么我们可以通过打开工程的 Project Structure 对话框，并选中一个 Module，选中 DependDencies 选项卡，点击 “+” 按钮，在弹出的 Choose library Dependency 对话框中轻松找到 Annotation Library，如图：

在 support-annotations:28.0.0-alpha1 函数包中，总共包含 39 种注解，下面我们按照类型分别进行介绍。

Nullness 注解

该类型下的注解只有两个

• @Nullable：作用于函数参数或者返回值，标记参数或者返回值可以为 null
• @NotNull：作用于参数或者返回值，标记参数或者返回值不可以为 null

当出现这种违反标记的代码时，Android Studio 会给出提示，同时使用 Android Lint 进行静态代码扫描，也会显示出错提示。

资源类型注解

我们知道资源在 Android 中通常是以整型值表示的，并保存在 R.Java 文件中。这意味着一个需要传入 Layout 资源值得函数，如果传入 String 资源值不会再编译期报错，只有在运行时执行到相应的代码才能发现问题，则使用资源类型注解可以防止这种情况的出现。

资源类型的注解作用于函数参数，返回值及类的变量，每种资源类型对应一个注解：

AnimatorRes：标记整型值是 android.R.animator 类型
AnimRes：标记整型值是 android.R.anim 类型
AnyRes：标记整型值是任何一种资源类型，如果确切知道是哪一种具体资源的话，建议显式指定
ArrayRes：标记整型值是 android.R.array 类型
AttrRes：标记整型值是 android.R.attr 类型
BoolRes：标记整型值是布尔类型
ColorRes：标记整型值是 android.R.color 类型
DrawableRes：标记整型值是 android.R.drawable 类型
FractionRes：标记整型值是 fraction 类型，这个比较少见，这种类型的资源常见于 Animation Xml 中，比如 50%p，表示占 parent 的 50%
IdRes：标记整型值是 android.R.id 类型
IntegerRes：标记整型是 android.R.inter 类型
InterpolatorRes：标记整型值是 android.R.interpoloator 类型
LayoutRes：标记整型值是 android.R.layout 类型
MenuRes：标记整型值是 android.R.menu 类型
PluralsRes：标记整型值是 android.R.plurals 类型
RawRes：标记整型值是 android.R.raw 类型
StringRes：标记整型值是 android.R.string 类型
StyleableRes：标记整型值是 android.R.styleable 类型
StyleRes：标记整型值是 android.R.style 类型
TransitionRes：标记整型值是 android.R.transition 类型
XmlRes：标记整型值是 android.R.xml 类型

来看一个例子，就比如我们的 AppCompatActivity的setContentView 函数就是使用了 LayoutRes 注解表示它的参数：

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

使用 LayoutRes 注解标记后，如果我们在函数中调用 setContentView 函数时传入的参数不是 R.layout 类型，而是其他资源类型（例如 R.id 类型）那么 Android Studio 会提示错误：

类型定义注解

在 Android 开发中，整型值不只经常用来代表资源引用值，而且经常用来代替枚举值，@IntDef 注解用来创建一个整型类型定义的新注解，我们可以使用这个心注解来标记自己编写的 API，而 @IntDef 在我们常用的 ActionBar 这个类中就可以找到具体的使用方式：

public abstract class ActionBar {
//定义可以接收的常量列表
@IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
//定义 NavigationMode 注解
public @interface NavigationMode {}
//定义常量
public static final int NAVIGATION_MODE_STANDARD = 0;
public static final int NAVIGATION_MODE_LIST = 1;
public static final int NAVIGATION_MODE_TABS = 2;

@NavigationMode
public abstract int getNavigationMode();

public abstract void setNavigationMode(@NavigationMode int mode);
......

在使用 setNavigationMode 这个 API 时，如果传入的参数 mode 不是三个常量值之一，那么 Android Studio 就会给出警告。

线程注解

Android 应用开发过程中，经常会涉及多线程的使用，界面相关操作必须在主线程，而耗时操作例如文件下载等则需要放到后台线程中，线程相关注解有四种。

• @UiThread：标记运行在 UI 线程，一个 UI 线程是 Activity 运行所在的主窗口，对于一个应用而言，可能粗才能在多个 UI 线程，每个 UI 线程对应不同的主窗口。
• @MainThread：标记运行在主线程，一个应用只有一个主线程，主线程也是 @UIThread 线程，通常情况下，我们使用 @MainThread 来注释申明周期相关函数，使用 @UIThread 来注解视图相关函数，一般情况下，@MainThread 和 @UIThread 是可互换使用的。
• @WorkerThread：标记运行在后台线程
• @BinderThread：标记运行在 Binder 线程

一个典型的例子是 AsyncTask 的实现，我们看下内部实现：

@MainThread
protected void onPreExecute(){}
@WorkerThread
protected abstract Result doInBackground(Params ... params){};
@MainThread
protected void onProgressUpdate(Progress ... values){};

RGB颜色值注解

在资源类型中使用 @ColorRes 来标记参数类型需要传入颜色类型的资源 id，@ColorInt 注解则是标记参数类型需要传入 RGB 或者 ARGB 颜色整型值。在 TextView 的源码中可以找到使用 @Color 的例子。

public void setTextColor(@ColorInt int color){
  mTextColor = ColorStateList.valueOf(color);
  updateTextColors();
}

值范围注解

当函数的取值范围在一定范围内时，可以使用值范围注解来防止调用者传入错误的参数，这种类型主要有三种注解

• @Size:对于类似数组、集合和字符串之类的参数，我们可以使用 @Size 注解来标识这些参数的大小，用法如下：
  – @Size(min=1)：表示集合不可以为空
  –@Size(max=23)：表示字符串最大字符个数是 23
  –@Size(2)：表示数组元素个数是 2 个
  –@Size(multiple=2)：表示数组的大小必须是 2 的倍数

• @IntRange：表示参数类型是 int 或者 long

 public void setAlpha(@IntRange(from=0,to=255) int alpha) {...}

• @FloatRange：表示参数类型是 float 或者 double

 public void setAlpha(@FloatRange(from=0.0,to=1.0) int alpha) {...}

权限注解

Android 应用在使用某些系统功能是，需要在 AndroidManifest.xml 中申明权限，否则在运行时会提示缺失对应的权限。为了在编译器及时发现缺失的权限，我们可以使用 @RequiresPermission 注解

• 如果函数调用需要声明一个权限，语句如下：

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

• 如果函数调用需要声明集合中最少一个权限，语句如下：

@ RequiresPermission(anyof = {
Manifest.permission.ACCESS_COARSE_LOCATION,
Manifest.permission.ACCESS.FINE_LOCATION})
public abstract void setWallpaper(Bitmap bitmap) throws IOException;

重写函数注解

如果 API 运行调用者重写某个函数，但同时要求重写的函数需要调用被重写的函数，否则代码逻辑可能会错误，那么可以使用 @CallSuper 注解来进行提示，语句如下：

@CallSuper
protected void onCreate(@Nullable Bundle saveInstanceState);

返回值注解

如果我们编写的函数需要调用者对返回值做某些处理，那么可以使用@CheckResult 注解来进行提示。当然我们没有必要对每个非空返回值的函数都添加这个注解，该注解的主要目的是让调用者在使用 API 时不至于怀疑该函数是否会产生副作用。在 Android 源码中，Context 类的 checkPremission 函数使用了该注解(自行查看吧）

@VisibleForTesting

单元测试中可能需要访问到一些不可见的类、函数或者变量，这时可以使用 @VisibleForTesting 注解来使其对测试可见

@Keep

@Keep 注解用来标记在 Proguard 混淆过程中不需要混淆的类或者方法。如果你曾经在编写混淆文件时使用过，那么 @Keep 的用法很简单

- keep class com.foo.bar {public static <methods> }

如果有了 @Keep 注解，则可以在代码编写过程中对不需要混淆的类或者方法直接标记即可
“`
public class AnnotaionDemo{
@Keep
public void doSomething(){
…..
}
……
}

最后说明一下，如果函数库中使用 Annotation Library，并使用 Gradle 生成 aar 压缩包，那么在编译时 Android Gradle 插件会抽出这些注解信息并打包在 aar 文件中，以便函数库的调用者正常使用我们的注解信息。aar 文件中的 annotation.zip 文件就是抽取出来的注解信息