利用注释改进代码检查

代码检查工具（如 Lint）可以帮助您找到问题并改进代码，但检查工具只能推断出这么多信息。例如，Android 资源 ID 使用 int 来标识字符串、图形、颜色及其他资源类型，因此如果您在本应指定颜色的地方指定了字符串资源，检查工具就无法发现这一问题。这种情况意味着，即使您使用了代码检查工具，您的应用也可能无法正确呈现或根本无法运行。

您可以使用注释向 Lint 之类的代码检查工具提供提示，以便它们检测这些更细微的代码问题。它们将作为附加到变量、参数和返回值的元数据标记进行添加，用于检查方法返回值、传递的参数、局部变量和字段。与代码检查工具配合使用时，注释可以帮助您发现一些问题，如 null 指针异常和资源类型冲突。

Android 通过注释支持库支持多种注释。您可以通过 android.support.annotation 软件包获取该库。

注意：如果模块依赖于某个注释处理器，您必须使用“annotationProcessor”依赖项配置来添加该依赖项。要了解详情，请阅读使用注释处理器依赖项配置。

为您的项目添加注释

要在您的项目中启用注释，请为库或应用添加 support-annotations 依赖项。这样一来，当您运行代码检查或 lint 任务时，您添加的所有注释都会接受检查。

添加支持注释库依赖项

支持注释库是在 Google 的 Maven 代码库中发布的。如需为您的项目添加支持注释库，请在 build.gradle 文件的 dependencies 代码块中添加以下代码行：

    dependencies {
        implementation 'com.android.support:support-annotations:28.0.0'
    }

然后，在工具栏或显示的同步通知中，点击 Sync Now。

如果您在自己的库模块中使用注释，注释将作为 Android ARchive (AAR) 工件的一部分以 XML 格式添加到 annotations.zip 文件中。添加 support-annotations 依赖项不会为相应库的任何下游用户引入依赖项。

注意：如果您使用的是 appcompat 库，则无需添加 support-annotations 依赖项。因为 appcompat 库已经依赖于注释库，您可以访问相关注释。

如需支持存储库中包含的注释的完整列表，请查看支持注释库参考，或者使用自动补全功能来显示 import android.support.annotation. 语句的可用选项。

运行代码检查

要从 Android Studio 启动代码检查（包括验证注释和自动 Lint 检查），请从菜单栏中依次选择 Analyze > Inspect Code。Android Studio 将显示冲突消息，在您的代码与注解冲突的地方标记潜在问题并建议可能的解决方法。

您还可以使用命令行运行 lint 任务，以便强制执行注释。尽管这对标记持续集成服务器遇到的问题可能有用，但请注意，lint 任务并不会强制执行 null 性注释（只有 Android Studio 会强制执行此类注释）。如需详细了解如何启用和运行 Lint 检查，请参阅使用 Lint 改进代码。

请注意，尽管注释冲突会导致生成警告，但这些警告不会阻止应用编译。

null 性注释

添加 @Nullable 和 @NonNull 注释，以检查给定变量、参数或返回值的 null 性。@Nullable 注释用于指明可以为 null 的变量、参数或返回值，而 @NonNull 则用于指明不可以为 null 的变量、参数或返回值。

例如，如果将包含 null 值的局部变量作为参数传递给方法，并且将 @NonNull 注释附加到该参数，则构建代码时会生成一条警告，指明存在非 null 冲突。另一方面，如果不事先检查被标记为 @Nullable 的方法返回的结果是否为 null，就尝试引用该结果，会导致生成一条 null 性警告。只有在每次使用方法时都明确检查返回值是否为 null，才能对方法的返回值使用 @Nullable。

以下示例将 @NonNull 注释附加到 context 和 attrs 参数，以检查传递的参数值是否不为 null。此外，还会检查 onCreateView() 方法本身是否不会返回 null。请注意，对于 Kotlin，我们不需要使用 @NonNull 注释，因为当我们指定了不可为 null 的类型时，该注释会自动添加到生成的字节码：

