Android注解支持

秒速五厘米 2022-06-01 07:46 140阅读 0赞

# (Support Annotations) #

Aug 13, 2015 |  [Android][]  | 16040 阅读

文章目录

1.  [1. 注解支持(Support Annotations)][1._Support Annotations]
2.  [2. 使用注解库][2.]
3.  [3. 执行注解][3.]
4.  [4. Nullness Annotations][4._Nullness Annotations]
5.  [5. 资源类型注解][5.]
6.  [6. IntDef/StringDef: 类型定义注解][6._IntDef_StringDef_]
7.  [7. 线程注解: @UiThread, @WorkerThread, …][7._ _UiThread_ _WorkerThread_]
8.  [8. RGB颜色整型][8._RGB]
9.  [9. 值约束: @Size, @IntRange, @FloatRange][9._ _Size_ _IntRange_ _FloatRange]
10. [10. 权限注解: @RequiresPermission][10._ _RequiresPermission]
11. [11. 方法重写: @CallSuper][11._ _CallSuper]
12. [12. 返回值: @CheckResult][12._ _CheckResult]
13. [13. @VisibleForTesting][13._VisibleForTesting]
14. [14. @Keep][14._Keep]
15. [15. 在你自己的库中使用注解][15.]
16. [16. IntelliJ注解][16._IntelliJ]

