Atlas 动态组件框架 Bundle 开发实战：工程配置、代码规范与主动启动全指南

移动开发原生移动插件系统【免费下载链接】atlasA powerful Android Dynamic Component Framework.项目地址https://gitcode.com/gh_mirrors/atlas/atlas点击查看免费下载本文以 Atlas Android 动态组件框架中的 BundleAWB为绝对主线完整讲解一个 Bundle 从工程声明、资源段分配、主客接入到运行时初始化、跨 Bundle 服务提供与主动启动的完整链路。读完本文你将掌握在 atlas-demo 这类宿主工程中正确创建和接入 AWB Bundle 的全部配置写法理解源码中BundleConfig.awbBundle、PreparePackageIdsTask等关键实现背后的原理并能规避官方文档列举的六大常见坑位。一、Bundle 是什么在 Atlas 框架中Bundle 是一个可以被动态部署的小型 APK它拥有自己的AndroidManifest.xml、代码、资源乃至 Application 声明但运行时并不由系统直接识别而是由 Atlas 容器统一管理、按需安装与启动。Bundle 的工程形态称为 AWBAndroid Web Bundle 的约定叫法仓库中大量以AwbBundle命名构建产物通常以xxxawb的坐标形式被主客工程依赖。从构建源码看插件层为每个 AWB 生成独立的资源、dex、manifest 处理链例如 BuildAtlasEnvTask.java 中逐个执行fillAwbManifest、fillAwbJar、fillAwbAndroidRes、fillAwbSolibs等填充动作最终由 PackageAwbsTask.java 把每个 Bundle 的 dex、压缩资源、JNI 目录、Java 资源等打包成独立产物。二、Bundle 的工程配置2.1 在 Bundle 自身工程中声明 AWBBundle 的build.gradle必须显式声明其为 AWB 模块核心配置只有一行atlas { bundleConfig { awbBundle true } }这一配置对应插件源码中的 BundleConfig.java其中private Boolean awbBundle false;默认为false只有置为true后该模块才会被插件纳入 AWB 构建管线资源、dex、manifest 按 Bundle 维度处理。仓库中的真实示例见 atlas-demo/AtlasDemo/firstbundle/build.gradleapply plugin: com.android.library apply plugin: com.taobao.atlas atlas { bundleConfig { awbBundle true } buildTypes { debug { baseApFile project.rootProject.file(app/build/outputs/apk/app-debug.ap) } } } group com.atlas.demo version 1.0.2注意该示例同时给出了baseApFile的配置——Bundle 在 debug 构建时依赖主工程的基线 APapp-debug.ap这是 Bundle 资源/符号链接主工程所必需的。2.2 推荐使用com.taobao.atlas.library插件原文档建议当 Bundle 需要更好地支持 AAR 传递依赖等问题时可以采用原生com.android.library之上的增强插件com.taobao.atlas.libraryapply plugin: com.taobao.atlas.library buildscript { repositories { mavenLocal() jcenter() } dependencies { classpath com.android.tools.build:gradle:2.1 classpath com.taobao.android:atlasplugin:1.0.0 // 使用 com.taobao.atlas.library 时需要配置 atlasplugin 等 classpath } }使用该插件时必须同时在buildscript.dependencies中引入com.taobao.android:atlasplugin文中示例版本为1.0.0仓库中的基于版本打包的 demo则使用了2.3.1.beta55见 app/build.gradle否则插件类无法被 Gradle 加载。需要说明的是不采用该插件、直接使用com.android.librarycom.taobao.atlas如 firstbundle 示例也是仓库 demo 验证过可行的写法差别主要在于对 AAR 传递依赖、库级资源合并等场景的处理能力上。2.3 主客工程的外部接入配置Bundle 要被主客工程使用需要两步外部配置第一步声明资源段packageId在主客工程的packageId.properties中为每个 Bundle 声明独立的资源 ID 段格式为com.taobao.android:firstbundle34 // groupId:artifactIdNUM其中groupId:artifactId必须与 Bundle 的 Maven 坐标一致NUM为该 Bundle 独占的资源段起始值。之所以必须划分资源段是因为 Atlas 将各 Bundle 的资源合并进主 APK 的资源体系若两个 Bundle 使用相同的资源 ID 段就会发生资源覆盖冲突。如果你不想手工维护也可以通过tBuildConfig.autoPackageId让插件自动分配。相关实现见 PreparePackageIdsTask.java插件会依次读取apContext.getPackageIdFile()即主工程的packageId.properties、tBuildConfig.getPackageIdFile()以及各 Bundle 的customPackageID.txt合并进autoConfigMap当isAutoPackageId为true且存在未分配项时从minPackageId开始自动递增分配并校验重复。默认值在 TBuildConfig.javaautoPackageId默认为trueminPackageId默认为35即自动分配从 35 号段开始。分配结果最终输出到build/outputs/packageIdFile.properties供后续构建环节使用。第二步添加 AWB 依赖在主客工程的build.gradle中以awb后缀引入 Bundle 依赖compile(com.taobao.android:firstbundle:1.0.0awb)awb是 Atlas 插件扩展出的特殊坐标分类插件据此把该依赖识别为动态 Bundle 而非普通 AAR。仓库 demo 的完整依赖结构见 structor.md其awbs段展示了多个 Bundle 的awb依赖写法例如{ awbs: { AtlasDemo:remotebundle:unspecifiedawb: [], AtlasDemo:publicbundle:unspecifiedawb: [], AtlasDemo:firstbundle:unspecifiedawb: [], AtlasDemo:secondbundle:unspecifiedawb: [ AtlasDemo:secondbundlelibrary:unspecifiedaar ] } }在 基于版本打包的demo/app/build.gradle 中可以看到与文档完全一致的实战写法compile(com.taobao.android:firstbundle:${version}awb)。三、Bundle 开发的注意点官方六大坑位原文档明确提示遵循以下代码规范可以有效避免在运行时遇到难以排查的问题。Manifest 中禁止引用 Bundle 内资源Bundle 的AndroidManifest.xml不能出现对 Bundle 自身资源的引用例如 Activity 的Theme必须声明在主 APK 中。因为 Bundle 的 Manifest 会合并进主 Manifest一旦存在 Bundle 内资源引用会直接引发构建出错。替代方案是 Manifest 中不写Theme改在 Activity 的onCreate中调用setTheme()。转场动画资源放主 APKActivity 通过overridePendingTransition使用的切换动画文件必须放在主 APK 中避免 Bundle 动态部署后动画资源缺失。包名与资源前缀规范化Bundle 内的 Class 最好以特定packageName开头resource 文件带有特定前缀。这样既能避免资源或类名重复引起的覆盖问题也能在出现问题时快速定位到出问题的模块。自定义 style 的 parent 必须位于主 APK如果 Bundle 内使用自定义style且其parent也是自定义 style那么 parent 的定义必须放在主 APK 中。这是 Android 5.0 之后系统 style 查找固有逻辑导致的容器内暂不能完全兼容。so 使用限制Bundle 内部如果有 so安装时 so 无法解压到 APK 的 lib 目录对于直接通过 native 层dlopen使用 so 的场景会存在限制且会影响后续 so 的动态部署因此 Bundle 内 so 不建议用dlopen方式使用。ContentProvider 的 multiprocess 声明若 Bundle 使用了主进程的 ContentProvider其 Manifest 中最好带上android:multiprocesstrue android:process:XX这样可避免主进程一启动就触发startBundle导致启动时间过长。四、初始化 BundleApplication 的两个关键差异Bundle 可以被认为是一个小型 APK因此每个 Bundle 的初始化都从 Bundle 的 Application 开始Application 声明在 Bundle 的AndroidManifest.xml中。启动方式与普通 App 类似先执行attachBaseContext再执行onCreate。但原文档特别强调两个不同点初始化线程取决于 start Bundle 的线程Bundle 可能运行在主线程也可能运行在子线程。因此初始化代码若对线程敏感需要特别注意如果需要强制主线程执行可通过new Handler(Looper.getMainLooper()).post(...)去初始化。Bundle 的 Application 并非系统真正认可的 Application需要以 Application 作为参数进行初始化的方法可以传入getBaseContext()。Bundle Application 的mBase实际就是主 APK 真正的 Application最好不要直接传入 Bundle 的 Application 本身进行初始化否则存在潜在风险。从容器源码可以印证这一点主工程的 Application 被保存在RuntimeVariables.androidApplication见 Atlas.java 的init方法容器框架本身也是围绕主 APK 的 Application 启动的。此外Atlas.java 中的checkingThread还做了线程校验debug 模式下若在 UI 线程执行 bundle 安装会抛出RuntimeException(can not install bundle in ui thread)这也呼应了初始化线程取决于调用线程的约束——Bundle 的安装与初始化都应放到非主线程执行。五、Bundle 如何提供服务给其他 Bundle原文档指出Bundle 虽然提供了依赖的方式但这种依赖方式如果使用不当反而会带来隐患且与 Bundle 本身的封装性相违背。正确的使用姿势是分场景决策如果某个中间件本身以 Bundle 形式存在那么声明依赖是可行的如果两个相对独立的业务 Bundle 之间存在某几个功能接口的依赖则应通过服务方式解耦服务提供方提供 AIDL 接口被使用方或者主 APK 依赖该接口同时服务提供方在自身 Bundle 内部实现 Service 的功能。这种接口 Service的模式保证了业务 Bundle 之间的松耦合避免直接依赖对方的类实现也让接口变更可以通过 AIDL 版本管理来约束。仓库 demo 中的 Bundle 同样遵循只通过 Component 的方式被依赖安装的约定见 structor.md 的提示。六、主动启动 Bundle默认情况下Bundle 只对外暴露 Android 原生的 Component运行期按需加载即所谓被动启动。但某些特殊 Bundle如监控性质的 Bundle本身与其他代码完全独立又需要在某个时间点主动运行这时可以通过如下方式主动启动。假设 Bundle 的 PackageName 为com.sample.bundleAAtlas.getInstance().installBundleTransitivelyAsync( new String[]{com.sample.bundleA}, new BundleInstaller.InstallListener() { Override public void onFinished() { BundleImpl impl (BundleImpl) Atlas.getInstance().getBundle(com.sample.bundleA); if (impl ! null) { try { impl.start(); } catch (BundleException e) { e.printStackTrace(); } } } });关键步骤拆解installBundleTransitivelyAsync异步安装目标 Bundle含其传递依赖安装完成后回调onFinishedAtlas.getInstance().getBundle(com.sample.bundleA)按包名取出已安装的 Bundle 实例。Atlas是框架的全局入口Atlas.java 中getInstance()返回单例INSTANCE真正的 Bundle 查找逻辑在 Framework.java 的getBundle(String location)内部从bundles表中按 location即包名取出对应 Bundleimpl.start()手动拉起 Bundle触发其 Application 初始化流程即上文第四节的attachBaseContext→onCreate可能抛出BundleException需要捕获。另外如果 Bundle 需要在 App 启动时就自动运行仓库的插件还提供了autoStartBundles配置见 TBuildConfig.java示例写法为atlas { tBuildConfig { autoStartBundles [com.taobao.firstbundle] // 自启动 bundle 配置 } }完整示例见 基于版本打包的demo/app/build.gradle。七、参考 Demo 与进一步阅读完整的 Bundle 接入 Demoatlas-demo/AtlasDemo含firstbundle、secondbundle、publicbundle、remotebundle等典型 Bundle 工程以及依赖结构说明 structor.md基于版本打包的完整工程基于版本打包的demo其 app/build.gradle 同时展示了awb依赖、autoStartBundles与 patch 配置的组合用法容器框架源码Bundle 安装、查询与启动的核心位于 Framework.java 与 Atlas.java插件构建源码AWB 资源/依赖/packageId 处理可分别查看 PreparePackageIdsTask.java、BuildAtlasEnvTask.java 与 BundleConfig.java。最后提醒一句接入前请先通读 guide-for-use 目录下的其他接入文档并对照 atlas-demo 的实际工程配置进行验证因为插件版本atlasplugin与构建工具版本com.android.tools.build:gradle需要相互匹配不同版本间 DSL 细节可能存在差异。赞分享移动开发原生移动插件系统【免费下载链接】atlasA powerful Android Dynamic Component Framework.项目地址https://gitcode.com/gh_mirrors/atlas/atlas点击查看免费下载相关推荐GraphiQL 如何从 UMD 构建迁移到 ESM-based CDN 用法GraphiQL 如何从 UMD 构建迁移到 ESM based CDN 用法 如果你是通过 CDN 的 script 标签在单页 HTML 里加载 Gra移动开发原生移动插件系统Vitest globalSetup 配置完全指南全局环境准备、数据注入与重跑钩子Vitest globalSetup 配置完全指南全局环境准备、数据注入与重跑钩子 导读 globalSetup 是 Vitest 中用于在测试运行开始前执行移动开发原生移动插件系统CANN/asc-devkit位图排序函数asc_bitsort 产品支持情况 |产品|是否支持| | : | : : | | term Atlas A3 训练系列产品/Atlas A3 推理系列产品人工智能深度学习算子库CANNAscend上一篇3步解锁专业工具开源激活方案完整指南下一篇Agent Governance Toolkit 原生预算强制执行从 SpendGuard 组合 Demo 到 ACS Manifests 与 budgets.rego创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考