面向库作者的优化

作为库作者，您必须确保应用开发者可以轻松将您的库纳入其应用，同时保持高质量的最终用户体验。这意味着您的库必须与 Android 优化 (R8) 兼容，而无需开发者进行额外的设置，或者说明该库可能不适合在 Android 上使用。至关重要的是， 旨在在 Android 上使用的库不得阻止重要的应用 优化，并且必须遵守额外的优化要求。

本文档面向已发布库的开发者，但对于大型模块化应用中的内部库模块的开发者也可能有用。

如果您是应用开发者，并且想了解如何优化 Android 应用， 请参阅启用应用优化。如需了解哪些库适合 使用，请参阅明智地选择库。

了解保留规则类型

库中可以包含两种截然不同的保留规则：

• 使用方保留规则 必须指定保留库所反映内容的规则。如果库使用反射或 JNI 调用其代码或客户端应用定义的代码，则这些规则需要描述需要保留哪些代码。库应打包使用方保留规则，这些规则的格式与应用保留规则相同。这些规则捆绑到库工件（AAR 或 JAR）中，并在使用库时在 Android 应用优化期间自动使用。 这些规则保存在 文件中，该文件使用 consumerProguardFiles 属性在您的 build.gradle.kts（或 build.gradle）文件中指定。如需了解详情，请参阅编写 使用方保留规则。
• 库 build 保留规则 在构建库时应用。只有当您决定在构建时部分优化库时，才需要这些规则。它们必须阻止移除库的公共 API，否则公共 API 将不会出现在库分发中，这意味着应用开发者无法使用该库。这些规则保存在文件 中，使用 proguardFiles 属性在您的 build.gradle.kts（或 build.gradle）文件中指定。如需了解详情，请参阅优化 AAR 库 build。

优化要求和准则

库中的 R8 配置会对使用应用的最终二进制文件大小和性能产生全局影响。除了通用的保留规则最佳 实践之外，库作者还必须遵守特定要求，并 考虑其他准则。

遵守优化要求

库中的低效是导致应用膨胀、内存浪费、启动缓慢和 ANR（应用无响应错误）的主要原因。库必须避免违反以下要求，以避免显著降低应用质量和用户体验。

• 没有广泛或软件包范围的保留规则： 您的库不得包含保留库中或另一个库中的大部分代码的广泛保留规则。广泛保留规则可能会在短期内解决崩溃问题，但它们会使使用您的库的所有应用的应用大小膨胀。

  请勿为库或其他引用的库中的软件包添加软件包范围的保留规则（例如 -keep class com.mylibrary.** {*; }）。此类规则会限制使用您的库的所有应用中这些软件包的优化。

• 没有不适当的全局规则： 切勿使用 全局选项，例如 -dontobfuscate 或 -allowaccessmodification。

• 尽可能使用 codegen 而不是反射： 如果可能，请使用 代码生成 (codegen) 而不是反射。codegen 和反射都是编程时避免样板代码的常用方法，但 codegen 与 R8 等应用优化器更兼容。

  使用 codegen 时，代码会在构建流程中进行分析和修改。由于编译后没有重大修改，因此优化器知道最终需要哪些代码，以及哪些代码可以安全移除。

  使用反射时，代码会在运行时进行分析和操作。由于代码在执行之前并未真正最终确定，因此优化器不知道哪些代码可以安全移除。它可能会移除在运行时通过反射动态使用的代码，从而导致用户应用崩溃。

  许多现代库都使用 codegen 而不是反射。如需了解常见入口点，请参阅 KSP，Room、Dagger2 和许多其他库都使用该入口点。

  注意： 在某些情况下，使用反射可能是合适的。 如需了解详情，请参阅何时可以使用反射。

• 支持 R8 完整模式： 启用 R8 完整模式后，您的库不应崩溃。R8 的完整模式是使用 R8 的推荐模式，并且自 AGP 8.0（于 2023 年稳定版发布）以来一直是默认模式。如果您的库在 R8 下崩溃，解决方案是识别特定的反射或 JNI 入口点并添加有针对性的规则，而不是保留整个软件包。

其他建议