Kotlin

    import android.support.annotation.NonNull
    ...

        /** Add support for inflating the <fragment> tag. **/
        fun onCreateView(
                name: String?,
                context: Context,
                attrs: AttributeSet
        ): View? {
            ...
        }
    ...

Java

    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) {
          ...
          }
    ...

Null 性分析

Android Studio 支持运行 null 性分析，以在代码中自动推断和插入 null 性注释。null 性分析会在代码的整个方法层次结构中扫描协定元素，以检测：

可以返回 null 的调用方法
不应返回 null 的方法
可以为 null 的变量，如字段、局部变量和参数
不能具有 null 值的变量，如字段、局部变量，以及参数

然后，该分析会在检测到的位置自动插入适当的 null 注释。

要在 Android Studio 中运行 null 性分析，请依次选择 Analyze > Infer Nullity。Android Studio 会在代码中检测到的位置插入 Android @Nullable 和 @NonNull 注释。运行 null 性分析后，最好验证一下这些注入的注释。

注意：添加 null 性注释时，自动补全功能可能会建议 IntelliJ @Nullable 和 @NotNull 注释，而不是 Android null 注释，并且可能会自动导入相应的库。不过，Android Studio Lint 检查工具只会查找 Android null 注释。验证您的注释时，请确认您的项目使用了 Android null 注释，以便 Lint 检查工具可以在代码检查期间正确通知您。

资源注释

验证资源类型可能非常有用，因为 Android 对资源（如可绘制对象和字符串资源）的引用以整数形式传递。如果代码需要一个参数来引用特定类型的资源（例如可绘制对象），可以为该代码传递预期的引用类型 int，但它实际上会引用其他类型的资源，如 R.string 资源。

例如，添加 @StringRes 注释，以检查资源参数是否包含 R.string 引用，如下所示：

Kotlin

    abstract fun setTitle(@StringRes resId: Int)

Java

    public abstract void setTitle(@StringRes int resId)

在代码检查期间，如果未在参数中传递 R.string 引用，该注释会生成一条警告。

其他资源类型的注释（例如 @DrawableRes、@DimenRes、@ColorRes 和 @InterpolatorRes）可以使用相同的注释格式添加，并在代码检查期间运行。如果参数支持多种资源类型，您可以为给定参数添加其中多个注释。使用 @AnyRes 可以指明被注释的参数可以是任何类型的 R 资源。

尽管您可以使用 @ColorRes 指定某个参数应为颜色资源，但系统不会将颜色整数（采用 RRGGBB 或 AARRGGBB 格式）识别为颜色资源。您可以改用 @ColorInt 注释来指明某个参数必须为颜色整数。构建工具会标记以下错误代码：将颜色资源 ID（例如 android.R.color.black）而非颜色整数传递给被注释的方法。

线程注释

线程注释可以检查某个方法是否从特定类型的线程调用。支持以下线程注释：

注意：构建工具会将 @MainThread 和 @UiThread 注释视为可互换，因此您可以从 @MainThread 方法调用 @UiThread 方法，反之亦然。不过，如果系统应用有多个视图在不同的线程上，那么界面线程可能会与主线程不同。因此，您应使用 @UiThread 来注释与应用的视图层次结构关联的方法，并使用 @MainThread 仅标注与应用生命周期关联的方法。

如果某个类中的所有方法具有相同的线程要求，您可以为该类添加一个线程注释，以验证该类中的所有方法是否从同一类型的线程调用。

线程注释的一个常见用途是验证 AsyncTask 类中的方法替换，因为此类会执行后台操作，并且仅在界面线程上发布结果。

值约束注释

使用 @IntRange、@FloatRange 和 @Size 注释可以验证所传递参数的值。@IntRange 和 @FloatRange 在应用到用户很可能会弄错范围的参数时最为有用。

