使用注解改进代码检查

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

通过注解，您可以向代码检查工具（例如 lint）提供提示，以帮助检测这些更细微的代码问题。注解作为元数据标记添加，您可以将其附加到变量、参数和返回值，以检查方法返回值、传入参数、局部变量和字段。与代码检查工具结合使用时，注解可以帮助您检测空指针异常和资源类型冲突等问题。

Android 通过 Jetpack 注解库支持各种注解。您可以通过 androidx.annotation 软件包访问该库。

注意：如果某个模块依赖于注解处理器，则对于 Kotlin，您必须使用 kapt 或 ksp 依赖配置；对于 Java，则必须使用 annotationProcessor 依赖配置来添加该依赖。

将注解添加到您的项目

要在项目中启用注解，请将 androidx.annotation:annotation 依赖项添加到您的库或应用中。您添加的任何注解都会在您运行代码检查或 lint 任务时进行检查。

添加 Jetpack 注解库依赖项

Jetpack 注解库发布在 Google 的 Maven 代码库中。要将 Jetpack 注解库添加到您的项目，请在 dependencies 代码块的 build.gradle 或 build.gradle.kts 文件中包含以下行

Kotlin

dependencies {
    implementation("androidx.annotation:annotation:1.9.1")
}

Groovy

dependencies {
    implementation 'androidx.annotation:annotation:1.9.1'
}
然后，在工具栏或出现的同步通知中，点击 Sync Now。

如果您在自己的库模块中使用注解，则这些注解会作为 Android Archive (AAR) 工件的一部分，以 XML 格式包含在 annotations.zip 文件中。添加 androidx.annotation 依赖项不会为您的库的任何下游用户引入依赖项。

注意：如果您正在使用其他 Jetpack 库，则可能无需添加 androidx.annotation 依赖项。由于许多其他 Jetpack 库都依赖于注解库，因此您可能已经有权访问这些注解。

有关 Jetpack 代码库中包含的注解的完整列表，请参阅 Jetpack 注解库参考，或使用自动补全功能显示 import androidx.annotation. 语句的可用选项。

运行代码检查

要从 Android Studio 开始代码检查（包括验证注解和自动 lint 检查），请从菜单中选择 Analyze > Inspect Code。Android Studio 会显示冲突消息，以标记代码与注解冲突的潜在问题，并建议可能的解决方案。

您还可以通过使用命令行运行 lint 任务来强制执行注解。虽然这对于标记持续集成服务器上的问题可能很有用，但 lint 任务不强制执行空值注解（将在下一节中介绍）；只有 Android Studio 才能这样做。有关启用和运行 lint 检查的更多信息，请参阅使用 lint 检查改进代码。

尽管注解冲突会生成警告，但这些警告不会阻止您的应用编译。

空值注解

空值注解在 Java 代码中非常有用，可用于强制规定值是否可以为空。它们在 Kotlin 代码中不太有用，因为 Kotlin 具有在编译时强制执行的内置空值安全性规则。

添加 @Nullable 和 @NonNull 注解，以检查给定变量、参数或返回值的空值情况。@Nullable 注解表示变量、参数或返回值可以为空。@NonNull 表示变量、参数或返回值不能为空。

例如，如果将包含空值的局部变量作为参数传递给带有 @NonNull 注解的方法，则构建代码会生成警告，指示非空冲突。此外，在未首先检查结果是否为空的情况下尝试引用由 @Nullable 标记的方法的结果，会生成空值警告。仅当方法的每次使用都必须进行显式空值检查时，才在方法的返回值上使用 @Nullable。

以下示例演示了空值性在实际应用中的情况。Kotlin 示例代码不使用 @NonNull 注解，因为在指定非空类型时，它会自动添加到生成的字节码中。Java 示例在 context 和 attrs 参数上使用 @NonNull 注解，以检查传入的参数值是否为空。它还检查 onCreateView() 方法本身是否不返回 null

Kotlin

...
    /** Annotation not used because of the safe-call operator(?)**/
    override fun onCreateView(
            name: String?,
            context: Context,
            attrs: AttributeSet
    ): View? {
        ...
    }
...

Java

import androidx.annotation.NonNull;
...
    /** Add support for inflating the <fragment> tag. **/
    @NonNull
    @Override
    public View onCreateView(String name, @NonNull Context context,
      @NonNull AttributeSet attrs) {
      ...
      }
...

