在Android开发里“多线程下载”算不上新鲜话题但真要把下载功能沉淀成一个能复用的工具类很多细节不实操一遍根本发现不了。我在项目里就踩过不少坑线程开了没关、进度条刷新卡到怀疑人生、任务一多就鸳鸯锅一样乱后来干脆花时间整理了一套支持进度回调与任务管理的下载工具类才把这块从“能用”变成“好用”。这篇内容适合正在做文件下载、APK更新、资源包预加载的Android开发者参考尤其是想自己封装下载模块而不想每次都复制粘贴一坨网络操作代码的朋友。我会把设计思路、线程模型、核心代码、常见坑一次讲清楚。1. 下载工具类到底要解决什么问题1.1 单线程下载的痛点和多线程的边界很多新手写下载就是开一个线程URL.openConnection()读流写文件完了再弹个Toast。这在小文件、低频场景下没问题但一旦涉及大文件、多任务并发、用户反复点击下载问题立刻暴露下载过程占用主线程界面直接卡死甚至ANR。没有统一的进度回调想更新进度条就得靠Handler或者轮询文件大小又慢又别扭。任务之间互相干扰没有独立状态取消一个任务可能把整个下载流程都带崩。没有重试和错误处理断网一次下载直接失败用户只能手动重来。“多线程”的意义并不是单纯让下载速度翻倍而是把下载任务从UI线程剥离放进线程池统一调度同时让多个下载任务能够并行执行互不阻塞。这就像餐厅里不能只有一个厨师得有一个后厨团队有人切菜、有人炒菜、有人装盘但你得有个排菜板任务队列和传菜窗口回调接口。1.2 工具类需要具备的能力清单我设计这套工具类时先给自己列了一个能力清单每一项都对应一个实际使用场景能力使用场景异步执行下载不阻塞UI线程下载过程中用户可以继续操作多任务并发同时下载多个文件比如Apk、配置文件、图片资源进度回调实时获取下载百分比驱动进度条和剩余大小显示任务状态管理区分等待、下载中、暂停、完成、失败支持取消取消和重试用户取消下载或者失败后重新加入队列生命周期安全Activity销毁时避免线程泄漏和回调异常后面所有代码和设计都是围绕这张清单展开的。2. 整体设计与线程模型详解2.1 核心设计思路任务抽象 线程池调度 回调解耦工具类一共分三层层次清楚以后维护起来非常舒服第一层是任务层定义一个DownloadTask类它封装了下载URL、保存路径、当前进度、状态以及这一次下载的核心逻辑。一个任务对应一个文件是一个最小的执行单元。第二层是调度层也就是DownloadManager负责维护任务队列、控制并发数量、提供取消和重试接口。它内部使用线程池来执行任务而不是每个任务new Thread()。第三层是回调层定义监听接口把进度信息、状态变化从工作线程抛给调用方。调用方在UI层实现接口更新进度条、弹提示。这三层各干各的活好处很明显UI层不关心你怎么下载任务层不关心你被谁调度回调层只负责传递信息。将来想换网络库、加断点续传、改成协程都只需要改局部实现。2.2 为什么用线程池而不是手动new Thread这是老生常谈但很多人栽跟头。手动new Thread在并发任务多的时候会频繁创建和销毁线程开销大而且线程数量失控容易耗尽内存。线程池能复用线程、控制最大并发数还能用队列兜住突发任务。我使用的线程池配置是这样的private ExecutorService executorService new ThreadPoolExecutor( 2, // 核心线程数 4, // 最大线程数 30L, TimeUnit.SECONDS, // 非核心线程空闲回收时间 new LinkedBlockingQueue(64), // 任务队列容量 ThreadFactoryBuilder.create() .setNameFormat(download-pool-%d) .build(), new ThreadPoolExecutor.AbortPolicy() );核心线程数我设为2最大4这个数值在大多数手机上足够。下载是IO密集型操作阻塞在网络上时CPU是空闲的所以线程数不必设得太大。核心线程2保证基础吞吐最大4允许短时的并发峰值。队列容量64超过会触发拒绝策略。这里我用AbortPolicy是为了让异常尽早暴露而不是默默丢掉任务。提示生产环境建议把拒绝策略改成CallerRunsPolicy或者自定义策略这样任务满了以后会让提交任务的线程自己执行而不是直接把任务扔掉。2.3 任务状态的显式管理状态不明是很多下载模块混乱的根源。我给DownloadTask定义了一组状态常量用一个volatile int保存保证线程间可见public static final int STATE_IDLE 0; // 初始态 public static final int STATE_DOWNLOADING 1; // 下载中 public static final int STATE_PAUSED 2; // 已暂停本实现先预留 public static final int STATE_COMPLETED 3; // 完成 public static final int STATE_FAILED 4; // 失败 public static final int STATE_CANCELED 5; // 已取消这个状态由任务自己维护Manager在操作任务前先检查状态避免重复提交、取消不存在任务等问题。比如用户点击下载按钮Manager先看任务是不是已经在队列里是的话直接忽略否则才提交。2.4 进度回调频率与线程切换问题进度回调这里有个经典问题到底多久回调一次如果每次都回调下载几千个数据块就会触发几千次回调哪怕回调里只是更新一下内存变量频率过高也会拖累性能。我采用两个维度控制频率数据块维度每读取一定字节比如512KB才回调一次。时间维度加上一个最小回调间隔比如100毫秒。简单说就是“数据量和时间间隔满足其一就回调”。这样进度条既不会卡顿也不会过于频繁。代码如下if (downloadedBytes - lastCallbackBytes 512 * 1024 || System.currentTimeMillis() - lastCallbackTime 100) { listener.onProgress(percent, downloadedBytes, totalBytes); lastCallbackBytes downloadedBytes; lastCallbackTime System.currentTimeMillis(); }回调接口设计也要克制。我定义了一个DownloadListener把进度、完成、失败、取消四件事分开而不是一把梭用一个大接口public interface DownloadListener { void onProgress(int percent, long downloaded, long total); void onSuccess(String filePath); void onFailed(String url, String errorMsg); void onCanceled(String url); }注意这个回调默认运行在下载线程更新UI时必须切换到主线程。我通常在Manager里封装一个postOnMainThread()方法让回调调用者省点心。3. 核心代码实现与实操要点3.1 定义下载任务实体DownloadTaskDownloadTask是本工具类的核心因为所有下载细节都被它兜住了。我把它设计成一个Runnable这样可以直接丢给线程池执行。它内部保存了public class DownloadTask implements Runnable { private final String url; private final String filePath; private final DownloadListener listener; private volatile int state; private final long totalBytes; private volatile long downloadedBytes; private final InputStream inputStream; private final RandomAccessFile outputFile; // 省略构造与getter/setter Override public void run() { if (state STATE_CANCELED) { listener.onCanceled(url); return; } state STATE_DOWNLOADING; try { // 核心下载逻辑详见下一节 } catch (IOException e) { state STATE_FAILED; listener.onFailed(url, e.getMessage()); } } }字段里特意加了volatile来保证状态和进度在不同线程里的可见性。totalBytes用long而不是int因为一个文件可能超过2GBint会溢出。3.2 单任务下载流程从建立连接到进度计算这是下载的核心环节。我习惯用HttpURLConnection做基础实现因为它不需要引入额外依赖而且足够稳定。如果项目里已经有OkHttp改成它的Call也很简单。private void executeDownload() throws IOException { HttpURLConnection connection (HttpURLConnection) new URL(url).openConnection(); connection.setConnectTimeout(15000); connection.setReadTimeout(15000); connection.setRequestMethod(GET); connection.setRequestProperty(Accept-Encoding, identity); // 禁用gzip方便计算进度 connection.connect(); int responseCode connection.getResponseCode(); if (responseCode ! HttpURLConnection.HTTP_OK) { throw new IOException(Server returned responseCode); } long contentLength connection.getContentLengthLong(); // 总大小 long lastCallbackBytes 0; long lastCallbackTime 0; try (InputStream input connection.getInputStream(); RandomAccessFile output new RandomAccessFile(filePath, rw)) { output.setLength(contentLength); // 预创建文件大小 byte[] buffer new byte[8192]; int bytesRead; while ((bytesRead input.read(buffer)) ! -1) { output.write(buffer, 0, bytesRead); downloadedBytes bytesRead; // 回调频率控制 if (downloadedBytes - lastCallbackBytes 512 * 1024 || System.currentTimeMillis() - lastCallbackTime 100) { int percent (int) (downloadedBytes * 100 / contentLength); listener.onProgress(percent, downloadedBytes, contentLength); lastCallbackBytes downloadedBytes; lastCallbackTime System.currentTimeMillis(); } // 支持外部取消 if (state STATE_CANCELED) { listener.onCanceled(url); return; } } state STATE_COMPLETED; listener.onSuccess(filePath); } }有几个细节要特别说明setRequestProperty(Accept-Encoding, identity)如果不设置服务器可能会返回gzip压缩后的流那样contentLength是压缩前的大小跟你实际读取的字节数对不上进度会超过100%。如果你确实希望支持压缩就得用Content-Encoding头去解码很麻烦。对于下载文件直接禁用省心。缓冲区大小8192是经过实践折中的值太小会频繁IO太大占内存8KB起步性能敏感时可以调到32KB。每次循环检查取消状态这样用户点取消后下载线程可以在几百毫秒内退出而不是傻等读完整个文件。RandomAccessFile的setLength可以预分配文件空间避免流式写入过程中文件碎片也方便后续做断点续传。3.3 打破单任务限制的DownloadManager任务管理器Manager需要维护一个ConcurrentHashMap来保存任务状态同时对外提供提交、取消、查询接口。我写了一个简洁版本public class DownloadManager { private final ExecutorService executorService; private final MapString, DownloadTask taskMap new ConcurrentHashMap(); private DownloadManager() { executorService new ThreadPoolExecutor( 2, 4, 30L, TimeUnit.SECONDS, new LinkedBlockingQueue(64), new ThreadFactoryBuilder().setNameFormat(download-%d).build(), new ThreadPoolExecutor.AbortPolicy() ); } public static DownloadManager getInstance() { return Holder.INSTANCE; } private static class Holder { private static final DownloadManager INSTANCE new DownloadManager(); } // 提交下载任务 public void submit(String url, String filePath, DownloadListener listener) { if (taskMap.containsKey(url)) { // 避免重复提交 return; } DownloadTask task new DownloadTask(url, filePath, listener); taskMap.put(url, task); executorService.execute(task); } // 取消下载 public void cancel(String url) { DownloadTask task taskMap.get(url); if (task ! null) { task.cancel(); // 内部将state置为STATE_CANCELED } } // 查询任务是否还在下载 public boolean isDownloading(String url) { DownloadTask task taskMap.get(url); return task ! null task.getState() DownloadTask.STATE_DOWNLOADING; } // 注意任务结束时需要从map中移除 public void removeTask(String url) { taskMap.remove(url); } }这里用单例模式是为了全局共享线程池和任务表避免每个页面自己new一个Manager导致线程资源到处铺。ConcurrentHashMap保证多线程访问安全。任务移除的时机很关键。我在封装DownloadTask时会让它在完成、失败、取消的回调里自动调用Manager.removeTask(url)否则map会越积越多最终造成内存泄漏。3.4 将进度事件安全地抛回UI线程下载线程不能直接更新UI。我在Manager里加了一个主线程分发方法利用Handler实现private final Handler mainHandler new Handler(Looper.getMainLooper()); private void postOnMainThread(Runnable runnable) { mainHandler.post(runnable); }然后在回调接口里统一走这个入口。比如提交任务时把监听器包装成“回调前切线程”的形式DownloadListener wrapperListener new DownloadListener() { Override public void onProgress(int percent, long downloaded, long total) { postOnMainThread(() - listener.onProgress(percent, downloaded, total)); } // 其他方法类似 };这样就保证了外部使用方永远在UI线程收到回调可以直接操作进度条不用自己再写runOnUiThread。但要注意如果你在后台任务里也需要监听进度比如把进度上报到服务器这种强制主线程的设计就不合适了。所以我在实际项目中会加一个callbackOnMainThread开关默认true。这里为了输出清晰先展示默认方案。接入进度条时就很简单了DownloadManager.getInstance().submit( downloadUrl, savePath, new DownloadListener() { Override public void onProgress(int percent, long downloaded, long total) { progressBar.setProgress(percent); tvPercent.setText(percent %); } Override public void onSuccess(String filePath) { toast(下载完成 filePath); } Override public void onFailed(String url, String errorMsg) { toast(下载失败 errorMsg); } Override public void onCanceled(String url) { toast(已取消); } } );3.5 关于断点续传和分段下载的扩展思考标题里写的“多线程下载”有些朋友可能第一反应是“把一个文件拆成几段同时下载”也就是分段下载。这个方案确实能提高单文件下载速度但它有几个硬前提服务器必须支持Range头。需要维护每一段的起始位置和已下载长度。合并文件时如果是文本文件要注意边界二进制文件相对容易。断点续传需要记录每个段的进度这已经超出“下载工具类”的核心诉求。我目前的方案是“多线程多任务并行下载”而不是“单文件多段下载”因为90%的场景下用户需要的是同时下载多个文件而不是把一个文件拆碎。如果你的场景确实需要分段加速可以在DownloadTask里做二次改造把url和filePath一变让一个任务内部再维护多个子任务每个子任务通过Range: bytesstart-end发起请求最后合并文件。我建议先把单任务下载做稳定再加分段。不要一上来就追求炫技否则排查问题时你会非常痛苦。4. 常见问题与排查技巧实录4.1 进度回调很卡甚至出现ANR这个坑我踩过。最初我在每次read()之后都回调一次结果主线程被刷屏进度条本身的setProgress()都是轻量操作但如果你在回调里做文件大小转换、数据库写入就会非常卡。解决办法就是我前面说的两个频率控制条件。另外onProgress回调方法里不要做耗时操作UI层只更新进度条即可。如果要做耗时操作请另起线程。4.2 任务结束后线程池泄漏或者进程不退出线程池中的非核心线程设置了空闲回收时间所以理论上不会长期霸占资源。但有一个典型错误单例Manager持有Activity或Context的引用导致Activity无法销毁。我的方法是DownloadListener接口内部尽量不直接持有Activity而是用WeakReference包装或者在回调中先判断Activity.isDestroyed()再更新UI。如果你不需要全局单例也可以在每个页面创建Manager实例页面销毁时调用shutdownNow()但这样又失去了多页面共用下载的能力。我个人的习惯是单例 弱引用回调这是开发者必须养成的意识。4.3 下载文件不完整但进度显示100%这种情况多半是重定向问题或者流被压缩了。HttpURLConnection默认会跟随重定向但有些服务器的重定向会丢内容长度还有前面提到的gzip问题如果你允许压缩但又按照Content-Length计算百分比就会造成提前显示100%。排查思路先检查ContentLength返回的是不是-1如果服务器不返回长度进度计算就无从谈起只能退化为“忙碌刷新”模式。再检查连续下载两个文件对比字节数是否一致。如果文件用于校验比如APK下载完成后建议计算MD5与服务器端对比而不是只信回调。4.4 重复点击下载按钮出现了多个下载任务没有任务表的情况下用户点十次就会创建十个线程疯狂写同一个文件最后文件损坏。我使用taskMap.containsKey(url)来防重入同时提交前检查状态if (taskMap.containsKey(url)) { return; }如果你的业务里允许重新下载同一个URL比如用户强制刷新可以先调用cancel(url)再removeTask(url)然后重新submit。4.5 下载页面退出了回调还在更新UI这是一个生命周期问题。比如用户进入下载页开始下载立刻退出页面。如果回调是强引用Activity就会造成内存泄漏如果Activity已经被销毁你还在setProgress轻则崩溃警告重则ANR。我的处理方案是在UI层封装一个工具方法private void safeUpdateProgress(ProgressBar bar, String tag, int progress) { if (bar ! null bar.isShown()) { bar.setProgress(progress); } }更严格的做法是在页面onDestroy时移除监听但这个需要Manager额外提供unregisterListener方法。如果你只是做一个内部小工具最省心的方式就是弱引用或者使用Lifecycle组件。4.6 常见问题速查表问题可能原因解决建议进度条不走服务器没有返回ContentLength改为不定长进度条或先获取文件大小进度超过100%启用了gzip压缩设置Accept-Encoding: identity点击下载没反应任务已被重复提交检查taskMap是否释放了旧任务退出页面崩溃回调更新已销毁的UI使用WeakReference或生命周期感知并发高了卡顿线程数设太多下载线程数控制在2-4取消无效下载方法没有检查取消状态在循环体中添加取消判断文件损坏多个任务写同一文件用URL作为任务key防重入5. 几个值得记录的经验细节最后说几个细节这些是文档上一般不写的。第一关于下载目录。不要直接写Environment.getExternalStorageDirectory()Android分区存储以后很多路径已经访问不了。我建议优先使用应用专属目录比如context.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)这个目录不需要额外权限卸载应用时也会自动清理。如果你要下载到公共Download目录还得适配Android 10以上的分区存储处理MediaStore的写入又是一堆兼容工作能绕就绕。第二关于命名。线程池一定要命名。我用的是Guava的ThreadFactoryBuilder你也可以写一个简单的ThreadFactory自己命名。有了线程名出现ANR看日志时你能一眼认出是哪个线程卡住了是download-pool-1还是主线程省下大量排查时间。第三关于回调接口的粒度。不要把所有事件都塞到一个onFinish里用onSuccess/onFailed/onCanceled分开调用方写起来清楚以后加逻辑也方便。接口宁可小而多不要大而全。第四关于重试。最简单的做法是给DownloadTask加一个retryCount字段在onFailed回调里判断是否小于最大重试次数然后重新提交。注意重试前要removeTask掉旧记录否则会被防重入拦截。就拿我自己的项目来说封装这套工具类后最直观的变化是下载模块的代码量缩了一半新增下载任务只需要调一行submit页面销毁也不怕崩溃新接手的小伙伴看个半小时就能上手改。如果你最近也在写类似功能照着这个思路自己撸一版踩过的坑基本就那几个提前避开会很舒服。