除了优化要求之外，以下是其他建议。

• 请勿在库的使用方保留规则文件中使用 -repackageclasses。 不过，如需优化库 build，您可以在库的 build 保留规则文件中使用 -repackageclasses 带有内部软件包名称（例如 <your.library.package>.internal）的 。这可以提高库在未优化应用中的效率。不过，这通常没有必要，因为应用也应该进行优化。
• 在库的保留规则文件中声明库运行所需的任何属性，即使这些属性可能与 proguard-android-optimize.txt 中定义的属性重叠。
• 如果您需要在库分发中包含以下属性，请在库的 build 保留规则文件中维护这些属性，而不要在库的使用方保留规则文件中维护这些属性：
  • AnnotationDefault
  • EnclosingMethod
  • Exceptions
  • InnerClasses
  • RuntimeInvisibleAnnotations
  • RuntimeInvisibleParameterAnnotations
  • RuntimeInvisibleTypeAnnotations
  • RuntimeVisibleAnnotations
  • RuntimeVisibleParameterAnnotations
  • RuntimeVisibleTypeAnnotations
  • Signature
• 如果注解在运行时使用，库作者应在其使用方保留规则中保留 RuntimeVisibleAnnotations 属性。
• 库作者不应在其使用方保留规则中使用以下全局选项：
  • -include
  • -basedirectory
  • -injars
  • -outjars
  • -libraryjars
  • -repackageclasses
  • -flattenpackagehierarchy
  • -allowaccessmodification
  • -renamesourcefileattribute
  • -ignorewarnings
  • -addconfigurationdebugging
  • -printconfiguration
  • -printmapping
  • -printusage
  • -printseeds
  • -applymapping
  • -obfuscationdictionary
  • -classobfuscationdictionary
  • -packageobfuscationdictionary

何时可以使用反射

如果您必须使用反射，则只能反射到以下任一项中：

• 特定目标类型（特定接口实现者或子类）
• 使用特定运行时注解的代码

以这种方式使用反射可以限制运行时费用，并能够编写 有针对性的使用方保留规则。

这种特定且有针对性的反射形式是一种模式，您可以在 Android 框架（例如，在扩充 activity、视图和可绘制对象时）和 AndroidX 库（例如，在构建 WorkManager ListenableWorkers 或 RoomDatabases 时）中看到这种模式。相比之下，Gson 的开放式反射不适合在 Android 应用中使用。

常见误解

一些常见的误解可能会导致您错误地配置 R8。这些误解包括：

• 对 R8 优化的理解不正确：与普遍的 理解相反，R8 的优化不仅限于混淆，还包括代码缩减和逻辑优化，以及方法内联 和类合并技术。如需了解详情，请参阅 R8 优化 概览。

• 绕过混淆库的优化：一个常见的错误是 省略对库的优化，因为该库在编译为 AAR（Android 归档）或 JAR（Java 归档）时已进行优化或混淆。库构建期间的优化是有限的，您的应用不应通过在保留规则中包含库来停用对库的优化。如需了解详情，请参阅优化 AAR 库 build。

• 对 -keep 选项的理解不正确 ：-keep 规则会阻止 R8 运行其任何优化传递。如需了解详情， 请参阅选择正确的保留选项。

配置规则打包

为确保正确应用使用方保留规则，您必须根据库格式适当地打包这些规则。

AAR 库

如需为 AAR 库添加使用方规则，请使用 Android 库模块的 build 脚本中的 consumerProguardFiles 选项。如需了解详情，请参阅我们的 有关创建库模块的指南。

Kotlin

android {
    defaultConfig {
        consumerProguardFiles("consumer-proguard-rules.pro")
    }
    ...
}

Groovy

android {
    defaultConfig {
        consumerProguardFiles 'consumer-proguard-rules.pro'
    }
    ...
}

JAR 库

如需将规则与以 JAR 形式提供的 Kotlin 或 Java 库捆绑在一起，请将规则文件放在最终 JAR 的 META-INF/proguard/ 目录中，并使用任意文件名。 例如，如果您的代码位于 <libraryroot>/src/main/kotlin 中，请将使用方 规则文件放在 <libraryroot>/src/main/resources/META-INF/proguard/consumer-proguard-rules.pro 中，规则将捆绑在输出 JAR 中的正确位置。

