准备发布您的库

此页面介绍了使用 Android Gradle 插件 (AGP) 准备将您的 Android 库 项目发布所需的属性和选项。即使您在创建库之初设置了其中一些属性，也请查看以下指导以优化您的设置。

选择命名空间

Android 库需要声明一个命名空间，以便在编译其资源时生成唯一的 R 类。此命名空间应与库的根类包紧密匹配，以避免用户从库及其 R 类导入常规类时出现混淆。

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

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

在上例中，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 有关使用测试夹具的文档。