预知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,如图:image.png

在 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 会提示错误:

image.png

类型定义注解

在 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 文件就是抽取出来的注解信息

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值