原文地址 [http://tools.android.com/tech-docs/support-annotations][http_tools.android.com_tech-docs_support-annotations]

更多翻译的Android技术文档请参考：[https://github.com/rujews/android-tech-docs][https_github.com_rujews_android-tech-docs]

### 注解支持(Support Annotations) ###

Android support library从19.1版本开始引入了一个新的注解库，它包含很多有用的元注解，你能用它们修饰你的代码，帮助你发现bug。Support library自己本身也用到了这些注解，所以作为support library的用户，Android Studio已经基于这些注解校验了你的代码并且标注其中潜在的问题。Support library 22.2版本又新增了13个新的注解以供使用。

### 使用注解库 ###

注解默认是没有包含的；他们被包装成一个独立的库。（support library现在由一些更小的库组成：v4-support, appcompat, gridlayout, mediarouter等等）

(如果你正在使用appcompat库，那么你已经可以使用这些注解了，因为appcomat它自己也依赖它。)

添加使用注解最简单的方式就是打开Project Structure对话框。首先在左边选中module，然后在右边选中Dependencies标签页，点击面板底部的`+`按钮，选择Library Dependency，假设你已经把Android Support Repository安装到你的SDK中了，那么注解库将会出现在列表中，你只需点击选中它即可(这里是列表中的第一个):  
[![添加依赖][add-dependency.png]][add-dependency.png]添加依赖

点击OK完成Project Structure的编辑。这会修改你的build.gradle文件，当然你也可以手动编辑它：

dependencies {
        compile 'com.android.support:support-annotations:22.2.0'
    }

对于Android application和Android library这两个类型的module(你应用了`com.android.application`或者`com.android.library`插件的)来说，你需要做的已经都做好了。如果你想只在Java module使用这些注解，那么你就明确的包含SDK仓库了，因为support libraries不能从jcenter获得(Android Gradle插件会自动的包含这些依赖，但是Java插件却没有。)

repositories {
       jcenter()
       maven { url '<your-SDK-path>/extras/android/m2repository' }
    }

### 执行注解 ###

当你用Android Studio和IntelliJ的时候，如果给标注了这些注解的方法传递错误类型的参数，那么IDE就会实时标记出来。

从Gradle插件1.3.0-beta1版本开始，并且安装了Android M Preview平台工具的情况下，通过命令行调用gradle的`lint`任务就可以执行这些检查。如果你想把标记问题作为持续集成的一部分，那么这种方式是非常有用的。说明：这并不包含nullness注解。本文中所介绍的其他注解都可以通过lint执行检查。

### Nullness Annotations ###

@Nullable注解能被用来标注给定的参数或者返回值可以为null。  
类似的，@NonNull注解能被用来标注给定的参数或者返回值不能为null。

如果一个本地变量的值为null(比如因为过早的代码检查它是否为null)，而你又把它作为参数传递给了一个方法，并且该方法的参数又被@NonNull标注，那么IDE会提醒你，你有一个潜在的崩溃问题。

v4 support library中的FragmentActivity的示例代码：
    
    import android.support.annotation.NonNull;
    import android.support.annotation.Nullable;
    ...
    
    /**
     * Add support for inflating the <fragment> tag.
     */
    @Nullable
    @Override
    public View onCreateView(String name, @NonNull Context context, @NonNull AttributeSet attrs) {
    ...

(如果你执行Analyze > Infer Nullity，或者你在键入时把@NonNull替换成了@NotNull，那么IDE可能会提供附加的IntelliJ注解。参考底部的“IntelliJ Annotations”段落了解更多)

注意@NonNull和@Nullable并不是对立的：还有第三种可能：未指定。当你没有指定@NonNull或者@Nullable的时候，工具就不能确定，所以这个API也就不起作用。

最初，我们在findViewById方法上标注@Nullable，从技术上说，这是正确的：findViewById可以返回null。但是如果你知道你在做什么的时候(如果你传递给他一个存在的id)他是不会返回null的。当我们使用@Nullable注解它的时候，就意味着源代码编辑器中会有大量的代码出现高亮警告。如果你已经意识到每次使用该方法都应该明确的进行null检查，那么就只能用@Nullable标注返回值。有个经验规则：看现有的“好的代码”(比如审查产品代码)，看看这些API是怎么被使用的。如果该代码为null检查结果，你应该为方法注解@Nullable。

### 资源类型注解 ###

Android的资源值通常都是使用整型传递。这意味着获取一个drawable使用的参数，也能很容易的传递给一个获取string的方法；因为他们都是int类型，编译器很难区分。

资源类型注解可以在这种情况下提供类型检查。比如一个被@StringRes住进诶的int类型参数，如果传递一个不是R.string类型的引用将会被IDE标注：  
[![资源类型注解][image00.png]][image00.png]资源类型注解  
以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将会标记出这种情况。  
[![类型定义注解][image06.png]][image06.png]类型定义注解

你也可以指定一个整型是一个标记性质的类型；这样客户端代码就通过|，&等操作符同时传递多个常量了：

@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][https_developer.android.com_tools_debugging_annotations.html_enum-annotations]

(这些都是建立在IntelliJ’s MagicConstant注解的基础上，你可以在这里找到该注解的详细信息：[http://blog.jetbrains.com/idea/2012/02/new-magic-constant-inspection/][http_blog.jetbrains.com_idea_2012_02_new-magic-constant-inspection])

### 线程注解: @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工具就会马上把它标记为一个错误：  
[![线程注解][image04.png]][image04.png]线程注解

@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就会标记出这段不正确的代码：  
[![颜色值注解][image05.png]][image05.png]颜色值注解

### 值约束: @Size, @IntRange, @FloatRange ###

如果你的参数是一个float或者double类型，并且一定要在某个范围内，你可以使用@FloatRange注解：

public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {

如果有人使用该API的时候传递一个0-255的值，比如尝试调用setAlpha(128)，那么工具就会捕获这一问题：

[![值约束注解][image08.png]][image08.png]值约束注解

(你也可以指定是否包括起始值。)

同样的，如果你的参数是一个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)

[![值约束注解][image03.png]][image03.png]值约束注解

### 权限注解: @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");

[![权限注解][image01.png]][image01.png]权限注解

### 方法重写: @CallSuper ###

如果你的API允许使用者重写你的方法，但是呢，你又需要你自己的方法(父方法)在重写的时候也被调用，这时候你可以使用@CallSuper标注：

@CallSuper
    protected void onCreate(@Nullable Bundle savedInstanceState) {

用了这个后，当重写的方法没有调用父方法时，工具就会给予标记提示：

[![方法重写][image02.png]][image02.png]方法重写

(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。

[![返回值][image07.png]][image07.png]返回值

### @VisibleForTesting ###

你可以把这个注解标注到类、方法或者字段上，以便你在测试的时候可以使用他们。

### @Keep ###

我们还在注解库里添加了@Keep注解，但是Gradle插件还支持（尽管已经在进行中）。被这个注解标注的类和方法在混淆的时候将不会被混淆。

### 在你自己的库中使用注解 ###

如果你在你自己的库中使用了这些注解，并且是通过Gradle构建生成aar包，那么在构建的时候Android Gradle插件会提取注解信息放在AAR文件中供引用你的库的客户端使用。在AAR文件中你可以看到一个名为annotations.zip的文件，这个文件记录的就是注解信息，使用的是IntelliJ的扩展注解XML格式。这是必须的，因为.class文件不能包含足够的要处理以上@IntDef注解的信息；注意我们只需记录该常量的一个引用，而不是它的值。当且仅当你的工程依赖注解库的时候，Android Gradle插件会把提取注解的任务作为构建的一部分执行它。(说明：只有源保留注解被放置在.aar文件中；class级别的会被放在classes.jar里。)

### 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'
    }

[Android]: http://www.flysnow.org/categories/Android/
[1._Support Annotations]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#注解支持-Support-Annotations
[2.]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#使用注解库
[3.]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#执行注解
[4._Nullness Annotations]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#Nullness-Annotations
[5.]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#资源类型注解
[6._IntDef_StringDef_]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#IntDef-StringDef-类型定义注解
[7._ _UiThread_ _WorkerThread_]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#线程注解-UiThread-WorkerThread-…
[8._RGB]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#RGB颜色整型
[9._ _Size_ _IntRange_ _FloatRange]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#值约束-Size-IntRange-FloatRange
[10._ _RequiresPermission]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#权限注解-RequiresPermission
[11._ _CallSuper]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#方法重写-CallSuper
[12._ _CheckResult]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#返回值-CheckResult
[13._VisibleForTesting]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#VisibleForTesting
[14._Keep]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#Keep
[15.]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#在你自己的库中使用注解
[16._IntelliJ]: http://www.flysnow.org/2015/08/13/android-tech-docs-support-annotations.html#IntelliJ注解
[http_tools.android.com_tech-docs_support-annotations]: http://tools.android.com/tech-docs/support-annotations
[https_github.com_rujews_android-tech-docs]: https://github.com/rujews/android-tech-docs
[add-dependency.png]: /images/20220601/c4168cb0bb404a22b1c66777b3ef886f.png
[image00.png]: /images/20220601/4bbdd38b730a41a591456f4eb32ba923.png
[image06.png]: /images/20220601/86500b3bc0c9479ab55b90a692f14ffa.png
[https_developer.android.com_tools_debugging_annotations.html_enum-annotations]: https://developer.android.com/tools/debugging/annotations.html#enum-annotations
[http_blog.jetbrains.com_idea_2012_02_new-magic-constant-inspection]: http://blog.jetbrains.com/idea/2012/02/new-magic-constant-inspection/
[image04.png]: /images/20220601/049501397c7741ac80c4011f83656e1c.png
[image05.png]: /images/20220601/07f2d3212a23454e8afe3f3660d0ebf2.png
[image08.png]: /images/20220601/4739bb06c57f489bb91846af03a335cd.png
[image03.png]: /images/20220601/89a47a1d43a84df693aa1b86fa8b443b.png
[image01.png]: /images/20220601/42d6e31634b845bf9395ff657ee4cde1.png
[image02.png]: /images/20220601/fd85393cc2e4413d8268de45e16000a3.png
[image07.png]: /images/20220601/53294ea891304983a4ecf6f0b4f5006b.png