Atlas Bundle 动态更新模块 atlas-update 详解:接口、数据模型与合并安装全流程

原创2026-09-25 23:40:421,911 阅读
文章标签:移动开发原生移动插件系统构建工具

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):

  1. Bundle 动态更新:允许只更新部分 Bundle(含主 dex),而无需用户重新安装整个 APK;
  2. 独立进程合并:补丁与原 APK 中 Bundle 的 dex 合并发生在独立进程中,避免合并大 dex 时阻塞主线程、拖垮 UI;
  3. 重启生效:更新安装完成后并不会像 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 中的真实执行序列如下:

  1. 入口校验:若 updateInfo == null || updateInfo.dexPatch,直接返回(dexPatch 场景需改走 dexpatchUpdate);
  2. 注册合并回调:构造 MergeCallback,用于逐 Bundle 上报合并结果(成功打 [dexmerge] merge bundle xxx success 日志,失败打 error);
  3. 合并:new PatchMerger(updateInfo, patchFile, mergeCallback).merge(),产出合并后的 Bundle 归档文件集合 mergeOutputs;
  4. 安装:new PatchInstaller(patchMerger.mergeOutputs, updateInfo).install(),调用底层 Framework 完成 Bundle 安装;
  5. 清理: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 给出了官方定义的五步更新过程:

  1. 解压 patch 包(Unzip the patch package)
  2. 合并 patch 与原 apk 包中的 bundle(在独立进程进行)(Merger patch of the original apk package and bundle, in a separate process)
  3. 安装合并后的新 bundle(Install the combined new bundle)
  4. 更新 bundle 列表信息(Update the bundle list information)
  5. 等待用户重启后重新加载(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。流程概览:

  1. 建立工作目录 workDir(默认 cacheDir/atlas_update)与基线目录 orignal_<baseVersion>;
  2. 遍历 updateInfo.updateBundles,对每个非 inherit 的 Item:
    • 全量部署:若补丁包中存在该 Bundle 的 .so Entry,且该 Bundle 不支持合并(!supportMerge(bundleName)),则直接把补丁中的归档拷贝到工作目录,记为 mergeOutputs 的输出;
    • 差量部署:否则定位原 APK/本地已安装的旧 Bundle(findOriginalBundleFile),连同补丁中的新内容组装成 MergeObject(原 Bundle 路径、Bundle 名、目标输出路径)加入 toMergeList;
    • 回滚:若 item.reset == true,直接把 mergeOutputs 中该 Bundle 的输出路径置为空串,表示回滚到基线版本;
  3. 若存在待合并项,创建 DexMergeClient(见 dexmerge 包),调用 dexMerge(patchFile, toMergeList, true) 在独立进程完成 dex 级合并,随后 unPrepare() 释放资源;
  4. 合并失败(非 dexPatch 模式)抛 MergeException("merge failed!");
  5. 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 安装:

  1. 空输出直接抛 BundleException("merge bundles is empty");
  2. 遍历 mergeOutputs,将 Bundle 名、文件路径、升级版本分别收集成数组;reset 的 Bundle 用占位文件 new File("reset") 与版本号 -1 表示回滚;
  3. 对 updateInfo.updateBundles 中未出现在 mergeOutputs 的 Bundle 做兜底:inherit 的以 new File("inherit") 占位并沿用其 unitTag 版本,否则抛 BundleException;
  4. 调用底层安装: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 动态更新时有几点值得注意:

  1. 先校验版本再更新:updateInfo.baseVersion 必须与客户端当前版本一致(dexpatchUpdate 中直接硬校验 versionName),否则合并基线会错位;
  2. 异步执行:合并过程涉及解压、dex 合并(独立进程)、文件安装,耗时较长,务必放到子线程执行,避免阻塞主线程;
  3. 生效时机:update() 走的是重启生效路径,安装成功后应提示用户重启;需要立即生效的类级修复应走 dexpatchUpdate 的 hot patch 分支;
  4. 磁盘空间:合并会产生工作目录临时文件,updateInfo.lowDisk 在低磁盘场景下会调整主 dex 合并策略;流程结束后 PatchCleaner 会自动清理 workDir;
  5. 失败兜底:合并失败会抛 MergeException,安装失败抛 BundleException,调用方应捕获并给出回滚或重试策略;Item.reset 提供回滚到基线版本的通道;
  6. 依赖一致性: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 动态更新机制。

登录后查看全文
atlas