通过检查规则是否位于 META-INF/proguard 目录中，验证最终 JAR 是否正确捆绑了规则。

优化 AAR 库 build（高级）

注意： Android 开发中的一个常见误解是，优化 AAR （Android 归档）或 JAR（Java 归档）使得在应用级 build 期间保留库软件包可以阻止 优化。 不过，整个程序优化（在应用级）比在库级进行的优化要有效得多。只有在应用 build 期间，当库作为应用的一部分包含在内时，R8 才能知道库的所有方法的使用方式以及传递的参数。

一般来说，您不应直接优化库 build，因为库构建期间的可能优化非常有限。作为库开发者，您需要在优化库之前，考虑库构建时间和应用构建时间期间的多个优化和保留行为阶段。

如果您仍然希望在构建时间优化库，Android Gradle 插件支持此操作。

Kotlin

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        configureEach {
            consumerProguardFiles("consumer-rules.pro")
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles
                getDefaultProguardFile('proguard-android-optimize.txt'),
                'proguard-rules.pro'
        }
        configureEach {
            consumerProguardFiles "consumer-rules.pro"
        }
    }
}

请注意，proguardFiles 的行为与 consumerProguardFiles 的行为截然不同：

• proguardFiles 在构建时间使用，通常与 getDefaultProguardFile("proguard-android-optimize.txt") 一起使用，以定义在库构建期间应保留库的哪一部分。至少，这是您的公共 API。
• 相比之下，consumerProguardFiles 会打包到库中，以影响稍后在使用您的库的应用的 build 期间发生的优化。

例如，如果您的库使用反射来构建内部类，您可能需要在 proguardFiles 和 consumerProguardFiles 中定义保留规则。

如果您在库的 build 中使用 -repackageclasses，请将类重新打包到库软件包内的子软件包中。 例如，使用 -repackageclasses 'com.example.mylibrary.internal' 而不是 -repackageclasses 'internal'。

支持不同的 R8 版本（高级）

您可以定制规则以定位到特定版本的 R8。这样，您的库就可以在使用较新 R8 版本的项目中以最佳方式运行，同时允许在具有较旧 R8 版本的项目中继续使用现有规则。

如需指定有针对性的 R8 规则，您需要在 AAR 的 classes.jar 内的 META-INF/com.android.tools 目录中或 JAR 的 META-INF/com.android.tools 目录中包含这些规则。

In an AAR library:
    proguard.txt (legacy location, the file name must be "proguard.txt")
    classes.jar
    └── META-INF
        └── com.android.tools (location of targeted R8 rules)
            ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
            └── ... (more directories with the same name format)

In a JAR library:
    META-INF
    ├── proguard/<ProGuard-rule-files> (legacy location)
    └── com.android.tools (location of targeted R8 rules)
        ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
        └── ... (more directories with the same name format)

在 META-INF/com.android.tools 目录中，可以有多个 子目录，其名称采用 r8-from-<X>-upto-<Y> 的形式，以指明 规则是为哪个 R8 版本编写的。每个子目录可以有一个或多个包含 R8 规则的文件，并具有任意文件名和扩展名。

请注意，-from-<X> 和 -upto-<Y> 部分是可选的，<Y> 版本 是 独占的，并且版本范围通常是连续的，但也可以 重叠。

例如，r8、r8-upto-8.0.0、r8-from-8.0.0-upto-8.2.0 和 r8-from-8.2.0 是表示一组有针对性的 R8 规则的目录名称。r8 目录下的规则可供任何 R8 版本使用。r8-from-8.0.0-upto-8.2.0 目录下的规则可供 R8 版本 8.0.0 到 8.2.0（但不包括 8.2.0）使用。

Android Gradle 插件使用该信息来选择当前 R8 版本可以使用的所有规则。如果库未指定有针对性的 R8 规则，Android Gradle 插件将从旧位置 (proguard.txt（适用于 AAR）或META-INF/proguard/<ProGuard-rule-files>（适用于 JAR））中选择规则。