准备发布您的库

此页面描述了使用 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 中，可以使用清单的 package 属性设置 applicationId 属性（对于应用）和 namespace 属性（对于库），这导致了混淆。

选择 minSdkVersion 值

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

在选择 minSdkVersion 时，请注意以下事项

  • 选择较低的 minSdkVersion 通常可以更广泛地分发您的库。

    除非应用显式调用库代码，否则通常不会执行库代码。应用仍然可以在低于库依赖项所需版本的 Android 版本上运行（如果库不是核心应用功能所必需的）——在调用库之前进行运行时检查。因此，请将库的 minSdkVersion 设置得足够低，以便可以将其嵌入到应用中，并在可能的情况下调用，以帮助覆盖更多用户。

  • 选择较高的 minSdkVersion 可能会阻止应用包含该库。

    清单合并器（AGP 中合并应用及其依赖项的清单文件的步骤）强制执行任何依赖项的 minSdkVersion 不高于应用。

  • 选择较高的 minSdkVersion 可能会提示应用开发者停用清单合并器安全检查，从而在构建过程的后期导致问题。

    由于清单合并器阻止应用项目包含 minSdkVersion 高于应用本身的库，因此应用开发者可能会停用清单合并器的安全检查以最大程度地减少构建错误。但是，这存在在构建过程的后期出现真正不兼容问题的风险。

  • 在库的清单包含广播接收器或其他某种其代码自动触发的机制的特殊情况下，可能需要选择较高的 minSdkVersion。

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

为了允许在应用中嵌入库，请在库中使用RequiresApi注解，以告知调用方需要进行运行时检查。Android Lint 使用 RequiresApi 信息进行检查。有关使用注解改进 API 代码和 API 的更多资源，请参阅 使用注解改进代码检查。

设置 AAR 元数据

Android 库打包成 Android 归档 (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{}

在前面的示例中，如果 minCompileSdk 在 defaultConfig{} 和 productFlavors{} 中都定义，则优先考虑 productFlavors{}，并将 minCompileSdk 设置为 30。

要详细了解 Gradle 在组合代码和资源时如何优先考虑设置，请参阅 使用源集构建。

启用测试夹具

测试夹具 通常用于设置要测试的代码或促进组件的测试。从 7.1 版本开始，AGP 除了应用程序和动态特性项目外，还可以为库项目创建测试夹具。

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

Groovy

android {
  testFixtures {
    enable = true
  }
}

Kotlin

android {
  testFixtures {
    enable = true
  }
}

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

有关更多信息，请参阅 Gradle 有关 使用测试夹具 的文档。