准备发布您的库

本页面介绍了使用 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。如果您的库包含利用较新平台属性的清单条目或资源，则需要设置此值。

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

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 关于使用测试夹具的文档。