Atlas Bundle 动态更新模块 atlas-update 详解:接口、数据模型与合并安装全流程
Atlas Bundle 动态更新模块 atlas-update 详解:接口、数据模型与合并安装全流程
atlas-update 是 Atlas 动态组件框架中负责 Bundle 动态更新(增量发布)的核心模块,它通过 tpatch 补丁包把新版本 Bundle 与旧版本 APK 内的 Bundle 在独立进程中合并,再重新安装并更新 Bundle 列表信息,实现不重新发包的客户端升级。读完本文,你将掌握 AtlasUpdater#update 主入口的完整用法、UpdateInfo/Item 数据模型的每个字段含义,以及解压、合并、安装、清理四步流水线在源码层面的真实实现细节。
模块定位与核心特性
atlas-update 是一个独立的 Android Library 模块(atlas-update/),其职责非常单一:接收 tpatch 补丁包与更新信息,完成 Bundle 级动态更新。它不负责补丁包的生成(那由 atlas-gradle-plugin 中的构建任务完成),也不负责补丁下载与版本校验(那通常由宿主 App 自身或 atlas-demo 中的演示工程配合完成),而是专注于"拿到补丁后如何在运行时安全落地"。
模块的核心能力(即 README.md 描述的 Feature):
- Bundle 动态更新:允许只更新部分 Bundle(含主 dex),而无需用户重新安装整个 APK;
- 独立进程合并:补丁与原 APK 中 Bundle 的 dex 合并发生在独立进程中,避免合并大 dex 时阻塞主线程、拖垮 UI;
- 重启生效:更新安装完成后并不会像 hotpatch 那样立即生效,需要用户重启应用后由 Atlas 运行时加载新 Bundle。
注意:atlas-update 中的
update接口面向的是 Bundle 整体更新(tpatch);而模块内另有一套dexpatchUpdate接口,面向 DexPatch(类级补丁),两者共享大部分合并与安装基础设施,但生效机制不同(详见下文)。
与 hotpatch 的关键区别:为什么需要重启
README.md 在 Feature 之后专门用 Note 强调:
Unlike hotpatch takes effect immediately, Atlas bundle update requires the user to restart the application after the patch installed.
(与 hotpatch 立即生效不同,Atlas Bundle 更新在补丁安装后需要用户重启应用才能生效。)
原因可以从源码结构推断:Bundle 动态更新会把合并出的新 libxxx.so(Bundle 归档文件)安装到 Bundle 存储区,并写入新的 Bundle 版本列表;而 Atlas 的 Bundle 类加载器(classloader)与资源加载器通常在应用启动阶段基于该列表完成初始化。正在运行的进程无法安全地替换已加载的 dex,因此必须等下次冷启动时 Framework 才会加载新版本的 Bundle。而 DexPatch 模式则不同,它支持 hot patch 立即生效(见下文 DexPatchUpdater.installHotPatch)。
核心 API:AtlasUpdater#update
动态更新的主入口是 com.taobao.atlas.update.AtlasUpdater#update,定义于 AtlasUpdater.java:
/**
* 更新主入口
* @param updateInfo 更新的基础信息
* @param patchFile tpatch包
* @throws MergeException
* @throws BundleException
*/
public static void update(UpdateInfo updateInfo, File patchFile) throws MergeException, BundleException
两个入参的职责非常清晰:
| 参数 | 类型 | 说明 |
|---|---|---|
updateInfo |
UpdateInfo |
更新的基础信息:当前版本、目标版本、待更新 Bundle 列表、工作目录等 |
patchFile |
File |
tpatch 补丁包文件(zip 格式,内含各 Bundle 的新版本归档) |
该方法在 AtlasUpdater.java 中的真实执行序列如下:
- 入口校验:若
updateInfo == null || updateInfo.dexPatch,直接返回(dexPatch 场景需改走dexpatchUpdate); - 注册合并回调:构造
MergeCallback,用于逐 Bundle 上报合并结果(成功打[dexmerge] merge bundle xxx success日志,失败打 error); - 合并:
new PatchMerger(updateInfo, patchFile, mergeCallback).merge(),产出合并后的 Bundle 归档文件集合mergeOutputs; - 安装:
new PatchInstaller(patchMerger.mergeOutputs, updateInfo).install(),调用底层 Framework 完成 Bundle 安装; - 清理:
PatchCleaner.clearUpdatePath(updateInfo.workDir.getAbsolutePath())删除工作目录中的临时文件。
调用方通常需要异步执行(网络下载补丁 + 合并安装都较重),并在成功后提示用户"重启应用生效"。
dexPatch 模式入口
同一入口类还提供了 DexPatch 更新接口(AtlasUpdater.java):
public static void dexpatchUpdate(Context context, UpdateInfo updateInfo, File patchFile,
final IDexpatchMonitor coldMonitor, boolean enableHot,
IDexpatchMonitor hotMonitor) throws Exception
- 内部先校验当前应用
versionName必须等于updateInfo.baseVersion,否则拒绝执行; enableHot为 true 时,先通过UpdateBundleDivider拆分出PATCH_DEX_HOT类型的 Bundle,调用DexPatchUpdater.installHotPatch做热补丁(立即生效);- 随后用
filterNeedColdPatchList过滤出PATCH_DEX_COLD类型列表,调用DexPatchUpdater.installColdPatch完成冷补丁安装(同样需要重启后生效)。
IDexpatchMonitor 是提供给调用方的进度/结果回调接口,包含 merge(...) 与 install(...) 两个方法,分别上报合并与安装结果(含成功标志、Bundle 名、版本号与错误信息)。
更新基础信息:UpdateInfo 数据模型
UpdateInfo(UpdateInfo.java)实现了 Serializable,用于在调用方与更新流程之间传递"这次要更新什么、从哪个版本升到哪个版本"。README 给出的核心字段如下,源码中还有若干扩展字段一并说明:
| 字段 | 类型 | 说明 |
|---|---|---|
baseVersion |
String |
当前客户端版本(补丁基于的基线版本) |
updateVersion |
String |
更新后的客户端版本 |
updateBundles |
List<Item> |
本次更新涉及的 Bundle 模块信息列表 |
workDir |
File |
更新工作目录,默认 new File(RuntimeVariables.androidApplication.getCacheDir(), "atlas_update"),合并过程中的临时产物都放这里 |
dexPatch |
boolean |
是否走 DexPatch 模式(true 时 update() 直接返回,需走 dexpatchUpdate) |
lowDisk |
boolean |
低磁盘空间标志(默认 false),影响主 dex 的合并策略 |
workDir 的默认值直接使用宿主 Application 的缓存目录,意味着更新过程产生的中间文件不需要申请外部存储权限;PatchCleaner 会在流程结束后将其整体清除。
Item:单个 Bundle 的更新信息
UpdateInfo.Item 同样实现 Serializable,描述单个 Bundle 的更新元数据。README 给出了 4 个字段,源码中还有大量与 DexPatch 相关的扩展字段:
README 明示字段:
| 字段 | 类型 | 说明 |
|---|---|---|
isMainDex |
boolean |
是否是主 dex(com.taobao.maindex) |
name |
String |
Bundle 的名称(如 com.taobao.dynamic.test) |
version |
String |
Bundle 版本信息 |
srcVersion |
String |
Bundle 对应的 git tag 版本 |
dependency |
List<String> |
依赖的 Bundle 列表 |
源码扩展字段(UpdateInfo.java):
| 字段 | 类型 | 说明 |
|---|---|---|
unitTag |
String |
新 Bundle 的单元标签(安装后写入版本列表,实际替代了 version 的角色) |
srcUnitTag |
String |
源 Bundle 的单元标签,用于在本地定位"旧版本 Bundle"作为合并基线 |
inherit |
boolean |
新版本与该 Bundle 兼容、无需更新时置 true,安装阶段直接继承原版本 |
patchType |
int |
补丁类型:PATCH_DYNAMIC_(0)、PATCH_DEX_COLD(1)、PATCH_DEX_HOT(2)、PATCH_DEX_C_AND_H(3) |
dexpatchVersion |
long |
DexPatch 版本号(用于判断是否需要安装/回滚) |
reset |
boolean |
是否回滚到基线版本 |
resetHotPatch |
boolean |
是否回滚已安装的热补丁 |
Item.makeCopy(origin) 提供浅拷贝方法,DexPatch 流程中按类型拆分列表时用它复制条目,避免污染原始列表。
更新流程五步走(README 骨架 + 源码印证)
README.md 给出了官方定义的五步更新过程:
- 解压 patch 包(Unzip the patch package)
- 合并 patch 与原 apk 包中的 bundle(在独立进程进行)(Merger patch of the original apk package and bundle, in a separate process)
- 安装合并后的新 bundle(Install the combined new bundle)
- 更新 bundle 列表信息(Update the bundle list information)
- 等待用户重启后重新加载(Wait for the user starts to reload)
下面结合源码逐一展开每一环的实现细节。
第 1 步:解压/读取 patch 包
Patch 包是 zip 格式。模块内提供了通用解压工具 ZipUtils.java(unzip(zipFilename, outputDirectory)),按 1024 字节缓冲逐文件写出。而在实际合并流程 PatchMerger.merge() 中,采用的是更高效的方式——直接用 new ZipFile(patchFile) 打开,按需读取特定 Entry,避免全量解压到磁盘(PatchMerger.java)。
补丁包内 Bundle 归档的 Entry 命名规则为:lib<bundleName中的.替换为_>.so,例如 Bundle com.taobao.dynamic.test 对应 Entry libcom_taobao_dynamic_test.so。PatchMerger 正是用 String.format("%s%s", "lib", bundleName.replace(".", "_")) + ".so" 从补丁包里定位每个 Bundle 的新版本。
第 2 步:在独立进程合并 Bundle(PatchMerger)
合并逻辑集中在 PatchMerger.java。流程概览:
- 建立工作目录
workDir(默认cacheDir/atlas_update)与基线目录orignal_<baseVersion>; - 遍历
updateInfo.updateBundles,对每个非inherit的 Item:- 全量部署:若补丁包中存在该 Bundle 的
.soEntry,且该 Bundle 不支持合并(!supportMerge(bundleName)),则直接把补丁中的归档拷贝到工作目录,记为mergeOutputs的输出; - 差量部署:否则定位原 APK/本地已安装的旧 Bundle(
findOriginalBundleFile),连同补丁中的新内容组装成MergeObject(原 Bundle 路径、Bundle 名、目标输出路径)加入toMergeList; - 回滚:若
item.reset == true,直接把mergeOutputs中该 Bundle 的输出路径置为空串,表示回滚到基线版本;
- 全量部署:若补丁包中存在该 Bundle 的
- 若存在待合并项,创建
DexMergeClient(见 dexmerge 包),调用dexMerge(patchFile, toMergeList, true)在独立进程完成 dex 级合并,随后unPrepare()释放资源; - 合并失败(非 dexPatch 模式)抛
MergeException("merge failed!"); finally中关闭打开的 apkZip。
关于独立进程:DexMergeClient/DexMergeService(atlas-update/src/main/java/com/taobao/atlas/dexmerge/DexMergeClient.java、DexMergeService)实现了跨进程合并:主进程通过 Binder 把合并任务交给独立进程执行,避免在主线程/主进程进行大量 dex 运算造成卡顿。README 中"在独立进程进行"的表述正是对应这部分实现。
关于 supportMerge 与主 dex:源码中 supportMerge = Build.VERSION.SDK_INT < 21(PatchMerger.java),且只有 Bundle 名为 com.taobao.maindex(常量 MAIN_DEX)时才走合并路径;低磁盘(lowDisk)时也强制对主 dex 走合并。也就是说:主 dex 的更新在 Android 5.0(API 21)以下必须靠 dex 合并实现,而普通 Bundle 在支持全量替换的情况下直接拷贝新归档即可。
旧 Bundle 定位(findOriginalBundleFile)(PatchMerger.java)体现了 Atlas 的多版本基线管理策略:
com.taobao.maindex:dexPatch 模式下按BaselineInfoManager中的主 dex 版本从已安装 Bundle 中取,否则直接用applicationInfo.sourceDir(即当前 APK 本身)作为合并基线;- 普通 Bundle:优先取
Atlas.getInstance().getBundle(bundleName)当前运行时 Bundle 的归档文件(要求未被打过 dexpatch、且其unique_tag与srcUnitTag一致);否则从Framework.getInstalledBundle(bundleName, srcUnitTag)取指定版本的历史归档;都没有时回退到从 APK 的lib/<abi>/libxxx.so或 assets 中解出原始 Bundle(getOriginalBundleFromApk); - 找不到有效源 Bundle 时抛
IOException("can not find valid src bundle of ..."),由上层转为MergeException。
第 3 步:安装合并后的新 Bundle(PatchInstaller)
合并产出的 mergeOutputs(Map<String, Pair<String, Item>>:Bundle 名 → 输出文件路径 + Item)交给 PatchInstaller.java 安装:
- 空输出直接抛
BundleException("merge bundles is empty"); - 遍历
mergeOutputs,将 Bundle 名、文件路径、升级版本分别收集成数组;reset的 Bundle 用占位文件new File("reset")与版本号-1表示回滚; - 对
updateInfo.updateBundles中未出现在mergeOutputs的 Bundle 做兜底:inherit的以new File("inherit")占位并沿用其unitTag版本,否则抛BundleException; - 调用底层安装:
Framework.update(!updateInfo.dexPatch, bundleNameArray, bundleFilePathArray, updateVersionArray, dexPatchVersionArray, updateInfo.updateVersion, updateInfo.lowDisk)(PatchInstaller.java)。
这里的 Framework.update 是 Atlas 运行时框架(atlas-core)提供的 Bundle 安装接口,负责把新归档写入 Bundle 存储、登记版本并更新 Bundle 列表信息——对应 README 流程的第 4 步"更新 bundle 列表信息"。
第 4 步:更新 Bundle 列表信息
如上所述,Framework.update 在安装的同时完成 Bundle 版本列表(BaselineInfoManager)的更新;下一次启动时,Atlas 框架依据该列表加载新版本的 Bundle 与对应 classloader。
第 5 步:等待用户重启重新加载
更新完成后,AtlasUpdater.update 最后调用 PatchCleaner.clearUpdatePath 删除工作目录(递归删除文件与目录,见 PatchCleaner.java),随后由调用方引导用户重启。重启后 Atlas 运行时按新 Bundle 列表完成加载,动态更新正式生效。
DexPatch 模式:热补丁 + 冷补丁的拆分与安装
模块内除了 README 主讲的 Bundle 动态更新,还完整实现了 DexPatch 补丁体系,作为对主流程的补充与深化(相关文档可参考 atlas-docs/update/ 目录下的 dexpatch 说明与演示 atlas-demo/AtlasDemo/)。
补丁类型拆分:UpdateBundleDivider.java 的 dividePatchInfo(list, patchType) 按 patchType 把 Item 列表拆成冷补丁(PATCH_DEX_COLD)与热补丁(PATCH_DEX_HOT)两份;PATCH_DEX_C_AND_H(冷热皆可)的条目会同时进入两份列表。
热补丁安装:DexPatchUpdater.installHotPatch 从补丁包读取各 Bundle 的 hot.dex(主 dex 对应 Entry 名为 hot.dex,普通 Bundle 为 lib<bundle名>/hot.dex),交给 AtlasHotPatchManager.getInstance().installHotFixPatch(updateVersion, updateBundles) 完成热替换——这部分能力与 README 强调的"Bundle 更新需重启"形成对比,热补丁是立即生效的。
冷补丁安装:DexPatchUpdater.installColdPatch 复用 PatchMerger.merge() + PatchInstaller.install() 的同一套合并安装流水线,只是结果记录进 BaselineInfoManager 的 dexpatch 版本表,供下次启动判断是否需要继续安装。
过滤已安装补丁:filterNeedHotPatchList/filterNeedColdPatchList 通过对比 dexpatchVersion 与本地已安装版本,跳过已安装/已回滚的条目,实现幂等(DexPatchUpdater.java)。
调试通道:AwoPatchReceiver 与本地验证
为了方便在真机上进行动态更新调试,模块提供了 AwoPatchReceiver.java——一个依赖 Atlas 调试模式(Framework.isDeubgMode())的 BroadcastReceiver:
- 动作常量:
com.taobao.atlas.intent.PATCH_APP(打补丁)、com.taobao.atlas.intent.ROLLBACK_PATCH(回滚); - 监听目录:应用外部私有目录下的
atlas-debug文件夹; - 触发方式:通过 adb 向该目录推送
.so格式的补丁归档,然后发送广播(intent 需携带pkg且与应用包名一致),Receiver 会把补丁移动为debug_storage/<packageName>/patch.zip,随后 Toast 提示"DebugPatch安装中",最后杀掉进程等待重启; - 限制:仅
Framework.isDeubgMode()为 true(即 debug 构建)时生效,不会影响线上包。
这为"先本地产出 tpatch → 推送 → 广播 → 重启验证"的调试闭环提供了现成通路。
实战接入建议与注意事项
基于 README 与源码实现,接入 atlas-update 做 Bundle 动态更新时有几点值得注意:
- 先校验版本再更新:
updateInfo.baseVersion必须与客户端当前版本一致(dexpatchUpdate中直接硬校验 versionName),否则合并基线会错位; - 异步执行:合并过程涉及解压、dex 合并(独立进程)、文件安装,耗时较长,务必放到子线程执行,避免阻塞主线程;
- 生效时机:
update()走的是重启生效路径,安装成功后应提示用户重启;需要立即生效的类级修复应走dexpatchUpdate的 hot patch 分支; - 磁盘空间:合并会产生工作目录临时文件,
updateInfo.lowDisk在低磁盘场景下会调整主 dex 合并策略;流程结束后PatchCleaner会自动清理workDir; - 失败兜底:合并失败会抛
MergeException,安装失败抛BundleException,调用方应捕获并给出回滚或重试策略;Item.reset提供回滚到基线版本的通道; - 依赖一致性:
Item.dependency与srcUnitTag用于基线定位,服务端下发的补丁信息应与本地已安装 Bundle 的unique_tag对齐,否则会因找不到有效源 Bundle 而合并失败。
小结
atlas-update 以极小的 API 面(一个 update 静态方法 + 一个 UpdateInfo 数据模型)封装了"解压补丁 → 独立进程合并 dex → 安装新 Bundle → 更新版本列表 → 等待重启"的完整动态更新流水线,同时在源码层面通过 PatchMerger(全量/差量/回滚三态)、PatchInstaller(Framework.update 安装)、DexPatchUpdater(冷热补丁拆分)把增量发布的不同诉求统一收敛。掌握 AtlasUpdater.java 与 UpdateInfo.java 这两个核心文件,配合 PatchMerger.java 与 PatchInstaller.java 的实现细节,即可在自己的 Atlas 应用中安全地接入并理解 Bundle 动态更新机制。