一、关于Annotations
support-annotations是google为我们提供的一个支持库，这个库包含了一些很实用的注解，当然你也可以定义你自己的注释上去，帮你捕获一些bugs。
Annotations 可以给代码检查工具提供一些提示，来帮助检查微妙的代码问题。
Annotations以元数据的方式添加到 变量、参数、一个方法中的输入参数、返回值等。
当使用了代码检查工具， annotations 可以帮助检查这些问题，比如空指针异常和资源文件类型冲突。
二、Nullness Annotations 参数
@Nullable and @NonNull annotations 可以检查一个变量、参数或返回值的null情况。
1 @Nullable
注释表明使用的的参数或者返回值可以为null
2 @NonNull
该注释表明使用的参数或者返回值不能为null
如果本地变量已知为空，并且我们申明了@NonNull, IDE会使用Warn警告提醒存在潜在的崩溃。
import android.support.annotation.NonNull;
...
/** Add support for inflating the <fragment> tag. */
@NonNull
@Override
public View onCreateView(String name, @NonNull Context context,
@NonNull AttributeSet attrs) {
...
}
...
3 Nullability Analysis
Android Studio 支持通过nullability 分析来在代码中动态的推断和插入nullness annotations。
在 Android Studio 中 进行 nullability的检查，选择Analyze > Infer Nullity。
Android Studio会插入 @Nullable and @NonNull annotations 在需要检查的位置。在空指针分析完成后，最好检验一下被注入的annotations。
4 Resource Type Annotations(资源类型annotations)
Resource Annotations 校验传入的参数是否为指定的资源类型
AnimatorRes ：animator资源类型
AnimRes：anim资源类型
AnyRes：任意资源类型
ArrayRes：array资源类型
AttrRes：attr资源类型
BoolRes：boolean资源类型
ColorRes：color资源类型
DimenRes：dimen资源类型。
DrawableRes：drawable资源类型。
FractionRes：fraction资源类型
IdRes：id资源类型
IntegerRes：integer资源类型
InterpolatorRes：interpolator资源类型
LayoutRes：layout资源类型
MenuRes：menu资源类型
PluralsRes：plurals资源类型
RawRes：raw资源类型
StringRes：string资源类型
StyleableRes：styleable资源类型
StyleRes：style资源类型
TransitionRes：transition资源类型
XmlRes：xml资源类型
import android.support.annotation.StringRes;
...
public abstract void setTitle(@StringRes int resId);
...
5 Thread Annotations
Thread annotations 校验一个方法是否在指定的线程中被调用。有以下4中类型：
@UiThread
@MainThread
@WorkerThread
@BinderThread
//@MainThread and the @UiThread 可以互换。
6 Value Constraint Annotations
@IntRange, @FloatRange, @Size 校验传递过来的参数值。
@IntRange 校验是否在指定的整形范围内。例子说明 alpha 参数包含在 0 ~ 255 之间：
public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }
@FloatRange 检验是否在指定的浮点型范围内。比如确保alpha参数在0.0 to 1.0之间：
public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}
@Size 校验一个容器或数组的长度。比如，使用@Size(min=1) 来检查一个容器不为空，使用@Size(2)来校验容器确定只有两个值。比如 确定location 数组知识包含一个元素：
int[] location = new int[3];
button.getLocationOnScreen(@Size(min=1) location);
@IntRange 校验是否在指定的整形范围内。例子说明 alpha 参数包含在 0 ~ 255 之间：
public void setAlpha(@IntRange(from=0,to=255) int alpha) { … }
6 Permission Annotations
@RequiresPermission 校验方法调用者的权限。 anyOf 属性用于检查满足一种一个， allOf属性用于检查满足所有 attribute.
setWallpaper 方法必须要有permission.SET_WALLPAPERS 权限.
@RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;
@RequiresPermission(allOf = {
Manifest.permission.READ_EXTERNAL_STORAGE,
Manifest.permission.WRITE_EXTERNAL_STORAGE})
public static final void copyFile(String dest, String source) {
...
}
7 CheckResults Annotations
使用@CallSuper 注解 校验 覆写的方法 需要调用父类的实现方法。
例子，覆写onCreate的方法必须调用super.onCreate()。
@CallSuper
protected void onCreate(Bundle savedInstanceState) {}
8 Enumerated Annotations
使用 @IntDef 和 @StringDef 注解 可以创建一个integer 和 string 类型的集合用来校验 其他变量的引用类型，比如传入set中的引用类型。
import android.support.annotation.IntDef;
...
public abstract class ActionBar {
...
//Define the list of accepted constants
@IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
//Tell the compiler not to store annotation data in the .class file
@Retention(RetentionPolicy.SOURCE)
//Declare the NavigationMode annotation
public @interface NavigationMode {}
//Declare the constants
public static final int NAVIGATION_MODE_STANDARD = 0;
public static final int NAVIGATION_MODE_LIST = 1;
public static final int NAVIGATION_MODE_TABS = 2;
//Decorate the target methods with the annotation
@NavigationMode
public abstract int getNavigationMode();
//Attach the annotation
public abstract void setNavigationMode(@NavigationMode int mode);
译代码的时候，如果mode 类型不在定义中的(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, or NAVIGATION_MODE_TABS)时，会有警告产生。
使用flag 可以检查一个参数或者返回值是否引用类型是否在指定的格式中。
import android.support.annotation.IntDef;
...
@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 {}
...
三、Annotations的使用Demo
1 先添加Android Support Repository的支持
打开 SDK Manager， 并选中 Android Support Repository，安装向导中点击 Continue 直到完成安装。
2 build.gradle
ompile 'com.android.support:support-annotations:25.0.1'
3 最后点击工具栏或者通知中的 Sync Now。
如果你自己的库模块中使用了annotations，那么annotations就已经以XML的方式存在于AAR(Android Archive (AAR) artifact)文件的annotations.zip
中了。使用了你的库的用户就没有必要再以这种添加依赖的方式添加这个模块了。
如果你想用Gradle Java plugin这种方式代替默认的Android plugin for Gradle (com.android.application 或 com.android.library)
，那你必须明确指定SDK库的位置，因为Android支持库并不支持JCenter
repositories {
jcenter()
maven { url '<your-SDK-path>/extras/android/m2repository' }
}
