【转】深入浅出Android Support Annotation
【转自】http://jcodecraeer.com/a/anzhuokaifa/androidkaifa/2015/0427/2797.html
http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html
英文链接：http://anupcowkur.com/posts/a-look-at-android-support-annotations/
译文链接 深入浅出Android Support Annotations
导读：如果你之前遇到过在方法参数前面有@NonNull的情况却不知道它是干什么的，这篇文章将解答你的疑问。
原文如下：
在Android Support Library19.1版本中，Android工具小组引入了几个很酷的注解类型，供开发者在工程中使用。Support Library自身也使用这些注解，这是一个好兆头。就让我们好好研究下。 通过gradle可以很容易的把这些注解添加到我们的工程中：
compile 'com.android.support:support-annotations:20.0.0'
有三种类型的注解可供我们使用：
-
Nullness注解；
-
资源类型注解；
-
IntDef和StringDef注解；
我们将通过代码例子来讲解每一种类型的作用以及在工程中如何使用它们。
Nullness注解
使用@NonNull注解修饰的参数不能为null。在下面的代码例子中，我们有一个取值为null的name变量，它被作为参数传递给sayHello函数，而该函数要求这个参数是非null的String类型：
public class MainActivity extends ActionBarActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
String name = null;
sayHello(name);
}
void sayHello(@NonNull String s) {
Toast.makeText(this, "Hello " + s, Toast.LENGTH_LONG).show();
}
}
由于代码中参数String s使用@NonNull注解修饰，因此IDE将会以警告的形式提醒我们这个地方有问题：
如果我们给name赋值，例如String name = “Our Lord Duarte”，那么警告将消失。使用@Nullable注解修饰的函数参数或者返回值可以为null。假设User类有一个名为name的变量，使用 User.getName()访问，那么我们可以编写如下代码：
public class MainActivity extends ActionBarActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
User user = new User("Our Lord Duarte");
Toast.makeText(this, "Hello " + getName(user), Toast.LENGTH_LONG).show();
}
@Nullable
String getName(@NonNull User user) {
return user.getName();
}
}
因为getName函数的返回值使用@Nullable修饰，所以调用：
Toast.makeText(this, "Hello " + getName(user), Toast.LENGTH_LONG).show();
没有检查getName的返回值是否为空，将可能导致crash。
资源类型注解
是否曾经传递了错误的资源整型值给函数，还能够愉快的得到本来想要的整型值吗？资源类型注解可以帮助我们准确实现这一点。在下面的代码中，我们的sayHello函数预期接受一个字符串类型的id，并使用@StringRes注解修饰：
public class MainActivity extends ActionBarActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
sayHello(R.style.AppTheme);
}
void sayHello(@StringRes int id) {
Toast.makeText(this, "Hello " + getString(id), Toast.LENGTH_LONG).show();
}
}
而我们传递了一个样式资源id给它，这时IDE将提示警告如下：
类似的，我们把警告的地方使用一个字符串资源id代替警告就消失了：
sayHello(R.string.name);
IntDef和StringDef注解
我们要介绍的最后一种类型的注解是基于Intellij的“魔术常量”检查机制（http://blog.jetbrains.com/idea/2012/02/new-magic-constant-inspection/）（我们不需要详细了解这个机制具体是如何实现的，想了解的话可以点击链接）。
很多时候，我们使用整型常量代替枚举类型（性能考虑），例如我们有一个IceCreamFlavourManager类，它具有三种模式的操 作：VANILLA，CHOCOLATE和STRAWBERRY。我们可以定义一个名为@Flavour的新注解，并使用@IntDef指定它可以接受的值类型。
public class IceCreamFlavourManager {
private int flavour;
public static final int VANILLA = 0;
public static final int CHOCOLATE = 1;
public static final int STRAWBERRY = 2;
@IntDef({VANILLA, CHOCOLATE, STRAWBERRY})
public @interface Flavour {
}
@Flavour
public int getFlavour() {
return flavour;
}
public void setFlavour(@Flavour int flavour) {
this.flavour = flavour;
}
}
这时如果我们使用错误的整型值调用IceCreamFlavourManager.setFlavour时，IDE将报错如下：
IDE甚至会提示我们可以使用的有效的取值：
我们也可以指定整型值作为标志位，也就是说这些整型值可以使用’｜’或者’&’进行与或等操作。如果我们把@Flavour定义为如下标志位：
@IntDef(flag = true, value = {VANILLA, CHOCOLATE, STRAWBERRY})
public @interface Flavour {
}
那么可以如下调用：
iceCreamFlavourManager.setFlavour(IceCreamFlavourManager.VANILLA & IceCreamFlavourManager.CHOCOLATE);
@StringDef用法和@IntDef基本差不多，只不过是针对String类型而已。
关于将来计划增加哪些新的注解类型或者这些注解的依赖以及和Intellij自身的注解如何交互等等问题，可以查看网址：http://tools.android.com/tech-docs/support-annotations。
我们可以使用@CheckResult注解来让使用者知道该函数的返回值是需要使用的，没有使用函数的返回值则Android Studio会给出警告提示：
@KEEP
最近我发现一个新的support annotation注解@Keep。根据support annotations文档说明，这个注解还没有被关联到Gradle插件中，被这个注解修饰的函数或者类，在代码混淆进行压缩时会被保持住。你会知道当尝试把某个特定的函数或者类从优化操作中排除掉是多么痛苦的事情。使用这个注解将会告诉Proguard不要对指定的函数或者类进行优化操作：
public class Example { @Keep public void doSomething() { // hopefully this method does something } ... }
我自己写了一个例子：
package com.kale.lib.utils; import android.content.Context; import android.os.Looper; import android.support.annotation.IntDef; import android.support.annotation.NonNull; import android.widget.Toast; /** * @author Jack Tony * @date 2015/4/29 */ public class EasyToast { @IntDef({Toast.LENGTH_SHORT, Toast.LENGTH_LONG}) public @interface Length { } public static void makeText(@NonNull Context context, int msg) { makeText(context,String.valueOf(msg)); } public static void makeText(@NonNull Context context, String msg) { if (context != null) { Toast.makeText(context, msg, Toast.LENGTH_SHORT).show(); } } public static void makeText(@NonNull Context context, int msg, @Length int length) { makeText(context,String.valueOf(msg),length); } public static void makeText(@NonNull Context context, String msg, @Length int length) { if (length == Toast.LENGTH_SHORT || length == Toast.LENGTH_LONG) { if (context != null) { Toast.makeText(context, msg, length).show(); } } } public static void makeTextInThread(@NonNull final Context context, int msg) { makeTextInThread(context, String.valueOf(msg)); } public static void makeTextInThread(@NonNull Context context, String msg) { makeTextInThread(context, msg, Toast.LENGTH_SHORT); } public static void makeTextInThread(@NonNull Context context, int msg, @Length int length) { makeTextInThread(context,String.valueOf(msg),length); } public static void makeTextInThread(@NonNull final Context context, final String msg, @Length final int length) { new Thread() { @Override public void run() { Looper.prepare();//先移除 Toast.makeText(context, msg, length).show(); Looper.loop();// 进入loop中的循环，查看消息队列 } }.start(); } }
资源类型注解
Android的资源值通常都是使用整型传递。这意味着获取一个drawable使用的参数，也能很容易的传递给一个获取string的方法；因为他们都是int类型，编译器很难区分。
资源类型注解可以在这种情况下提供类型检查。比如一个被@StringRes住进诶的int类型参数，如果传递一个不是R.string类型的引用将会被IDE标注：
以ActionBar为例:
import android.support.annotation.StringRes;
...
public abstract void setTitle(@StringRes int resId);
有很多不同资源类型的注解：如下的每一个Android资源类型：
@StringRes, @DrawableRes, @ColorRes, @InterpolatorRes,等等。一般情况下，如果有一个foo类型的资源，那么它的相应的资源类型注解就是FooRes.
除此之外，还有一个名为@AnyRes特殊的资源类型注解。它被用来标注一个未知的特殊类型的资源，但是它必须是一个资源类型。比如在框架中，它被用在Resources#getResourceName(@AnyRes int resId)上，使用的时候，你可以这样getResources().getResourceName(R.drawable.icon)用，也可以getResources().getResourceName(R.string.app_name)这样用，但是却不能这样getResources().getResourceName(42)用。
请注意，如果你的API支持多个资源类型，你可以使用多个注解来标注你的参数。
IntDef/StringDef: 类型定义注解
整型除了可以作为资源的引用之外，也可以用作“枚举”类型使用。
@IntDef和”typedef”作用非常类似，你可以创建另外一个注解，然后用@IntDef指定一个你期望的整型常量值列表，最后你就可以用这个定义好的注解修饰你的API了。
appcompat库里的一个例子：
import android.support.annotation.IntDef;
...
public abstract class ActionBar {
...
@IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
@Retention(RetentionPolicy.SOURCE)
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);
上面非注解的部分是现有的API。我们创建了一个新的注解(NavigationMode)并且用@IntDef标注它,通过@IntDef我们为返回值或者参数指定了可用的常量值。我们还添加了@Retention(RetentionPolicy.SOURCE)告诉编译器这个新定义的注解不需要被记录在生成的.class文件中(译者注：源代码级别的，生成class文件的时候这个注解就被编译器自动去掉了)。
使用这个注解后，如果你传递的参数或者返回值不在指定的常量值中的话，IDE将会标记出这种情况。
你也可以指定一个整型是一个标记性质的类型；这样客户端代码就通过|，&等操作符同时传递多个常量了：
@IntDef(flag=true, value={
DISPLAY_USE_LOGO,
DISPLAY_SHOW_HOME,
DISPLAY_HOME_AS_UP,
DISPLAY_SHOW_TITLE,
DISPLAY_SHOW_CUSTOM
})
@Retention(RetentionPolicy.SOURCE)
public @interface DisplayOptions {}
最后，还有一个字符串版本的注解，就是@StringDef，它和@IntDef的作用基本上是一样，所不同的是它是针对字符串的。该注解一般不常用，但是有的时候非常有用，比如在限定向Activity#getSystemService方法传递的参数范围的时候。
要了解关于类型注解的更多详细信息，请参考
https://developer.android.com/tools/debugging/annotations.html#enum-annotations
线程注解: @UiThread, @WorkerThread, …
(Support library 22.2及其之后版本支持.)
如果你的方法只能在指定的线程类型中被调用，那么你就可以使用以下4个注解来标注它：
- @UiThread
- @MainThread
- @WorkerThread
- @BinderThread
如果一个类中的所有方法都有相同的线程需求，那么你可以注解类本身。比如android.view.View，就被用@UiThread标注。
关于线程注解使用的一个很好的例子就是AsyncTask：
@WorkerThread
protected abstract Result doInBackground(Params... params);
@MainThread
protected void onProgressUpdate(Progress... values) {
}
如果你在重写的doInBackground方法里尝试调用onProgressUpdate方法或者View的任何方法，IDE工具就会马上把它标记为一个错误：
@UiThread还是@MainThread?
在进程里只有一个主线程。这个就是@MainThread。同时这个线程也是一个@UiThread。比如activity的主要窗口就运行在这个线程上。然而它也有能力为应用创建其他线程。这很少见，一般具备这样功能的都是系统进程。通常是把和生命周期有关的用@MainThread标注，和View层级结构相关的用@UiThread标注。但是由于@MainThread本质上是一个@UiThread，而大部分情况下@UiThread又是一个@MainThread，所以工具(lint ,Android Studio,等等)可以把他们互换，所以你能在一个可以调用@MainThread方法的地方也能调用@UiThread方法，反之亦然。
RGB颜色整型
当你的API期望一个颜色资源的时候，可以用@ColorRes标注，但是当你有一个相反的使用场景时，这种用法就不可用了，因为你并不是期望一个颜色资源id，而是一个真实的RGB或者ARGB的颜色值。
在这种情况下，你可以使用@ColorInt注解，表示你期望的是一个代表颜色的整数值：
public void setTextColor(@ColorInt int color)
有了这个，当你传递一个颜色id而不是颜色值的时候，lint就会标记出这段不正确的代码：
值约束: @Size, @IntRange, @FloatRange
如果你的参数是一个float或者double类型，并且一定要在某个范围内，你可以使用@FloatRange注解：
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {
如果有人使用该API的时候传递一个0-255的值，比如尝试调用setAlpha(128)，那么工具就会捕获这一问题：
(你也可以指定是否包括起始值。)
同样的，如果你的参数是一个int或者long类型，你可以使用@IntRange注解约束其值在一个特定的范围内：
public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }
把这些注解应用到参数上是非常有用的，因为用户很有可能会提供错误范围的参数，比如上面的setAlpha例子，有的API是采用0-255的方式，而有的是采用0-1的float值的方式。
最后，对于数据、集合以及字符串，你可以用@Size注解参数来限定集合的大小(当参数是字符串的时候，可以限定字符串的长度)。
举几个例子
- 集合不能为空: @Size(min=1)
- 字符串最大只能有23个字符: @Size(max=23)
- 数组只能有2个元素: @Size(2)
- 数组的大小必须是2的倍数 (例如图形API中获取位置的x/y坐标数组: @Size(multiple=2)
权限注解: @RequiresPermission
如果你的方法的调用需要调用者有特定的权限，你可以使用@RequiresPermission注解：
@RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;
如果你至少需要权限集合中的一个，你可以使用anyOf属性：
@RequiresPermission(anyOf = {
Manifest.permission.ACCESS_COARSE_LOCATION,
Manifest.permission.ACCESS_FINE_LOCATION})
public abstract Location getLastKnownLocation(String provider);
如果你同时需要多个权限，你可以用allOf属性：
@RequiresPermission(allOf = {
Manifest.permission.READ_HISTORY_BOOKMARKS,
Manifest.permission.WRITE_HISTORY_BOOKMARKS})
public static final void updateVisitedHistory(ContentResolver cr, String url, boolean real) {
对于intents的权限，可以直接在定义的intent常量字符串字段上标注权限需求(他们通常都已经被@SdkConstant注解标注过了):
@RequiresPermission(android.Manifest.permission.BLUETOOTH)
public static final String ACTION_REQUEST_DISCOVERABLE =
"android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";
对于content providers的权限，你可能需要单独的标注读和写的权限访问，所以可以用@Read或者@Write标注每一个权限需求：
@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");
方法重写: @CallSuper
如果你的API允许使用者重写你的方法，但是呢，你又需要你自己的方法(父方法)在重写的时候也被调用，这时候你可以使用@CallSuper标注：
@CallSuper
protected void onCreate(@Nullable Bundle savedInstanceState) {
用了这个后，当重写的方法没有调用父方法时，工具就会给予标记提示：
(Android Studio 1.3 Preview 1的lint检查有个关于这个注解的bug，这个bug就是即使是对的重写也会报错，这个bug已经在Preview 2版本修改，可以通过canary channel更新到Preview 2版本。)
返回值: @CheckResult
如果你的方法返回一个值，你期望调用者用这个值做些事情，那么你可以使用@CheckResult注解标注这个方法。
你并不需要微每个非空方法都进行标注。它主要的目的是帮助哪些容易被混淆，难以被理解的API的使用者。
比如，可能很多开发者都对String.trim()一知半解，认为调用了这个方法，就可以让字符串改变以去掉空白字符。如果这个方法被@CheckResult标注，工具就会对那些没有使用trim()返回结果的调用者发出警告。
Android中，Context#checkPermission这个方法已经被@CheckResult标注了：
@(suggest="#enforcePermission(String,int,int,String)")
public abstract int checkPermission(@NonNull String permission, int pid, int uid);
这是非常重要的，因为有些使用context.checkPermission的开发者认为他们已经执行了一个权限 —-但其实这个方法仅仅只做了检查并且反馈一个是否成功的值而已。如果开发者使用了这个方法，但是又不用其返回值，那么这个开发者真正想调用的可能是这个Context#enforcePermission方法，而不是checkPermission。
@VisibleForTesting
你可以把这个注解标注到类、方法或者字段上，以便你在测试的时候可以使用他们。
参考自：http://www.jianshu.com/p/1d0faca34a6e?utm_source=www.race604.com
IntelliJ注解
IntelliJ，Android Studio就是基于它开发的，IntelliJ有一套它自己的注解；IntDef分析其实重用的是MagicConstant分析的代码，IntelliJ null分析其实用的是一组配置好的null注解。如果你执行Analyze > Infer Nullity…，它会试图找出所有的null约束并添加他们。这个检查有时会插入IntelliJ注解。你可以通过搜索,替换为Android注解库的注解，或者你也可以直接用IntelliJ注解。在build.gradle里或者通过Project Structure对话框的Dependencies面板都可以添加如下依赖：
dependencies {
compile 'com.intellij:annotations:12.0'
}