@IntRange 注释可以验证整型或长型参数值是否在指定范围内。以下示例可以确保 alpha 参数包含介于 0 到 255 之间的整数值：

Kotlin

    fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }

Java

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

@FloatRange 注释可以检查浮点型或双精度型参数值是否在指定的浮点值范围内。以下示例可以确保 alpha 参数包含介于 0.0 到 1.0 之间的浮点值：

Kotlin

    fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}

Java

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

@Size 注释可以检查集合或数组的大小，以及字符串的长度。@Size 注释可用于验证以下特性：

最小大小（例如 @Size(min=2)）
最大大小（例如 @Size(max=2)）
确切大小（例如 @Size(2)）
大小必须是指定数字的倍数（例如 @Size(multiple=2)）

例如，@Size(min=1) 可以检查某个集合是否不为空，@Size(3) 可以验证某个数组是否正好包含三个值。以下示例可以确保 location 数组至少包含一个元素：

Kotlin

    fun getLocation(button: View, @Size(min=1) location: IntArray) {
        button.getLocationOnScreen(location)
    }

Java

    void getLocation(View button, @Size(min=1) int[] location) {
        button.getLocationOnScreen(location);
    }

权限注释

使用 @RequiresPermission 注释可以验证方法调用方的权限。要检查是否具有一系列有效权限中的一项权限，请使用 anyOf 属性。要检查是否具有某组权限，请使用 allOf 属性。以下示例会注释 setWallpaper() 方法，以确保方法调用方具有 permission.SET_WALLPAPERS 权限。

Kotlin

    @RequiresPermission(Manifest.permission.SET_WALLPAPER)
    @Throws(IOException::class)
    abstract fun setWallpaper(bitmap: Bitmap)

Java

    @RequiresPermission(Manifest.permission.SET_WALLPAPER)
    public abstract void setWallpaper(Bitmap bitmap) throws IOException;

此示例要求 copyFile() 方法的调用方具有对外部存储空间的读取和写入权限：

Kotlin

    @RequiresPermission(allOf = [
        Manifest.permission.READ_EXTERNAL_STORAGE,
        Manifest.permission.WRITE_EXTERNAL_STORAGE
    ])
    fun copyFile(dest: String, source: String) {
        ...
    }

Java

    @RequiresPermission(allOf = {
        Manifest.permission.READ_EXTERNAL_STORAGE,
        Manifest.permission.WRITE_EXTERNAL_STORAGE})
    public static final void copyFile(String dest, String source) {
        //...
    }

对于 intent 的权限，请在用来定义 intent 操作名称的字符串字段上添加权限要求：

Kotlin

    @RequiresPermission(android.Manifest.permission.BLUETOOTH)
    const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

Java

    @RequiresPermission(android.Manifest.permission.BLUETOOTH)
    public static final String ACTION_REQUEST_DISCOVERABLE =
                "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";

如果您需要对内容提供程序拥有单独的读取和写入访问权限，则需要将每个权限要求封装在 @RequiresPermission.Read 或 @RequiresPermission.Write 注释中：

Kotlin

    @RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS))
    @RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS))
    val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")

Java

    @RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS))
    @RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
    public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");

间接权限

如果权限依赖于为某个方法的参数提供的特定值，则应对该参数本身使用 @RequiresPermission，而不必列出具体权限。例如，startActivity(Intent) 方法会对传递给它的 intent 使用间接权限：

Kotlin

    abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)

Java

    public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle)

当您使用间接权限时，构建工具会执行数据流分析，以检查传递给方法的参数是否具有任何 @RequiresPermission 注释。随后，它们会对方法本身强制执行参数的所有现有注释。在 startActivity(Intent) 示例中，如果向 startActivity(Intent) 方法传递了不具备相应权限的 intent，Intent 类中的注释就会导致针对无效使用该方法的情况生成警告，如图 1 所示。

图 1. 根据间接权限注释针对 startActivity(Intent) 方法生成的警告。

