面向库作者的优化

作为库的作者,您应确保应用开发者能够轻松地将您的库纳入其应用中,同时保持高质量的最终用户体验。您应确保您的库与 Android 优化兼容,无需进行额外设置;或者记录该库可能不适合在 Android 上使用。

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

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

使用代码生成而非反射

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

  • 借助代码生成,可以在构建过程中分析和修改代码。 由于编译后不会进行任何重大修改,因此优化器知道最终需要哪些代码,以及哪些代码可以安全地移除。
  • 通过反射,可以在运行时分析和操纵代码。由于代码在执行之前并未真正最终确定,因此优化器不知道哪些代码可以安全地移除。它可能会移除在运行时通过反射动态使用的代码,从而导致应用崩溃。

许多现代库都使用代码生成而非反射。如需了解由 RoomDagger2 和许多其他库使用的通用入口点,请参阅 KSP

何时可以反思

如果您必须使用反射,则只能反射到以下任一位置:

  • 特定目标类型(特定接口实现者或子类)
  • 使用特定运行时注释的代码

以这种方式使用反射可限制运行时费用,并支持编写有针对性的消费者保留规则

这种特定且有针对性的反射是您可以在 Android 框架(例如在膨胀 activity、视图和可绘制对象时)和 AndroidX 库(例如在构建 WorkManager ListenableWorkersRoomDatabases 时)中看到的模式。相比之下,Gson 的开放式反射不适合在 Android 应用中使用

媒体库中的保留规则类型

媒体库中可以包含两种不同的保留规则:

  • 消费者保留规则必须指定保留库所反映内容的规则。如果库使用反射或 JNI 调用其代码或客户端应用定义的代码,则这些规则需要描述需要保留哪些代码。库应打包使用与应用保留规则相同格式的消费者保留规则。这些规则会捆绑到库制品(AAR 或 JAR)中,并在使用相应库时在 Android 应用优化期间自动使用。这些规则保存在 build.gradle.kts(或 build.gradle)文件中通过 consumerProguardFiles 属性指定的文件中。如需了解详情,请参阅编写消费者保留规则
  • 在构建库时,系统会应用库 build 保留规则。如果您决定在 build 时部分优化库,才需要这些标志。 他们必须防止移除库的公共 API,否则库分发中将不包含公共 API,这意味着应用开发者无法使用该库。这些规则保存在 build.gradle.kts(或 build.gradle)文件中通过 proguardFiles 属性指定的文件中。如需了解详情,请参阅优化 AAR 库 build

编写消费者保留规则

除了常规的保留规则指南之外,以下建议专门针对库作者。

  • 请勿使用不当的全局规则 - 避免在库的消费者保留规则文件中放置 -dontobfuscate-allowaccessmodification 等全局设置,因为它们会影响使用您库的所有应用。
  • 请勿在库的消费者保留规则文件中使用 -repackageclasses。不过,为了优化库 build,您可以在库的 build keep 规则文件中使用带有内部软件包名称(例如 <your.library.package>.internal)的 -repackageclasses。即使使用该库的应用未经过优化,这样做也可以提高库的效率,但通常没有必要,因为应用也应进行优化。如需详细了解如何优化库,请参阅面向库作者的优化
  • 在库的保留规则文件中声明库正常运行所需的任何属性,即使这些属性可能与 proguard-android-optimize.txt 中定义的属性重叠。
  • 如果您需要在库分发中包含以下属性,请在库的 build keep 规则文件中保留这些属性,而不要在库的 consumer keep 规则文件中保留这些属性:
    • AnnotationDefault
    • EnclosingMethod
    • Exceptions
    • InnerClasses
    • RuntimeInvisibleAnnotations
    • RuntimeInvisibleParameterAnnotations
    • RuntimeInvisibleTypeAnnotations
    • RuntimeVisibleAnnotations
    • RuntimeVisibleParameterAnnotations
    • RuntimeVisibleTypeAnnotations
    • Signature
  • 如果在运行时使用注释,库作者应在其消费者保留规则中保留 RuntimeVisibleAnnotations 属性。
  • 库作者不应在其消费者保留规则中使用以下全局选项:
    • -include
    • -basedirectory
    • -injars
    • -outjars
    • -libraryjars
    • -repackageclasses
    • -flattenpackagehierarchy
    • -allowaccessmodification
    • -overloadaggressively
    • -renamesourcefileattribute
    • -ignorewarnings
    • -addconfigurationdebugging
    • -printconfiguration
    • -printmapping
    • -printusage
    • -printseeds
    • -applymapping
    • -obfuscationdictionary
    • -classobfuscationdictionary
    • -packageobfuscationdictionary

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(高级)

一般来说,您无需直接优化库 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 会打包到库中,以影响稍后在构建使用您的库的应用期间发生的优化。

例如,如果您的库使用反射来构建内部类,您可能需要在 proguardFilesconsumerProguardFiles 中同时定义 keep 规则。

如果您在库的 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> 版本是互斥的,版本范围通常是连续的,但也可以重叠。

例如,r8r8-upto-8.0.0r8-from-8.0.0-upto-8.2.0r8-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 插件将从旧位置(AAR 为 proguard.txt,JAR 为 META-INF/proguard/<ProGuard-rule-files>)选择规则。