ArkTS 网络层实战:@ohos.net.http 封装与文件断点续传【鸿蒙心迹】

摘要
本文围绕 HarmonyOS 的 @ohos.net.http 模块,给出一套可直接落地的网络层封装方案。全文从「网络代码散落各处、大文件下载易 OOM、弱网体验差」三个真实痛点出发,先梳理 HttpRequest 生命周期、超时控制、Range 断点续传、流式进度与重试等核心规格,再依次给出统一 request 拦截器、断点续传下载、递增退避重试三段可复用代码,并用流程图与时序图说明调用链路,最后总结四个高频踩坑点与适用边界。读完你可以做到:业务层只调一个方法完成请求与下载,大文件永不从头开始,弱网也能从断点丝滑续上。
关键词:HarmonyOS;ArkTS;@ohos.net.http;断点续传;Range;流式下载;重试退避
目录
一、背景与痛点
网络请求是每个鸿蒙 App 的"毛细血管",但很多项目里网络代码是散着写的:A 页面直接 http.createHttp().request,B 页面自己拼 header,C 页面手写超时。等到要统一加 token、统一处理 401、统一打错误日志时,才发现要改十几个地方,漏一个就埋一个雷。
更痛的是文件下载。用户在下几百兆的安装包或离线视频时,网络一抖就从头再来,体验极差。我当初第一版下载就是"一次性拉 ArrayBuffer 再落盘",结果大文件直接 OOM,弱网下进度条永远卡在 0%。后来才搞明白:要用 HTTP Range 头做断点续传,用流式接收做实时进度,而不是傻等全部到位。
本文基于 @ohos.net.http 给出一个生产可用的网络层封装:统一 request 拦截器、文件断点续传下载、进度回调、超时与错误重试。目标只有一个——让你以后写网络只调一个方法,大文件下载永不从头开始,弱网也能丝滑续上。
二、核心概念与规格
| 维度 | 说明 |
|---|---|
| 请求入口 | http.createHttp() 返回 HttpRequest,用完必须 destroy() |
| 超时控制 | options.connectTimeout / readTimeout,单位 ms,不设置则走系统默认,弱网易假死 |
| 断点续传 | 请求头加 Range: bytes=start-,服务器返回 206 表示支持 |
| 流式进度 | 监听 on('dataReceive') 逐块写文件,别用 expectDataType: ARRAY_BUFFER 一次性拉全量 |
| 落盘 | fs.open 用 READ_WRITE/CREATE,先 seek 到 start 再 write |
| 重试 | 需自行实现,http 模块不内置重试,出错要手动重发并记录已下字节 |
记住:下载大文件的核心是"分块拿、定位写、断点续",而不是"等全了再存"。只要本地落盘字节数还在,网络断了就从上次的位置接着要。
下面这张图把一次断点续传下载的完整链路串起来,先建立整体印象,再看后面的代码:
三、核心代码
1. 统一 request 封装(拦截器式)
这一层的设计目标是把「鉴权、序列化、错误归一化」三件事从业务代码里彻底剥离。http.createHttp() 每次返回一个独立的 HttpRequest 实例,它内部持有一条底层连接句柄,因此必须成对调用 destroy(),否则句柄泄漏会在长时间运行后表现为 FD 耗尽。下面的实现用 try/finally 保证任何分支都能释放,并把 401 这类全局状态码收敛到拦截器里统一处理,业务侧只关心 data 与业务错误码。
import http from '@ohos.net.http';
interface ApiResp<T> { code: number; data: T; msg: string; }
// 统一请求:自动带 token、统一解析、统一错误处理
export async function request<T>(
url: string,
method: http.RequestMethod,
data?: Object
): Promise<T> {
const req = http.createHttp();
try {
const resp = await req.request(url, {
method,
connectTimeout: 10000,
readTimeout: 30000,
header: { 'Content-Type': 'application/json', 'X-Token': getToken() },
extraData: data ? JSON.stringify(data) : undefined
});
// 拦截器:401 统一跳登录
if (resp.responseCode === 401) { gotoLogin(); throw new Error('登录失效'); }
const body = JSON.parse(resp.result as string) as ApiResp<T>;
if (body.code !== 0) throw new Error(body.msg);
return body.data;
} finally {
req.destroy(); // 必须释放连接
}
}
2. 断点续传下载(Range + 流式进度)
断点续传的本质是让「本地已落盘字节数」成为续传的唯一真相源。实现上有三个关键点:其一,用 fs.statSync 读取已有文件大小作为 start,文件不存在时降级为 0;其二,通过 fs.seek 把文件指针定位到 start,保证新数据追加而非覆盖;其三,请求头携带 Range: bytes=start-,服务端若支持则返回 206 Partial Content 并只传输剩余部分。进度计算上,content-length 在 206 响应里表示的是本次剩余长度,所以总大小要加上 start 才是完整文件体积,这一点极易算错。
import http from '@ohos.net.http';
import fs from '@ohos.file.fs';
export async function downloadWithResume(
url: string, savePath: string,
onProgress: (received: number, total: number) => void
): Promise<void> {
// 1. 看本地已有多少,作为续传起点
let start = 0;
try { start = fs.statSync(savePath).size; } catch { start = 0; }
const req = http.createHttp();
const file = fs.openSync(savePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
fs.seek(file.fd, start, fs.WhenceType.BEGIN); // 定位到断点
let received = start;
let total = 0;
req.on('headersReceive', (headers: Object) => {
const len = (headers as Record<string, string>)['content-length'];
total = len ? Number(len) + start : 0;
});
req.on('dataReceive', (chunk: ArrayBuffer) => {
fs.writeSync(file.fd, chunk);
received += chunk.byteLength;
onProgress(received, total);
});
try {
await req.request(url, {
method: http.RequestMethod.GET,
header: { 'Range': `bytes=${start}-` }, // 关键:断点续传
connectTimeout: 10000,
readTimeout: 60000
});
} finally {
fs.closeSync(file);
req.destroy();
}
}
3. 超时重试骨架(递增退避)
@ohos.net.http 本身不提供重试能力,网络抖动、DNS 超时、服务端 5xx 都需要业务层自行兜底。下面的骨架采用线性递增退避(1s、2s、3s…),实现简单、易于观察;生产环境建议改为指数退避(1s、2s、4s…)并叠加随机抖动(jitter),避免大量客户端在同一时刻集中重试造成「重试风暴」。同时要注意:重试的入参 fn 应当是无副作用的幂等操作,下载场景下每次重试都会重新读取本地字节数,天然满足从断点继续的语义。
export async function requestWithRetry<T>(
fn: () => Promise<T>, maxRetry = 3
): Promise<T> {
let lastErr: Error | null = null;
for (let i = 0; i < maxRetry; i++) {
try { return await fn(); }
catch (e) {
lastErr = e as Error;
await new Promise(r => setTimeout(r, 1000 * (i + 1))); // 退避
}
}
throw lastErr;
}
// 用法:requestWithRetry(() => downloadWithResume(url, path, cb))
4. 组合调用:一个方法搞定请求与下载
把上面三块拼起来,业务层只需要调一个入口,鉴权、重试、进度、续传全部内聚:
import http from '@ohos.net.http';
import { request } from './httpClient';
import { downloadWithResume } from './downloader';
import { requestWithRetry } from './retry';
// 场景一:普通接口请求,自动带 token + 401 拦截 + 递增退避重试
export async function fetchUserInfo(userId: string) {
return requestWithRetry(() =>
request<UserInfo>(`https://api.example.com/user/${userId}`, http.RequestMethod.GET)
);
}
// 场景二:大文件下载,断点续传 + 实时进度
export async function downloadPackage(url: string, savePath: string) {
return requestWithRetry(() =>
downloadWithResume(url, savePath, (received, total) => {
const percent = total > 0 ? ((received / total) * 100).toFixed(1) : '--';
console.info(`下载进度:${percent}% (${received}/${total} bytes)`);
})
);
}
调用时序如下,重试层始终包在外层,保证任何一次失败都能从断点继续:
从时序图可以看出,重试层与下载层是正交的:requestWithRetry 只负责「失败后何时再试」,downloadWithResume 只负责「每次从哪个字节开始」。二者组合后,任意一次重试都会重新执行 fs.statSync,自动拿到最新的本地进度,因此无需在重试层额外维护断点状态,职责边界清晰,也便于单独测试。
四、实战要点
要点 1:createHttp 后忘了 destroy。
我当初每个请求都不 destroy,跑一天 FD 耗尽、新请求全失败。正确做法:用 try/finally 包住,任何路径(成功/异常)都 req.destroy(),把连接还回去。
要点 2:大文件用 ARRAY_BUFFER 一次性拉。
第一版下载我把整个文件读进内存再写盘,100MB 直接 OOM 崩溃。正确做法:用 on('dataReceive') 流式边收边写,配合 Range 还能断点续,内存占用恒定为一块缓冲区。
要点 3:续传前没核对服务器是否支持 206。
有次我加 Range 头,服务器却回 200 从头给,导致文件前半段重复、文件损坏。正确做法:先用 on('headersReceive') 读 Accept-Ranges / Content-Range,确认支持 206 再 seek 续写,否则清空重下。
要点 4:重试不带退避会雪崩。
弱网时我当初立刻重试,把服务器打挂、自己也卡死。正确做法:退避重试(骨架用 1s、2s、3s 线性递增,生产建议指数退避 1s、2s、4s 并加随机抖动),且重试要复用已下载字节,从断点续而非从头,别让流量白费。
五、小结与边界
这套网络层适合绝大多数"接口请求 + 文件下载"场景:统一拦截器管好鉴权与错误,Range 续传管好大文件体验。它的边界是——超大量并发上传/下载建议改用 @ohos.request 的任务队列(带系统级调度与暂停),@ohos.net.http 更适合自定义协议与精细控制。落地口诀:请求统一封装、用完必 destroy、大文件走流式、续传先验 206、重试带退避。
本文为原创首发实战笔记,基于 HarmonyOS 数据存储与网络能力,代码示例为可复用骨架,实际接口以华为官方文档为准。
更多推荐


所有评论(0)