构建工具会根据 Intent 类中相应的 intent 操作名称上的注释针对 startActivity(Intent) 生成警告：

Kotlin

    @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
    @RequiresPermission(Manifest.permission.CALL_PHONE)
    const val ACTION_CALL = "android.intent.action.CALL"

Java

    @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
    @RequiresPermission(Manifest.permission.CALL_PHONE)
    public static final String ACTION_CALL = "android.intent.action.CALL";

如有必要，在注释方法的参数时，您可以将 @RequiresPermission 替换为 @RequiresPermission.Read 和/或 @RequiresPermission.Write。不过，对于间接权限，@RequiresPermission 不应与读取或写入权限注释结合使用。

返回值注释

使用 @CheckResult 注释可验证是否实际使用了方法的结果或返回值。应添加注释来阐明可能令人困惑的方法的结果，而不是使用 @CheckResult 注释每个非 void 方法。例如，新手 Java 开发者经常误认为 <String>.trim() 会移除原始字符串中的空白字符。如果使用 @CheckResult 来注释方法，系统会在调用方不对方法的返回值进行任何处理时标记使用 <String>.trim() 的情况。

以下示例注释了 checkPermissions() 方法，以确保会实际引用该方法的返回值。此外，这还会将 enforcePermission() 方法指定为要向开发者建议的替代方法：

Kotlin

    @CheckResult(suggest = "#enforcePermission(String,int,int,String)")
    abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int

Java

    @CheckResult(suggest="#enforcePermission(String,int,int,String)")
    public abstract int checkPermission(@NonNull String permission, int pid, int uid);

CallSuper 注释

使用 @CallSuper 注释可验证替换方法是否会调用该方法的超类实现。以下示例注释了 onCreate() 方法，以确保所有替换方法实现都会调用 super.onCreate()：

Kotlin

    @CallSuper
    override fun onCreate(savedInstanceState: Bundle?) {
    }

Java

    @CallSuper
    protected void onCreate(Bundle savedInstanceState) {
    }

Typedef 注释

使用 @IntDef 和 @StringDef 注释，您可以创建整数集和字符串集的枚举注释来验证其他类型的代码引用。Typedef 注释可以确保特定参数、返回值或字段引用一组特定的常量。这些注释还会启用代码补全功能，以自动提供允许的常量。

Typedef 注释使用 @interface 来声明新的枚举注释类型。@IntDef 和 @StringDef 注释以及 @Retention 可以对新注释进行注释，是定义枚举类型所必需的。@Retention(RetentionPolicy.SOURCE) 注释可告诉编译器不要将枚举注释数据存储在 .class 文件中。

以下示例展示了创建某个注释的具体步骤，该注释可以确保作为方法参数传递的值引用某个已定义的常量：

Kotlin

    import android.support.annotation.IntDef
    //...
    // Define the list of accepted constants and declare the NavigationMode annotation
    @Retention(AnnotationRetention.SOURCE)
    @IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS)
    annotation class NavigationMode

    // Declare the constants
    const val NAVIGATION_MODE_STANDARD = 0
    const val NAVIGATION_MODE_LIST = 1
    const val NAVIGATION_MODE_TABS = 2

    abstract class ActionBar {

        // Decorate the target methods with the annotation
        // Attach the annotation
        @get:NavigationMode
        @setparam:NavigationMode
        abstract var navigationMode: Int

    }

