• 翻译：Andriod支持注解(Annotations)
• Android 支持注解
• 添加库到你的工程里
  • Nullness 注解
  • 资源注解
  • 线程注解
  • 值限制注解
  • CheckResult Annotations
• 写在最后
• 参考

Android 支持注解

这篇博客，我们将要说说Android Support Annotations 库，以及我们需要关注它。

support library 19.1版引入一个新的注解包，这个注解包里面有一系列有用的注解,使用它能很方便地捕获bugs。这些注解将会帮助 Android studio 来检测你代码里可能的错误并报告给你。在版本22.2中，这些注解进一步丰富了，新增了13个注解。

添加库到你的工程里

默认情况下，你的项目里没有注解库，因为它是一个独立的库。如果你使用appcompat库，则你可以使用这些注解，因为appcompat库依赖于它。

不管哪种情况, 为了在项目中使用注解, 添加以下代码到你的build.gradle文件中。

compile 'com.android.support:support-annotations:<latest-library-version>'

这些注解基于它们的使用和功能的相似性组合在一起，并根据这些分组，我们有以下注解类：

• NULL的含量注解
• 资源注释
• 线程注释
• 值约束注解
• 其他是：权限注解，CheckResults注解和CallSuper注解。

Nullness 注解

@Nullable and @NonNull annotations 用于检查变量、参数以及方法的返回值是否为null。 @NonNull annotation 意味着变量、参数以及方法的返回值不能是null. 如果违法了注解规则，Android studio产生一条警告信息。例如:

//pass a null argument to a method annotated as @NonNull
doubleNumber(null);

public int doubleNumber(@NonNull int num) {
    return num * 2;
}

@Nullable 意味着变量的值可以是null, 如果注解用于方法，则指明方法的返回值可以是null。 不论何时使用@Nullable注解, 都应该在变量和方法返回值上做Null检查。

资源注解

因为在Android中，资源是做为一个整数在传递的, 一段期望字符串id的代码,可以传递一个指向drawable的整形值，这种情况下编译器居然是可以接受的。资源类型注解允许在这种情况下检查资源的类型。譬如添加一个@StringRes的注解, 能确保传递的是字符串资源，如果是其它资源，IDE就会标志。

public void setButtonText(@StringRes int id) {
     //set text on some button
}

//this will be flagged by the IDE
setButtonText(R.drawable.icon);

每个android资源类型都有相应的资源类型注解。譬如有 @DrawableRes, @ColorRes, @InterpolatorRes等等. 总得原则是,如果资源类型是“Foo”,那么相应的注解就是“FooRes”.

最后, 有一个特别的资源注解，它是@AnyRes表明是个资源，但不明确到底是什么资源类型.

线程注解

线程注解检查一个方法是否在特定的线程类型中被调用。支持的线程注解有:

• @UiThread
• @MainThread
• @WorkerThread
• @BinderThread
  @MainThread 和 @UiThread 注解是可以互换的。

当类中的方法全都在同样类型的线程中调用时，可以把注解直接加到类上。一个演示线程注解使用的好例子是在AsyncTask中

@WorkerThread
protected abstract Result doInBackground(Params... params);

@MainThread
protected void onProgressUpdate(Progress... values) {
}

如果onProgressUpdate方法不是在主线程中调用,IDE就会标志一个错误出来。

值限制注解

@IntRange, @FloatRange and @Size annotations 用于验证参数的有效性。 @IntRange annotation 验证参数的值是在指定的整数范围内. 下面这个例子中,setAlpha方法会检查alpha的值是从0到255。

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

@FloatRange 类似，验证参数是在指定的浮点数范围内. @Size annotation 有点不一样, 它用于检查集合或数组的大小, 也用于检查字符串长度. @Size(min=1) annotation 用于检查数组非空, @Size(2) annotation 检查数组刚好有两个元素。

CheckResult Annotations

这个用于确保方法的返回值确实有使用。主要目的是帮助在使用一些API的时候，去使用它的返回值，而不是理所当然地认为函数有边际效应。在官方文档中有解释，一个好的例子是字符串。
trim 方法, 会让Java开发新手误用，认为方法调用完，字符串的值已经去掉了空白符。trim 方法使用@CheckResult注解。当调用者使用了trim方法，又没有使用返回值时，IDE就会标志。

@CheckResult
public String trim(@NonNull String string) {
    //remove whitespace from string
}

String s = "hello world ";

//this will make the IDE flag an error since the result from the @CheckResult
//annotated method is not used
s.trim();

其他值得关注的注解还有 @CallSuper, @Keep and @RequiresPermission. 完整的列表请参考官方的文档。

写在最后

使用注解支持库可以帮助我们更好地理解代码意图。它使用的代码结果是可预测的，同时方便其它开发人员整合你的代码，也方便你将来再次修改它。

更多关于Android的文章可以参考演道网

参考

Improve code Inspection with Annotations – Android developer doc

Support Annotation documentation

http://michaelevans.org/blog/2015/07/14/improving-your-code-with-android-support-annotations/

原文：http://mayojava.github.io/android/android-support-annotations/?utm_source=Android+Weekly&utm_campaign=c0a2159802-Android_Weekly_222&utm_medium=email&utm_term=0_4eb677ad19-c0a2159802-337909737