空值性分析

Android Studio 支持运行空值性分析，以自动推断和插入代码中的空值注解。空值性分析会扫描代码中方法层次结构中的契约，以检测

  • 可返回 null 的调用方法。
  • 不应返回 null 的方法。
  • 可以为空的变量（例如字段、局部变量和参数）。
  • 不能包含空值的变量（例如字段、局部变量和参数）。

然后，分析会自动在检测到的位置插入适当的空值注解。

要在 Android Studio 中运行空值性分析，请选择 Analyze > Infer Nullity。Android Studio 会在代码中检测到的位置插入 Android @Nullable 和 @NonNull 注解。运行空值分析后，最好验证注入的注解。

注意：添加空值注解时，自动补全可能会建议 IntelliJ @Nullable 和 @NotNull 注解，而不是 Android 空值注解，并且可能会自动导入相应的库。但是，Android Studio lint 检查器仅查找 Android 空值注解。在验证您的注解时，请确认您的项目使用了 Android 空值注解，以便 lint 检查器可以在代码检查期间正确通知您。

资源注解

验证资源类型可能很有用，因为 Android 对资源的引用（例如可绘制对象和字符串资源）是作为整数传递的。

期望参数引用特定资源类型（例如 String）的代码可以传递给预期的 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 方法，反之亦然。但是，对于在不同线程上有多个视图的系统应用，UI 线程可能与主线程不同。因此，您应使用 @UiThread 注解与应用视图层次结构相关联的方法，并且仅使用 @MainThread 注解与应用生命周期相关联的方法。

如果类中的所有方法都共享相同的线程要求，则可以向该类添加单个线程注解，以验证类中的所有方法是否都从相同类型的线程调用。

线程注解的一个常见用途是验证带有 @WorkerThread 注解的方法或类是否仅从适当的后台线程调用。

值约束注解

使用 @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;

以下示例要求 copyImageFile() 方法的调用者具有对外部存储的读访问权限以及对复制图像中位置元数据的读访问权限

Kotlin

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

Java

@RequiresPermission(allOf = {
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION})
public static final void copyImageFile(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) 示例中，当 intent 未包含适当权限而传递给方法时，Intent 类中的注解会导致对 startActivity(Intent) 的无效使用生成警告，如图 1 所示。

图 1. startActivity(Intent) 方法上的间接权限注解生成的警告。

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

Kotlin

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

Java

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

如有必要，在注解方法的参数时，可以用 @RequiresPermission 替换 @RequiresPermission.Read 或 @RequiresPermission.Write。但是，对于间接权限，@RequiresPermission 不应与读或写权限注解一起使用。

返回值注解

使用 @CheckResult 注解来验证方法的返回值是否实际被使用。与其为每个非 void 方法添加 @CheckResult 注解，不如添加该注解来阐明可能令人困惑的方法的结果。

例如，新的 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 注解

Typedef 注解会检查特定参数、返回值或字段是否引用了一组特定的常量。它们还支持代码补全功能，自动提供允许的常量。

使用 @IntDef 和 @StringDef 注解创建整数和字符串集的枚举注解，以验证其他类型的代码引用。

Typedef 注解使用 @interface 声明新的枚举注解类型。@IntDef 和 @StringDef 注解与 @Retention 一起注解新注解，并且对于定义枚举类型是必需的。@Retention(RetentionPolicy.SOURCE) 注解告诉编译器不要将枚举注解数据存储在 .class 文件中。

以下示例展示了创建注解的步骤，该注解用于检查作为方法参数传递的值是否引用了定义的常量之一

Kotlin

import androidx.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 androidx.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 属性的注解，以检查参数或返回值是否引用了有效模式。

以下示例创建了 DisplayOptions 注解，其中包含有效的 DISPLAY_ 常量列表

Kotlin

import androidx.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 androidx.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 的，但对于测试而言它是 package-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.LIBRARY_GROUP_PREFIX) 将 API 访问权限仅限于您的库。

只有您的库代码才能访问带注解的 API。这不仅允许您以所需的任何包层次结构组织代码，还可以在一组相关库之间共享代码。此选项已可用于 Jetpack 库，这些库有许多不供外部使用的实现代码，但必须是 public 才能在各种互补的 Jetpack 库之间共享。

测试

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

只有测试代码才能访问带注解的 API。这可以防止其他开发者将您仅用于测试目的的 API 用于开发。