Java

    import android.support.annotation.IntDef;
    //...
    public abstract class ActionBar {
        //...
        // Define the list of accepted constants and declare the NavigationMode annotation
        @Retention(RetentionPolicy.SOURCE)
        @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
        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 或 NAVIGATION_MODE_TABS），系统会生成一条警告。

您还可以结合使用 @IntDef 和 @IntRange，以指明某个整数可以是一组给定的常量，也可以是某个范围内的值。

支持使用标记将常量组合起来

如果用户可以使用标记（如 |、&、^ 等）将允许的常量组合起来，您可以通过 flag 属性定义一个注释，以检查参数或返回值是否引用有效模式。以下示例使用一组有效的 DISPLAY_ 常量来创建 DisplayOptions 注释：

Kotlin

    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(AnnotationRetention.SOURCE)
    annotation class DisplayOptions
    ...

Java

    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 {}

    ...

构建带注释标记的代码时，如果经过修饰的参数或返回值未引用有效模式，系统会生成一条警告。

Keep 注释

使用 @Keep 注释可以确保以下情况：如果在构建时缩减代码大小，将不会移除带有该注释的类或方法。该注释通常添加到通过反射访问的方法和类，以防止编译器将代码视为未使用。

注意：使用 @Keep 注释的类和方法会始终包含在应用的 APK 中，即使您从未在应用逻辑中引用这些类和方法也是如此。

为使您的应用保持小巧，请考虑是否有必要在您的应用中保留每个 @Keep 注释。如果使用反射来访问被注释的类或方法，请在 ProGuard 规则中使用 -if 条件语句来指定进行反射调用的类。

如需详细了解如何缩减代码大小以及如何指定不应移除的代码，请参阅压缩代码和资源。

代码公开范围注释

使用以下注释可以指明代码特定部分（如方法、类、字段或软件包）的公开范围。

使代码公开以进行测试

@VisibleForTesting 注释用于指明被注释的方法的公开范围大于使该方法可供测试通常所需的公开范围。该注释包含一个可选的 otherwise 参数，您可以通过该参数指定在不需要使某个方法公开以进行测试时，该方法的公开范围应该是多大。Lint 使用 otherwise 参数来强制执行预期的公开范围。

在以下示例中，myMethod() 通常为 private，但对测试来说是软件包专用的方法。指定了以下 VisibleForTesting.PRIVATE 参数时，如果从 private 访问权限允许的上下文以外（如从其他编译单元）调用此方法，Lint 会显示一条消息。

Kotlin

    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
    fun myMethod() {
        ...
    }

Java

    @VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
    void myMethod() { ... }

您还可以指定 @VisibleForTesting(otherwise = VisibleForTesting.NONE)，以指明某个方法的存在只是为了进行测试。这种形式与使用 @RestrictTo(TESTS) 相同。这两者执行相同的 Lint 检查。

限制 API

@RestrictTo 注释用于指明访问被注释的 API（软件包、类或方法）会受到限制，具体说明如下。

子类

使用 @RestrictTo(RestrictTo.Scope.SUBCLASSES) 注释形式可以仅限子类访问 API。

只有对被注释的类进行扩展的类可以访问此 API。Java protected 修饰符的限制性不够严格，因为它允许从同一软件包中的不相关类进行访问。此外，在有些情况下，您可能希望使某个方法保持 public 状态，以便将来灵活使用，因为您永远不能使先前处于 protected 状态且被替换的方法变为 public 状态，但您需要提供一条提示，指明该方法应仅在相应类或子类中使用。

库

使用 @RestrictTo(RestrictTo.Scope.GROUP_ID) 注释形式可以限制只有库能够访问 API。

只有库代码可以访问被注释的 API。这样，您不仅可以按所需的任何软件包层次结构组织您的代码，还可以在一组相关库之间共享代码。有些支持库包含大量的实现代码，这些代码不适合外部使用，但必须处于 public 状态，以便在各种互补支持库之间共享，而此选项已经可供此类支持库使用。

注意：Android 支持库类和软件包现在带有 @RestrictTo(GROUP_ID) 注释，这意味着，如果您不小心使用了这些实现类，Lint 会警告您不建议这样做。

测试

使用 @RestrictTo(RestrictTo.Scope.TESTS) 注释形式可以防止其他开发者访问您的测试 API。

只有测试代码可以访问被注释的 API。这样可以防止其他开发者使用您仅打算作测试之用的 API 进行开发。