LeakCanary 2.0 升级迁移指南从 1.x 重写 API 到新架构的完整实战手册【免费下载链接】leakcanaryA memory leak detection library for Android.项目地址: https://gitcode.com/gh_mirrors/le/leakcanaryLeakCanary 2 是一次推翻重来的大版本重写核心变化包括全新的低内存堆分析引擎 Shark、100% Kotlin 化的内部实现以及一套职责更清晰的配置 API。本文以官方升级文档为主线结合当前仓库源码完整讲解从 1.x 迁移到 2.x 时必须掌握的五件事依赖声明、默认安装、观察器 APIRefWatcher → ObjectWatcher、配置模型AppWatcher / LeakCanary 双单例以及分析结果监听与库泄漏匹配的新写法帮助你无痛完成升级并理解新架构背后的设计动机。上图是 2.0 的泄漏列表与详情界面一次分析可以输出多条不同的泄漏4 Distinct Leaks并按泄漏类型分组展示同时支持 Library Leak 标签与 Share Heap Dump file 分享堆转储文件——这正是新分析引擎带来的直接变化。2.0 是一次彻底重写先理解变化的全貌升级文档开篇即给出高层次的变更清单这是理解后续所有迁移动作的基石新的堆分析引擎从头重写内存占用降低到原来的十分之一这就是 SharkSmart Heap Analysis Reports for Kotlin。Shark 以分层方式发布Shark Hprof 负责读写 hprof 记录、Shark Graph 负责遍历堆对象图、Shark 生成堆分析报告、Shark Android 提供 Android 启发式分析再往上才是 LeakCanary 本体。API 全面更新简化配置方式并开放对新分析引擎的访问。内部实现 100% KotlinShark 重度依赖 sealed class 与 sequence 来节省内存参见 docs/shark.md。一次分析检出多个泄漏并按泄漏类型分组不再像 1.x 那样只汇报单条泄漏链。理解这四点之后下面逐一处理迁移中会遇到的每个具体问题。依赖变化no-op 消失升级前1.xdependencies { debugImplementation com.squareup.leakcanary:leakcanary-android:1.6.3 releaseImplementation com.squareup.leakcanary:leakcanary-android-no-op:1.6.3 // Optional, if you use support library fragments: debugImplementation com.squareup.leakcanary:leakcanary-support-fragment:1.6.3 }升级后2.xdependencies { debugImplementation com.squareup.leakcanary:leakcanary-android:当前发布版本号 }值得注意的几点leakcanary-android-no-op构件已消失。官方 FAQ 式的问答很关键如果不再有 no-op如何在 release 构建中确保 LeakCanary 不运行答案是——只要把leakcanary-android声明为debugImplementationrelease 构建中就不会有任何引用 LeakCanary 的代码因为该依赖根本没有被打进 release 变体。LeakCanary 不再依赖 support library也不依赖 AndroidX。相应的leakcanary-support-fragment构件随之取消。AndroidX fragment 的检测是自动的只要你的 classpath 里有 AndroidX fragments 依赖LeakCanary 就会自动开始观察它们无需额外配置。默认安装代码不再需要 Application 子类升级前1.x1.x 要求开发者手动在 Application 里安装并显式判断分析进程public class ExampleApplication extends Application { Override public void onCreate() { super.onCreate(); if (LeakCanary.isInAnalyzerProcess(this)) { // This process is dedicated to LeakCanary for heap analysis. // You should not init your app in this process. return; } LeakCanary.install(this); // Normal app init code... } }升级后2.x默认安装不需要任何代码。值得注意的几点LeakCanary 自动安装自身在object-watcher-android-core中AppWatcher.manualInstall()会在主进程应用启动时以默认参数被自动调用参见 AppWatcher.kt。只有在需要定制安装参数例如只安装部分 watcher时才需要先通过leak_canary_watcher_auto_install布尔资源禁用自动安装再手动调用。堆分析现在运行在主进程不再有独立的 analyzer 进程因此LeakCanary.isInAnalyzerProcess()也不再需要调用。需要说明的是如果遇到主进程内存压力过大仍然可以主动引入leakcanary-android-process把分析搬到独立进程详见 docs/recipes.md但这属于可选优化而非默认行为。获取观察器RefWatcher → ObjectWatcher如果你在业务代码中持有过RefWatcher升级后的替换非常简单升级前1.xval refWatcher: RefWatcher LeakCanary.installedRefWatcher()升级后2.xval objectWatcher: ObjectWatcher AppWatcher.objectWatcher从源码看AppWatcher.objectWatcher是一个配置好的ObjectWatcher实例它基于SystemClock.uptimeMillis()时钟并通过主线程 Handler 延迟执行检查对象是否仍强可达的任务参见 AppWatcher.kt。ObjectWatcher.watch(watchedObject, description)会为该对象创建KeyedWeakReference并在设定的延迟默认 5 秒retainedDelayMillis之后检查弱引用是否被清除若仍被强引用则判定为 retained 并通知监听器参见 ObjectWatcher.kt。解决 RefWatcher 出现在 release 代码中的编译错误由于 no-op 构件已删除如果你在非 debug 代码中使用了RefWatcher升级后会直接编译失败。好消息是ObjectWatcher现在位于独立的object-watcher构件中完全适合在 release 构建中使用。官方给出两种方案方案一把object-watcher-android加进 release 构建dependencies { implementation com.squareup.leakcanary:leakcanary-object-watcher-android:当前发布版本号 }这个构件带来的行为与代价会自动为销毁的 Activity、Fragment 以及任何传给AppWatcher.objectWatcher的实例保持弱引用不会触发堆转储或 LeakCanary 的其他任何行为代码量很小对 release 应用几乎没有影响可以用来统计 retained 对象数量例如为 OutOfMemoryError 崩溃添加元数据val retainedObjectCount AppWatcher.objectWatcher.retainedObjectCountretainedObjectCount返回当前被认为已保留retained的被观察对象数量这一用法在 docs/recipes.md 的 Counting retained instances in release builds 一节中同样给出了完整示例。方案二自定义ObjectWatcher接口如果你不想在 release 构建里引入任何额外依赖可以抽象一个自己的接口// In shared code interface MaybeObjectWatcher { fun watch(watchedObject: Any, description: String) object None : MaybeObjectWatcher { override fun watch(watchedObject: Any, description: String) { } } } // In debug code class RealObjectWatcher : MaybeObjectWatcher { override fun watch(watchedObject: Any, description: String) { AppWatcher.objectWatcher.watch(watchedObject, description) } }然后 release 代码中使用MaybeObjectWatcher.None空实现零开销debug 代码中使用RealObjectWatcher。配置 LeakCanaryAppWatcher 与 LeakCanary 职责分离2.0 最核心的配置模型变化是职责分离AppWatcher负责检测 retained 对象LeakCanary负责堆转储与分析。两者的配置都是数据类可以随时整体替换。升级前1.xpublic class DebugExampleApplication extends ExampleApplication { Override protected void installLeakCanary() { RefWatcher refWatcher LeakCanary.refWatcher(this) .watchActivities(false) .buildAndInstall(); } }升级后2.xAppWatcher 侧——配置观察什么通过替换AppWatcher.config实现class DebugExampleApplication : ExampleApplication() { override fun onCreate() { super.onCreate() AppWatcher.config AppWatcher.config.copy(watchFragmentViews false) } }LeakCanary 侧——配置何时转储、如何分析通过替换 LeakCanary.config 实现disableLeakCanaryButton.setOnClickListener { LeakCanary.config LeakCanary.config.copy(dumpHeap false) }LeakCanary.config是一个Volatile var每次被替换时源码都会记录配置变更日志并同步更新堆转储控制状态参见 LeakCanary.kt因此运行时动态切换配置是安全且被官方支持的。理解 LeakCanary.Config 的默认值结合 LeakCanary.kt 的源码LeakCanary.Config数据类的核心字段与默认值如下配置项默认值含义dumpHeaptrue是否在 retained 实例足够时转储堆。设为false可临时停用如产品演示AppWatcher仍会跟踪对象恢复true后会补查dumpHeapWhenDebuggingfalse调试器挂载时是否转储断点会制造临时泄漏默认不转储retainedVisibleThreshold5应用可见时达到该数量的 retained 实例才转储应用不可见时按retainedDelayMillis默认 5 秒转储。阈值越高打扰越少但也可能漏掉泄漏referenceMatchersAndroidReferenceMatchers.appDefaults已知引用模式列表忽略或标记为库泄漏objectInspectorsAndroidObjectInspectors.appDefaults为堆中的对象提供泄漏与否的洞察可在泄漏链上自动添加说明与标签metadataExtractorAndroidMetadataExtractor从 hprof 提取元数据写入HeapAnalysisSuccess.metadata在后台线程执行computeRetainedHeapSizetrue是否计算 retained 堆大小含与 Java 对象关联的原生内存如 Bitmap。开启会拖慢分析maxStoredHeapDumps7设备上为当前包保留的堆转储文件数量上限超过后删除旧文件leakingObjectFinderKeyedWeakReferenceFinder找出泄漏对象可替换为FilteringLeakingObjectFinder扫描全堆以发现更多泄漏heapDumperAndroidDebugHeapDumper堆转储实现可替换核心实现eventListenersLogcat / Toast / Notification或 TV 分析器订阅 LeakCanary 事件流showNotificationstrue是否显示 LeakCanary 通知对于 Java 开发者Config提供了仅限 Java 使用的newBuilder()参见 LeakCanary.ktLeakCanary.Config config LeakCanary.getConfig().newBuilder() .retainedVisibleThreshold(3) .build(); LeakCanary.setConfig(config);在 instrumentation 测试中运行 LeakCanary升级前1.x1.x 需要在build.gradle中配置测试监听器并在测试 Application 中安装专门的 refWatcherdependencies { androidTestImplementation com.squareup.leakcanary:leakcanary-android-instrumentation:${leakCanaryVersion} } android { defaultConfig { // ... testInstrumentationRunner android.support.test.runner.AndroidJUnitRunner testInstrumentationRunnerArgument listener, com.squareup.leakcanary.FailTestOnLeakRunListener } }public class InstrumentationTestExampleApplication extends DebugExampleApplication { Override protected void installLeakCanary() { InstrumentationLeakDetector.instrumentationRefWatcher(this) .buildAndInstall(); } }升级后2.x删除上面所有旧的测试相关泄漏检测代码然后按照 docs/ui-tests.mdUI 测试中的泄漏检测一文重新接入。新的工作方式完全不同只需在测试依赖中加入leakcanary-android-instrumentation然后在测试任意位置调用LeakAssertions.assertNoLeaks()若检测到应用泄漏会抛出NoLeakAssertionFailedError。还可以用DetectLeaksAfterTestSuccess测试规则在测试结束时自动断言或用SkipLeakDetection跳过部分断言非常适合接入 CI 防止新泄漏被合并进代码库。分析监听器 / 上传到服务器升级前1.x1.x 通过继承DisplayLeakService并覆写回调来上传分析结果还需要在 Manifest 中注册该 Servicepublic class LeakUploadService extends DisplayLeakService { Override protected void afterDefaultHandling(HeapDump heapDump, AnalysisResult result, String leakInfo) { // TODO Upload result to server } }RefWatcher refWatcher LeakCanary.refWatcher(this) .listenerServiceClass(LeakUploadService.class) .buildAndInstall();?xml version1.0 encodingutf-8? manifest xmlns:androidhttp://schemas.android.com/apk/res/android application android:namecom.example.DebugExampleApplication service android:namecom.example.LeakUploadService / /application /manifest升级后2.x改为实现OnHeapAnalyzedListener接口并通过LeakCanary.config注入。如果需要保留默认行为通知 保存结果保留一个DefaultOnHeapAnalyzedListener实例并在自定义逻辑之后委托给它class LeakUploader : OnHeapAnalyzedListener { val defaultListener DefaultOnHeapAnalyzedListener.create() override fun onHeapAnalyzed(heapAnalysis: HeapAnalysis) { TODO(Upload heap analysis to server) // Delegate to default behavior (notification and saving result) defaultListener.onHeapAnalyzed(heapAnalysis) } } class DebugExampleApplication : ExampleApplication() { override fun onCreate() { super.onCreate() LeakCanary.config LeakCanary.config.copy( onHeapAnalyzedListener LeakUploader() ) } }不再需要 Service、不再需要 Manifest 注册——配置全部收敛到 Kotlin 代码中。匹配已知库泄漏ExcludedRefs → ReferenceMatcher升级前1.x1.x 使用ExcludedRefs.Builder按类 静态字段排除引用ExcludedRefs excludedRefs AndroidExcludedRefs.createAppDefaults() .staticField(com.samsing.SomeSingleton, sContext) .build(); RefWatcher refWatcher LeakCanary.refWatcher(this) .excludedRefs(excludedRefs) .buildAndInstall();升级后2.x使用referenceMatchers列表在AndroidReferenceMatchers.appDefaults基础上追加自定义匹配器LeakCanary.config LeakCanary.config.copy( referenceMatchers AndroidReferenceMatchers.appDefaults AndroidReferenceMatchers.staticFieldLeak( com.samsing.SomeSingleton, sContext ) )需要注意的两点没有与ExcludedRefs.Builder.clazz()等价的 API。官方明确说明这是有意的设计——按类整体排除曾被滥用容易掩盖真正的应用泄漏。如需忽略特定 Activity 或 Fragment 类请参考 docs/recipes.md 中 Ignoring specific activities or fragment classes 一节的做法例如关闭自动观察后手动筛选传入watch的对象。更完整的自定义staticFieldLeak写法还可以附加description与patternApplies条件例如限定厂商与系统版本详见 docs/recipes.md 的 Matching known library leaks 一节。公共 API 包名变化这是迁移中容易被编译器直接提醒的一处改动升级前所有公共 API 都在com.squareup.leakcanary.*包下。升级后所有公共 API 都在leakcanary.*包下AppWatcher、ObjectWatcher、LeakCanary、OnHeapAnalyzedListener等均在leakcanary包中可从 LeakCanary.kt 与 AppWatcher.kt 的包声明直接确认。升级时只需将 import 语句中的com.squareup.leakcanary批量替换为leakcanary即可。升级检查清单综合全文从 1.x 迁移到 2.x 的完整动作可以浓缩为一份清单依赖删除leakcanary-android-no-op与leakcanary-support-fragment仅保留debugImplementation com.squareup.leakcanary:leakcanary-android:版本号。安装代码删除Application.onCreate()中所有LeakCanary.install()与isInAnalyzerProcess()相关代码2.0 自动安装、主进程分析。RefWatcher替换为AppWatcher.objectWatcherrelease 侧代码若引用了旧 API选择引入object-watcher-android或自行抽象接口。配置watchActivities(false)等由LeakCanary.refWatcher()链式调用的配置分别迁移到AppWatcher.config.copy(...)与LeakCanary.config.copy(...)。测试删除FailTestOnLeakRunListener等旧测试接线改用 docs/ui-tests.md 中的LeakAssertions.assertNoLeaks()与DetectLeaksAfterTestSuccess规则。分析结果上传把继承DisplayLeakService的写法改为实现OnHeapAnalyzedListener并注入LeakCanary.config。库泄漏匹配把ExcludedRefs.Builder改写为referenceMatchers AndroidReferenceMatchers.appDefaults ...。包名批量更新 import 为leakcanary.*。完成以上步骤后你的应用即运行在 2.x 的新架构上更省内存的 Shark 分析引擎、一次分析输出多条分组泄漏、更简洁且可运行时变更的配置模型以及不再依赖 support library 的零侵入自动安装。【免费下载链接】leakcanaryA memory leak detection library for Android.项目地址: https://gitcode.com/gh_mirrors/le/leakcanary创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考