夜雨聆风
一、提出问题：预下载本来是优化，为什么反而会拖慢体验
第一，下载并发不可控。礼物列表、宠物资源、通用资源、房间特效都可能在进入页面后批量触发下载。如果每个业务都直接启动下载，瞬时网络请求数会快速升高，设备侧文件 IO 也会被打满。
第二，后台预加载会抢占关键下载。礼物动画、宠物 ZIP、房间皮肤通常属于体验增强资源，慢一点下载可以接受；但聊天图片、用户主动打开的视频、当前页面首屏资源更敏感。如果所有下载同等优先级，后台预加载就可能拖慢用户正在等待的资源。
第三，同一个资源可能被重复下载。多个页面、组件、Manager 可能同时发现同一个资源不存在，然后同时发起下载。重复下载不仅浪费流量，也容易让同一个本地文件被多个任务同时删除、写入、重命名。
第四，下载失败与异常参数缺少统一入口。URL 为空、本地路径为空、下载失败、临时文件残留等问题散落在业务侧，很难形成统一治理。
所以，下载治理的核心不是把所有资源都下载得更快，而是让关键请求不要被后台预下载拖慢。把下载能力从“业务直接发起”升级为“公共入口入队、调度器统一分配执行”的模式，本质上是在客户端内部建立一个资源下载调度层。
二、先定义什么是关键请求
在做调度之前，要先给下载任务分层。否则所有下载都会被当成同一种任务处理。
在社交 App 里，下载任务大致可以分成三类：
| 类型 | 用户感知 | 示例 | 调度策略 |
|---|---|---|---|
| 关键请求 | 用户正在等待 | 聊天图片、语音附件、当前页面首屏资源 | 立即优先 |
| 半关键请求 | 当前页面稍后可能需要 | 二屏资源、即将展示的预览资源 | 正常排队 |
| 后台预下载 | 体验增强，慢一点可接受 | 礼物动画、宠物 ZIP、房间皮肤、通用资源包 | 降低优先级 |
这张表是整套方案的基础。
如果一个资源用户正在等，它就不应该和后台礼物动画抢队列。如果一个资源只是为了“以后可能用到”，它就不应该占满网络和文件 IO。
三. 总体方案：所有下载先进入调度器
本次改造的核心是新增 ResourceDownloadScheduler，并让 Http.downLoadFile 先进入调度器，再由调度器决定什么时候真正执行下载。
整体链路如下：
业务调用 Http.downLoadFile↓ 参数校验，非法参数直接 FAIL ↓ResourceDownloadScheduler.enqueue↓按 url + localPath 去重↓进入 HIGH / NORMAL / LOW 队列↓根据并发限制调度任务↓执行 Http.downLoadFileImmediately↓axios 下载到 .temp 文件↓rename 为最终文件，回调 COMPLETE / FAIL
这套设计保留了原有下载接口的调用方式，同时新增一个可选的 priority 参数。旧业务不需要立即改造，默认仍然按高优先级下载；预加载类、大文件类、非关键类资源可以逐步标记为低优先级。
从业务视角看，改造后的规则很简单：
用户正在等的资源：HIGH页面稍后可能用到的资源：NORMAL后台补缓存的大资源：LOW
调度器负责把这些任务放到不同队列里，再根据并发限制决定谁先执行。
四. 改造一：把直接下载收口到公共入口
Http.downLoadFile 的接口现在变为：
publicstaticdownLoadFile(url: string,localPath: string,callBack?: Function,params?: Record<string, Object>,priority: ResourceDownloadPriority=ResourceDownloadPriority.HIGH)
核心变化有三点。
第一，增加 priority 参数，默认值是 ResourceDownloadPriority.HIGH。这保证了旧调用方式仍然兼容：
Http.downLoadFile(url, path, callback)第二，增加了参数校验。URL 或本地路径为空时，不再继续进入 axios 和文件写入流程，而是直接记录日志并回调 FAIL：
if (StringUtils.isEmpty(url) ||StringUtils.isEmpty(localPath)) {callBack?.({totalBytes: 0,remainingBytes: 0,status: FileLoadStatus.FAIL })return}
第三，真正的下载逻辑被拆到 downLoadFileImmediately。downLoadFile 本身只负责校验和入队：
ResourceDownloadScheduler.enqueue(url,localPath,callBack,params,priority,Http.downLoadFileImmediately)
这样做之后，所有业务仍然走统一入口，但下载是否立即执行、是否合并、是否延后，就由调度器统一控制。
这个改造的关键是“收口”。只要业务继续绕过公共入口直接创建下载，就仍然会破坏全局调度。
因此，Http.downLoadFile 不再只是一个下载工具方法，而是全局下载治理的入口。
五. 改造二：用优先级队列保护关键请求
5.1 任务模型
调度器内部定义了一个下载任务对象：
class ResourceDownloadTask {key: string=''url: string=''localPath: string=''params?: Record<string, Object>priority: ResourceDownloadPriority=ResourceDownloadPriority.HIGHcallbacks: Function[] = []executor: ResourceDownloadExecutor= () => {}running: boolean=false}
这个模型里有几个关键字段：
| 字段 | 作用 |
|---|---|
key | 任务去重 key |
url | 下载地址 |
localPath | 文件最终保存路径 |
params | GET 查询参数 |
priority | 下载优先级 |
callbacks | 同一任务的多个回调 |
executor | 真正执行下载的函数 |
running | 当前任务是否正在执行 |
5.2 三档优先级
当前定义了三档下载优先级：
exportenumResourceDownloadPriority {HIGH=0,NORMAL=1,LOW=2}
数字越小优先级越高。调度器维护三条队列：
privatestatichighQueue: ResourceDownloadTask[] = []privatestaticnormalQueue: ResourceDownloadTask[] = []privatestaticlowQueue: ResourceDownloadTask[] = []
取任务时按以下顺序：
HIGH -> NORMAL -> LOW这意味着只要高优先级队列里有任务，低优先级预加载资源就不会抢先执行。
这正是“避免预下载拖慢关键请求”的核心：不是禁止预下载，而是让预下载排在正确的位置。
5.3 总并发限制
调度器限制全局同时运行的下载任务数：
private static readonly MAX_TOTAL_RUNNING = 2 调度入口是 schedule：
privatestaticschedule() {while(ResourceDownloadScheduler.runningCount<ResourceDownloadScheduler.MAX_TOTAL_RUNNING) {const task = ResourceDownloadScheduler.pollNextTask()if(!task) {return}ResourceDownloadScheduler.startTask(task)}}
只要当前运行任务数小于 2，就继续从队列中取任务执行。这个限制直接解决了旧模式下“业务调用多少次就启动多少个下载”的问题。
对客户端来说，并发不是越高越好。下载并发过高会同时抢占网络、文件 IO、解码和解压资源，尤其是 ZIP、MP4、VAP 这类大文件，很容易影响前台交互。
5.4 低优先级并发限制
除了总并发，调度器还限制低优先级任务的并发：
private static readonly MAX_LOW_RUNNING = 1低优先级队列只有在满足以下条件时才会出队：
if(ResourceDownloadScheduler.lowRunningCount<ResourceDownloadScheduler.MAX_LOW_RUNNING&& ResourceDownloadScheduler.lowQueue.length > 0) {return ResourceDownloadScheduler.lowQueue.shift()}
这意味着即使总下载并发允许 2 个，后台预加载类资源同一时间最多也只运行 1 个。礼物动画、宠物 ZIP、通用资源 ZIP、房间皮肤等资源不会一口气把下载通道占满。
这个限制非常重要。因为后台预下载通常不是一个任务，而是一批任务。如果不限制低优先级并发，即使总并发受控，也可能出现两个并发位都被后台资源占住的情况。
5.5 任务去重
调度器使用 url + localPath 构造任务 key：
privatestaticbuildKey(url : string, localPath: string): string{return`${url}taskMap：let task = ResourceDownloadScheduler.taskMap.get(key)if (task) {if(callBack) {task.callbacks.push(callBack)}ResourceDownloadScheduler.upgradePriorityIfNeed(task, priority)ResourceDownloadScheduler.schedule()return}
如果同一个资源已经在队列中或正在下载，后续调用不会再创建新的真实下载任务，而是把 callback 追加到已有任务上。
这能解决两类问题：
多个业务同时下载同一文件导致的重复网络请求。
同一目标文件被多个任务同时删除、写入、rename 的文件竞争问题。
5.6 多回调分发
同一个下载任务可能有多个调用方。调度器在收到下载进度、成功或失败时，会分发给所有 callback：
privatestaticdispatch (task: ResourceDownloadTask,result: FileLoadCallback) {const callbacks = task.callbacks.slice()for (let callBack of callbacks) {callBack(result)}}
这里使用 slice() 复制一份 callback 列表，可以避免分发过程中 callback 数组被外部修改带来的遍历问题。
5.7 优先级提升
如果一个任务已经在低优先级队列中等待，后续又被高优先级业务请求，调度器会尝试提升它的优先级：
private static upgradePriorityIfNeed(task: ResourceDownloadTask,priority: ResourceDownloadPriority) {if(task.running || priority >= task.priority) {return}ResourceDownloadScheduler.removeQueuedTask(task)task.priority = priorityResourceDownloadScheduler.pushTask(task)}
这个设计适合“资源先被后台预加载，随后被用户主动打开”的场景。
例如一个礼物动画原本在后台以 LOW 优先级预下载，用户突然点击要播放这个礼物。如果任务还没开始运行，就可以被提升到更高优先级，避免“明明已经在队列里，却还要等后台顺序”的问题。
六. 改造三：用临时文件避免读到半成品
调度器只负责排队，不直接处理文件。真正执行下载的是 Http.downLoadFileImmediately。
当前下载采用临时文件策略：
let tempLocalPath = localPath + ".temp"下载前会尝试删除旧的 .temp 文件和目标文件：if (fs.accessSync(tempLocalPath)){fs.unlinkSync(tempLocalPath)}if (fs.accessSync(localPath)) {fs.unlinkSync(localPath)}
axios 下载时写入临时文件：
axios({ url: url,method: 'get',context: AppUtils.getContext(),params: params,filePath: tempLocalPath,onDownloadProgress: ...})
下载成功后再重命名为最终文件：
await StorageUtil.rename(tempLocalPath, localPath)callBack?.({ status: FileLoadStatus.COMPLETE })下载失败时删除临时文件：
StorageUtil.deleteFile(tempLocalPath)callBack?.({ status: FileLoadStatus.FAIL })临时文件策略的好处是：业务侧只有在收到 COMPLETE 后才应该认为最终文件可用，避免直接读取未下载完成的半成品文件。
对大资源尤其重要。礼物、宠物、房间皮肤下载后经常还要解压、校验、解析配置，如果业务读到了半成品文件，后续失败位置会非常隐蔽。
七. 业务落地：哪些资源应该降为低优先级
这次分支已经把几类预加载资源显式标记为 LOW。这些资源有一个共同特点：它们能提升体验，但不应该阻塞用户当前操作。
| 业务 | 代码入口 | 下载内容 | 为什么适合低优先级 |
|---|---|---|---|
| 礼物动画 | GiftDownloadManager.ets | SVGA、MP4、VAP | 多为预下载，文件偏大，不应影响聊天附件 |
| 宠物资源 | PetResManager.ets | 宠物等级资源 ZIP | 更新频率低，下载后还要解压，可后台执行 |
| 通用资源 | ResCommonManager.ets | Lottie、美颜、陪伴房资源 ZIP | 启动或页面进入时补缓存，非即时强依赖 |
| 房间主题 | RoomThemeWebAPI.ets | 房间皮肤 ZIP | 体验增强资源，可以延后完成 |
| 传送动画 | DeliveryManager.ets | 房间传送动画文件 | 房间配置类资源，适合后台补齐 |
典型调用方式：
Http.downLoadFile(remoteUrl,filePath,(result: FileLoadCallback) =>{if(result.status==FileLoadStatus.COMPLETE) {// 下载完成后的业务处理} else if(result.status == FileLoadStatus.FAIL) {// 下载失败日志和降级}},undefined,ResourceDownloadPriority.LOW)
这种接入方式非常克制：业务只多传一个参数，就能进入统一的低优先级下载池。
这也是这次改造比较适合老项目的地方：不需要重写礼物、宠物、房间皮肤的下载流程，只要把它们接入同一个调度入口，就能先把并发和优先级管起来。
八. 三档优先级如何服务业务
建议后续统一定义三档优先级的使用边界。
| 优先级 | 适用场景 | 示例 |
|---|---|---|
HIGH | 用户正在等待、当前页面立即需要、主动触发的下载 | 聊天图片、聊天视频、语音附件、首屏必要资源 |
NORMAL | 当前页面稍后可能用到，但不是首屏强依赖 | 页面二屏资源、即将播放的资源、用户可能点击的预览 |
LOW | 后台预加载、缓存补齐、体验增强、大资源下载 | 礼物动画、宠物 ZIP、房间皮肤、通用资源包 |
当前项目里主要已经形成 HIGH 和 LOW 的区分，NORMAL 还可以继续补充使用。例如，当前页面内“用户马上可能看到”的资源可以放在 NORMAL，而全局静默补缓存继续放在 LOW。
一个比较实用的判断标准是：
用户已经触发并等待结果：HIGH用户停留在当前页面，有较大概率马上看到：NORMAL只是为了后续体验提前准备：LOW
优先级不是技术字段，而是业务体验的表达。
九. 改造收益：关键请求被保护起来
9.1 限制并发，降低资源争抢
全局同时最多 2 个下载任务，低优先级最多 1 个。这个限制可以减少：
瞬时网络请求过多。
CDN 请求尖峰。
本地文件 IO 竞争。
页面卡顿和资源加载抖动。
9.2 关键资源优先
默认下载是 HIGH，预加载资源显式标记为 LOW。因此，在礼物动画、宠物资源等后台下载过程中，聊天附件、用户主动打开的图片视频仍然可以优先进入下载执行链路。
9.3 同任务合并
同一个 url + localPath 的下载任务会合并，多个调用方共享一次真实下载。这可以减少重复流量，也能降低同一文件被多个下载任务同时操作的风险。
9.4 改造成本低
旧调用保持兼容，新能力通过最后一个可选参数启用。业务可以渐进式接入，不需要一次性修改所有下载场景。
9.5 参数异常更容易定位
URL 或路径为空会在公共入口直接失败，并输出日志。这比进入 axios 后才失败更容易排查。
十. 典型业务收益
10.1 礼物动画
礼物配置刷新或礼物面板打开时，可能触发批量动画预下载。降级为 LOW 后，礼物动画不会一次性并发下载，也不会明显影响聊天图片、视频等即时下载。
10.2 宠物资源
宠物资源 ZIP 通常较大，下载后还要解压、复制、读取配置。放入低优先级队列后，宠物资源更新可以后台慢慢完成，避免抢占关键下载。
10.3 通用资源包
通用资源包用于贵族 Lottie、美颜、陪伴房等场景。这类资源适合启动后或页面进入后补齐，放入低优先级队列可以降低对前台交互的影响。
10.4 房间皮肤和传送动画
房间皮肤和传送动画属于体验增强资源。低优先级下载可以让它们在不影响用户关键操作的情况下逐步补齐。
把项目里的资源下载从“业务各自直接开请求”，升级为“统一入队、按优先级调度、受控并发、同任务合并”的模式。
它最直接解决了四类问题：
资源预下载过多导致并发失控。
后台大资源抢占用户关键下载。
同一文件重复下载和文件写入竞争。
非法参数导致的失败位置不确定。
对于社交 App 来说，下载资源本身并不难，难的是在大量业务同时需要资源时，让关键资源优先、后台资源克制、重复任务合并、失败问题可定位。
所以这篇文章的重点不是“实现了一个下载工具”，而是“如何避免后台预下载拖慢关键请求”。ResourceDownloadScheduler 的价值就在这里：它把下载从一个工具方法，提升成了一个可以被全局治理的资源调度能力。
