准备要发布的库

本页介绍了如何使用 Android Gradle 插件 (AGP) 设置所需的属性和选项，以便准备发布您的 Android 库项目。 即使您在开始创建库时设置了其中某些属性，也请查看以下指南以优化设置。

选择命名空间

Android 库需要声明一个命名空间，以便在系统编译其资源时生成唯一的 R 类。此命名空间应该与库的根类软件包高度一致，以免在用户从库导入常规类及其 R 类时造成混淆。

从 AGP 7.0 开始，您可以在应用的 build.gradle 文件中设置命名空间，如以下代码示例所示：

Groovy

android {
  namespace = 'com.example.library'
}

Kotlin

android {
  namespace = "com.example.library"
}

此命名空间是面向开发者的库属性。它与使用 applicationId 属性设置的应用身份无关。

在以前的 AGP 版本中，applicationId 属性（适用于应用）和 namespace 属性（适用于库）可以使用清单的 package 属性来设置，而这会导致混淆。

选择 minSdkVersion 值

为您的库选择 minSdkVersion 是发布库的重要环节。minSdkVersion 应该反映您的代码可以支持的最低 Android 版本。

选择 minSdkVersion 时，请注意以下几点：

  • 通常，选择较低版本的 minSdkVersion 可以扩大库的分发范围。

    除非应用明确调用，否则系统通常不会执行库的代码。如果库不是核心应用功能所必需的，您仍然可以在低于库依赖项要求的 Android 版本上运行应用，只需在调用该库之前进行运行时检查即可。因此，将库的 minSdkVersion 设为足够低的版本，使其可以嵌入应用并在可能的情况下可供调用，有助于您覆盖更多用户。

  • 选择较高版本的 minSdkVersion 可能会导致应用无法包含库。

    清单合并程序是 AGP 中的一个步骤，用于合并来自应用及其依赖项的清单文件，它会强制要求所有依赖项的 minSdkVersion 版本都不得高于应用。

  • 选择较高版本的 minSdkVersion 可能会提示应用开发者停用清单合并程序安全检查，导致后续的构建流程出现问题。

    由于清单合并程序会阻止应用项目包含 minSdkVersion 版本高于应用本身的库，因此应用开发者可能会停用清单合并程序的安全检查，以尽量减少构建错误。但是，这可能会导致下游出现真正的不兼容问题。

  • 在特殊情况下，如果库的清单包含广播接收器或自动触发其代码的其他某种机制，您必须选择较高版本的 minSdkVersion。

    在这些情况下，选择较高版本的 minSdkVersion 可以确保代码能够运行。或者，您也可以停用自动化行为，以便应用能够选择在执行正确的检查后执行相应的库。

若要允许嵌入到应用中，请在库中使用 RequiresApi 注解，以向调用方指明它们需要进行运行时检查。Android Lint 使用 RequiresApi 信息进行检查。如需详细了解如何使用注解来改进 API 代码和 API，请参阅利用注解改进代码检查。

设置 AAR 元数据

Android 库以 Android ARchive (AAR) 文件的形式打包。AAR 元数据由可以帮助 AGP 使用库的属性组成。如果您的库被不兼容的配置所使用，并且设置了 AAR 元数据，系统会向用户显示错误消息，以帮助对方解决问题。

选择 minCompileSdk 值

从版本 4.1 开始，AGP 支持 minCompileSdk。 这表示使用方项目可以使用的最低版本的 compileSdk。如果您的库包含清单条目或使用新版平台属性的资源，您需要设置此值。

您可以在模块级 build.gradle 文件的 defaultConfig{}、productFlavors{} 和 buildTypes{} 代码块中设置 minCompileSdk 值：

Groovy

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    foo {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

Kotlin

android {
  defaultConfig {
    aarMetadata {
      minCompileSdk = 29
    }
  }
  productFlavors {
    register("foo") {
      ...
      aarMetadata {
        minCompileSdk = 30
      }
    }
  }
}

如果您在多个位置设置 minCompileSdk，Gradle 会在构建流程中按以下顺序确定各设置位置的优先级：

  1. buildTypes{}

  2. productFlavors{}

  3. defaultConfig{}

在上述示例中，defaultConfig{} 和 productFlavors{} 中都定义了 minCompileSdk，而 productFlavors{} 的优先级更高，因此 minCompileSdk 设为 30。

如需详细了解 Gradle 在组合代码和资源时如何确定设置的优先级，请参阅使用源代码集构建。

启用测试夹具

测试夹具通常用于设置要测试的代码，或帮助完成组件测试。从版本 7.1 开始，除了应用和动态功能项目外，AGP 还可以为库项目创建测试夹具。

发布供其他用户使用的库时，不妨考虑为您的 API 创建测试夹具。您可以在模块级 build.gradle 文件中启用测试夹具：

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

您开启测试夹具后，Gradle 会自动创建一个 src/testFixtures 源代码集，您可在其中编写测试夹具。

如需了解详情，请参阅有关如何使用测试夹具的 Gradle 文档。