Atlas 动态更新模块 atlas-update 深度解析:bundle 热更新原理与 API 实战指南
Atlas 动态更新模块 atlas-update 深度解析:bundle 热更新原理与 API 实战指南
导读
atlas-update 是 Atlas 动态组件框架(Android Dynamic Component Framework)中负责 bundle 动态更新 的核心模块。它承载了"通过 tpatch 包对已发布 App 中的 bundle 进行增量/全量升级"的完整链路:从更新信息的模型定义(UpdateInfo.java),到合并 patch 与原始 apk 中 bundle 的独立进程服务(DexMergeService),再到新 bundle 的重新安装与列表信息更新。读完本文,你将掌握 AtlasUpdater.update() 的完整调用方式、UpdateInfo 各字段的语义、五种更新的底层执行步骤,以及 dexpatch 冷热补丁体系的设计思路,可直接用于理解或二次开发自己的 bundle 动态更新方案。
一、特性总览与核心注意点
按照仓库文档 atlas-update/README.zh-cn.md 的定义,该模块的核心 feature 是 bundle 的动态更新,即在 App 发布后,通过下发补丁包对已安装 App 内部的动态组件(bundle)进行增量升级,而无需重新发布整个 APK。
使用前必须牢记一个关键差异:
Atlas 更新不像 hotpatch 那样立即生效,而是需要用户在 patch 成功安装之后,重启应用才能生效。
这一点与热补丁方案有本质区别:atlas-update 走的是"冷启动生效"路径——补丁被下载并安装到指定目录后,只有在下一次应用进程启动时,框架才会基于新的 bundle 列表与文件完成加载。源码层面也能印证:PatchInstaller 最终调用的是框架的 Framework.update() 进行版本切换,而真正的类加载发生在下次进程启动时由 Atlas 运行时完成。同时,该模块支持 updateInfo.dexPatch 标记来区分普通 bundle 更新与 dexpatch(见下文第四章)。
二、核心接口 API:AtlasUpdater.update()
更新主入口位于 AtlasUpdater.java:
public static void update(UpdateInfo updateInfo, File patchFile) throws MergeException, BundleException
- 入参
updateInfo:更新的基础信息,见第三章; - 入参
patchFile:tpatch 包文件,即从服务端下发的补丁包; - 异常:
MergeException(bundle dex 合并失败,定义于 MergeException.java)与 OSGi 语义的BundleException(bundle 安装/校验失败)。
从源码看,update() 的执行逻辑非常紧凑(AtlasUpdater.java):
public static void update(UpdateInfo updateInfo, File patchFile) throws MergeException, BundleException {
if (null == updateInfo || updateInfo.dexPatch) {
// with dexPatch, please call "dexPatchUpdate"
return;
}
MergeCallback mergeCallback = new MergeCallback() { ... };
PatchMerger patchMerger = new PatchMerger(updateInfo, patchFile, mergeCallback);
try {
patchMerger.merge();
} catch (IOException e) {
e.printStackTrace();
}
PatchInstaller patchInstaller = new PatchInstaller(patchMerger.mergeOutputs, updateInfo);
patchInstaller.install();
PatchCleaner.clearUpdatePath(updateInfo.workDir.getAbsolutePath());
}
值得注意的两个细节:
- 入口分流:当
updateInfo == null或updateInfo.dexPatch == true时,update()直接返回,引导调用方走dexpatchUpdate()分支。普通 bundle 更新与 dexpatch 是两套不同的更新通道。 - 合并结果透传:合并阶段通过
MergeCallback.onMergeResult(boolean result, String bundleName)回调逐 bundle 上报合并成败,便于上层做埋点与监控。
另外,模块还提供了面向 dexpatch 的入口:
public static void dexpatchUpdate(Context context, UpdateInfo updateInfo, File patchFile,
final IDexpatchMonitor coldMonitor, boolean enableHot,
IDexpatchMonitor hotMonitor) throws Exception
以及省略热补丁开关的简化重载(此时 enableHot=false、hotMonitor=null,只做冷补丁)。IDexpatchMonitor 接口定义了两个回调,分别对应合并与安装两个阶段:
public interface IDexpatchMonitor {
public void merge(boolean success, String bundleName, long version, String errMsg);
public void install(boolean success, String bundleName, long version, String errMsg);
}
dexpatchUpdate() 的完整流程是:先校验当前进程的 versionName 是否与 updateInfo.baseVersion 一致(不一致直接返回,避免错误基线打补丁);若开启热补丁,则先通过 UpdateBundleDivider 划分出 PATCH_DEX_HOT 类型的 bundle,交给 DexPatchUpdater.installHotPatch() 立即生效;随后过滤出 PATCH_DEX_COLD 类型的 bundle,走 installColdPatch() 冷安装通道。
三、更新基础信息模型:UpdateInfo
更新信息的载体是 UpdateInfo.java,它实现了 Serializable,可以随 patch 一起被序列化传输或持久化。字段语义如下:
| 字段 | 类型 | 说明 |
|---|---|---|
baseVersion |
String | 当前的客户端版本,作为合并的基线版本号 |
updateVersion |
String | 更新后的客户端版本 |
updateBundles |
List<Item> | 本次需要更新的模块(bundle)列表信息 |
workDir |
File | 更新工作目录,默认 getCacheDir()/atlas_update,用于存放合并中间产物 |
dexPatch |
boolean | 是否走 dexpatch 通道(源码中新增的开关) |
lowDisk |
boolean | 低磁盘空间标记,影响主 dex 的合并策略(见第四章) |
其中 workDir 的默认值来自运行时全局变量:new File(RuntimeVariables.androidApplication.getCacheDir(), "atlas_update"),即应用私有缓存目录下的 atlas_update 文件夹。
更新模块信息 Item
每个待更新模块由内部静态类 UpdateInfo.Item(同样实现 Serializable)描述,README 中列出的核心字段:
| 字段 | 类型 | 说明 |
|---|---|---|
isMainDex |
boolean | 是不是主 dex(com.taobao.maindex) |
name |
String | bundle 的名称 |
version |
String | bundle 版本信息 |
srcVersion |
String | bundle 的代码仓库对应的版本 |
dependency |
List<String> | 依赖的 bundle 列表 |
结合源码 UpdateInfo.java,Item 在实际实现中比 README 描述的字段更丰富,完整的补充字段包括:
unitTag/srcUnitTag:bundle 的发布单元标识与源单元标识,实际合并时以srcUnitTag定位基线版本文件(见第四章);inherit:标记该 bundle 版本与新版 App 天然兼容,无需更新,安装阶段会直接以 "inherit" 占位继承(见 PatchInstaller.java);patchType:dexpatch 补丁类型,取值如下:PATCH_DYNAMIC_ = 0:动态更新(普通 bundle 更新)PATCH_DEX_COLD = 1:dexpatch 冷补丁(重启生效)PATCH_DEX_HOT = 2:dexpatch 热补丁(立即生效)PATCH_DEX_C_AND_H = 3:冷热都打
reset:是否回滚到基线版本的 bundle(回滚时安装阶段使用 "reset" 占位);resetHotPatch:是否重置热补丁;dexpatchVersion:dexpatch 补丁版本号,安装/过滤时用于版本比较(大于已安装版本才会安装)。
此外 Item 提供了静态工厂 makeCopy(Item origin),用于在 UpdateBundleDivider 划分冷热补丁列表时深拷贝条目,避免改动原始列表。
四、更新过程五步走:从 tpatch 到新 bundle 落地
README 将更新过程概括为五步,这里结合源码逐一展开:
第 1 步:解压 patch 包
tpatch 包本质是一个 zip 文件(ZipUtils.java 提供了完整的 unzip(zipFilename, outputDirectory) 解压工具,按 zip entry 递归创建目录并写出文件)。在合并阶段,PatchMerger.merge() 直接以 new ZipFile(patchFile) 的方式打开 patch,并通过 patchZip.getEntry(entryName) 定位每个 bundle 对应的补丁条目。
tpatch 包内条目的命名规则(由源码推导):普通 bundle 的补丁文件名为 lib<bundle_name以.替换为_>.so,例如 bundle com.taobao.dynamic.test 对应 libcom_taobao_dynamic_test.so;dexpatch 场景下则是 lib<bundle_name>_.../hot.dex 目录(见 DexPatchUpdater.installHotPatch() 中对 hot.dex 条目的读取)。
第 2 步:合并 patch 包和原始 apk 中的 bundle(在独立进程进行)
这是整个更新链路的核心。PatchMerger 构造函数会打开原始 APK(new ZipFile(RuntimeVariables.androidApplication.getApplicationInfo().sourceDir)),随后 merge() 中针对每个待更新 bundle 分三种策略处理:
- 全量部署:当 patch 包中存在该 bundle 的完整
libxxx.so条目,且该 bundle 不支持合并(supportMerge(bundleName)为 false)时,直接把 patch 中的条目拷贝到工作目录,作为新 bundle 文件;mergeOutputs中记录bundleName -> (文件路径, item)。 - 差量部署(dex 合并):否则需要找到原始 bundle 文件(
findOriginalBundleFile()),与新 bundle 的 dex 做合并。查找基线 bundle 的优先级为:当前已安装的BundleImpl归档(需满足未打 dexpatch 且unique_tag与srcUnitTag一致)→Framework.getInstalledBundle(bundleName, srcUnitTag)→ 从 APK 中提取原始 bundle(getOriginalBundleFromApk(),依次尝试 files 目录下 lib、nativeLibraryDir、assets 资源与 APK 内lib/armeabi/条目)。 - 回滚:当
item.reset == true时,mergeOutputs记录空路径"",表示回滚到基线。
独立进程合并:需要合并的 bundle 会构造 MergeObject(originalPath, bundleName, targetPath) 列表,随后通过 DexMergeClient 绑定独立的 :dexmerge 进程服务 DexMergeService(在 AndroidManifest.xml 中声明为 android:process=":dexmerge"),由该进程完成真正的 dex 合并,避免在主进程造成卡顿或内存压力。DexMergeClient 内部实现了:
prepare():绑定服务并阻塞等待连接建立(超时 60 秒),绑定失败自动 unbind;dexMerge():通过IDexMergeBinder发起合并请求,通过IDexMergeCallback回调逐 bundle 上报onMergeFinish、整体完成上报onMergeAllFinish;- binder 死亡重试机制:注册
IBinder.DeathRecipient,当服务进程死亡时自动重连并重试最多 3 次。
合并的底层能力来自仓库内置的 dx 合并器(dexmerge/dx/merge/DexMerger.java)以及 patch 目录下的补丁(0001-patch-code.patch)。
第 3 步:将合并后新的 bundle 进行重新安装
合并完成后,PatchInstaller.install() 负责把产物安装进 Atlas 框架:
- 遍历
mergeOutputs,按 bundle 名、文件路径、升级版本(普通更新用unitTag,dexpatch 用dexpatchVersion)组装数组; - 特殊占位处理:
reset的 bundle 使用new File("reset")占位并记录版本-1,inherit的 bundle 使用new File("inherit")占位; - 校验:若 merge 输出为空则抛
BundleException("merge bundles is empty");bundle 文件不存在则抛BundleException("bundle input is wrong"); - 最终调用框架层
Framework.update(!updateInfo.dexPatch, bundleNameArray, bundleFilePathArray, updateVersionArray, dexPatchVersionArray, updateInfo.updateVersion, updateInfo.lowDisk),将新的 bundle 文件与版本信息登记进 Atlas 的运行时安装表。
第 4 步:更新 bundle 的列表信息
Framework.update() 内部会同步更新 bundle 的列表/版本信息(对应 Atlas 运行时的 BaselineInfoManager 等版本信息管理组件,见 atlas-core 目录下的运行时实现),使新版本 bundle 在下次启动时能够被框架正确识别、加载与索引。
第 5 步:等待用户启动重新加载
更新安装完成后并不立即生效。AtlasUpdater.update() 最后调用 PatchCleaner.clearUpdatePath() 递归清理工作目录 atlas_update(删除全部临时文件与目录),释放磁盘空间。而新的 bundle 要真正被加载,需要用户重启应用,Atlas 运行时在下次启动时依据已登记的版本信息完成装载——这正对应 README 强调的"重启后生效"特性。
五、dexpatch 补丁体系:热补丁与冷补丁分工
atlas-update 在 README 基础能力之外,还内置了一套完整的 dexpatch 补丁体系(源码新增,属于对文档的深化补充):
- UpdateBundleDivider.dividePatchInfo():根据
patchType把更新列表划分为冷补丁子集与热补丁子集;PATCH_DEX_C_AND_H类型的条目会同时进入两个子集(深拷贝并改写patchType)。 - DexPatchUpdater 提供三个核心方法:
installHotPatch():读取 patch 包中每个 bundle 的hot.dex条目(主 dex 对应com.taobao.maindex/hot.dex),交给AtlasHotPatchManager.getInstance().installHotFixPatch()完成即时生效的热修复安装;installColdPatch():走与普通更新相同的PatchMerger.merge()+PatchInstaller.install()链路,但合并结果只保留成功 bundle(文件存在或 reset),随后通过BaselineInfoManager.instance().getDexPatchBundles()核对安装结果并回调监控;filterNeedHotPatchList()/filterNeedColdPatchList():基于已安装版本做幂等过滤——仅当本地未安装或dexpatchVersion大于已安装版本时才真正执行安装;reset回滚条目则仅当本地已安装且未回滚时才加入列表。
这套"热补丁即时修复 + 冷补丁重启生效"的双通道设计,使 Atlas 既能快速止血线上小问题(hot),又能完整替换 bundle dex 做版本演进(cold),且两套通道共用 IDexpatchMonitor 回调上报 merge/install 两个阶段的成功、bundle 名、版本号与错误信息。
六、组件声明与集成要点
更新模块的组件声明集中在 atlas-update/src/main/AndroidManifest.xml:
DexMergeService:以独立进程:dexmerge运行的合并服务,通过 intent-filter 暴露 actioncom.taobao.atlas.dexmerge.DexMergeService,由DexMergeClient在合并前 bind 拉起;AwoPatchReceiver:广播接收器(AwoPatchReceiver.java),监听以下四个 action,分别对应动态更新的触发与回滚:com.taobao.atlas.intent.PATCH_APP:普通 bundle 更新com.taobao.atlas.intent.DEX_PATCH_APP:dexpatch 更新com.taobao.atlas.intent.ROLLBACK_PATCH:普通更新回滚com.taobao.atlas.intent.ROLLBACK_DEX_PATCH:dexpatch 回滚
- SDK 约束:
minSdkVersion=14、targetSdkVersion=23。
集成时,宿主工程需要将 atlas-update 作为依赖引入(其 AndroidManifest.xml 中的 service 与 receiver 会合并进宿主),并确保 :dexmerge 进程的声明与 com.taobao.atlas.dexmerge 包下的服务类在混淆时被保留(项目配置可参考 atlas-update/gradle.properties 与模块自身的构建配置)。服务端下发 tpatch 包后,客户端在拿到 UpdateInfo(含 baseVersion、updateVersion、updateBundles 列表)与 patch 文件后,调用 AtlasUpdater.update() 即可完成一次完整的动态更新。
七、小结
atlas-update 为 Atlas 动态组件框架提供了完整的 bundle 动态更新能力:以 UpdateInfo 描述更新意图,以 tpatch(zip)承载补丁内容,以独立 :dexmerge 进程完成 dex 合并,以 PatchInstaller 完成框架层安装,最后等待用户重启加载生效。同时它在基础动态更新之上进一步实现了 dexpatch 冷热双通道补丁体系,兼顾"即时修复"与"版本演进"两种诉求。理解这一模块的调用链(AtlasUpdater.update → PatchMerger.merge → DexMergeClient/DexMergeService → PatchInstaller.install → Framework.update),就掌握了 Atlas 动态更新机制的核心脉络。
关键源码索引:
- 更新主入口:AtlasUpdater.java
- 更新信息模型:UpdateInfo.java
- 补丁合并:PatchMerger.java
- 独立进程合并客户端/服务:DexMergeClient.java、DexMergeService.java
- 补丁安装:PatchInstaller.java
- dexpatch 冷热通道:DexPatchUpdater.java、UpdateBundleDivider.java
- 组件声明:atlas-update/src/main/AndroidManifest.xml
- 官方说明文档:atlas-update/README.zh-cn.md