用 HTTP Range 实现大文件断点续传接口
【摘要】 用 Express 实现大文件断点续传下载接口:解析单段 Range 返回 206 与 Content-Range,越界时返回 416 和 bytes */总长度,并用强 ETag 配合 If-Range 避免文件变更后分段拼接错乱,附 curl 验证步骤。
用 HTTP Range 做断点续传:206、416 与 If-Range
问题场景
大文件下载中断后,如果每次从 0 开始,既浪费带宽,也无法保证分段拼接正确。HTTP Range 允许客户端只请求文件的一段,服务端用 206 Partial Content 和 Content-Range 告知实际范围;请求越界时返回 416 Range Not Satisfiable,并在 Content-Range 中使用 bytes */总长度。当文件可能变化时,客户端会带 If-Range(通常是强 ETag);服务端若发现 ETag 不匹配,应忽略 Range 返回完整 200,避免旧分段和新文件拼在一起。
Express 最小实现
依赖 express,示例文件为同目录 big.bin:
const express = require('express');
const fs = require('fs');
const path = require('path');
const { pipeline } = require('stream');
const app = express();
const FILE = path.join(__dirname, 'big.bin');
const QUOTE = String.fromCharCode(34);
function makeEtag(st) {
return QUOTE + st.size.toString(16) + '-' + Math.floor(st.mtimeMs).toString(16) + QUOTE;
}
function parseRange(header, size) {
const m = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim());
if (!m) return { kind: 'unsupported' };
const a = m[1];
const b = m[2];
if (a === '' && b === '') return { kind: 'unsupported' };
if (size === 0) return { kind: 'unsat' };
let start;
let end;
if (a === '') {
const suffix = Number(b);
if (!Number.isSafeInteger(suffix) || suffix <= 0) return { kind: 'unsat' };
start = Math.max(size - suffix, 0);
end = size - 1;
} else {
start = Number(a);
end = b === '' ? size - 1 : Number(b);
if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)) {
return { kind: 'unsupported' };
}
if (start > end) return { kind: 'unsat' };
}
if (start >= size) return { kind: 'unsat' };
if (end >= size) end = size - 1;
return { kind: 'ok', start, end };
}
function sendFull(req, res, size) {
res.set('Content-Length', String(size));
if (req.method === 'HEAD' || size === 0) return res.end();
return pipeline(fs.createReadStream(FILE), res, (err) => {
if (err) res.destroy(err);
});
}
app.get('/download', async (req, res) => {
let st;
try {
st = await fs.promises.stat(FILE);
} catch {
return res.status(404).end();
}
const etag = makeEtag(st);
res.set('Accept-Ranges', 'bytes');
res.set('ETag', etag);
res.set('Content-Type', 'application/octet-stream');
const range = req.headers.range;
const ifRange = req.headers['if-range'];
if (range && ifRange && ifRange !== etag) {
return sendFull(req, res, st.size);
}
if (!range) {
return sendFull(req, res, st.size);
}
const part = parseRange(range, st.size);
if (part.kind === 'unsupported') {
return sendFull(req, res, st.size);
}
if (part.kind === 'unsat') {
res.status(416);
res.set('Content-Range', `bytes */${st.size}`);
return res.end();
}
const { start, end } = part;
res.status(206);
res.set('Content-Range', `bytes ${start}-${end}/${st.size}`);
res.set('Content-Length', String(end - start + 1));
if (req.method === 'HEAD') return res.end();
return pipeline(fs.createReadStream(FILE, { start, end }), res, (err) => {
if (err) res.destroy(err);
});
});
app.listen(3000, () => {
console.log('GET http://127.0.0.1:3000/download');
});
运行:
node -e "require('fs').writeFileSync('big.bin', Buffer.alloc(1024 * 1024))"
npm i express
node app.js
服务监听 http://127.0.0.1:3000/download。parseRange 只接受单段 bytes=start-end、bytes=start-、bytes=-suffix;多段或语法不支持时回退完整 200,越界才 416。sendFull 同时处理 HEAD 和 0 字节文件。
curl 分段验证
另开终端,先取前 512 KiB,再取剩余部分并拼接:
curl -sS -D - -o p1 -H 'Range: bytes=0-524287' http://127.0.0.1:3000/download
# 期望 206,Content-Range: bytes 0-524287/1048576,Content-Length: 524288
curl -sS -D - -o p2 -H 'Range: bytes=524288-' http://127.0.0.1:3000/download
cat p1 p2 > joined.bin
cmp big.bin joined.bin && echo OK
越界请求应返回 416:
curl -sS -D - -o /dev/null -H 'Range: bytes=2000000-' http://127.0.0.1:3000/download
# 期望 416,Content-Range: bytes */1048576
验证 If-Range:先从正常响应头复制 ETag(包含双引号),替换下面的占位值:
curl -sS -D - -o p3 -H 'Range: bytes=0-1023' -H 'If-Range: "100000-18f..."' http://127.0.0.1:3000/download
# 匹配时 206
curl -sS -D - -o full.bin -H 'Range: bytes=0-1023' -H 'If-Range: "stale"' http://127.0.0.1:3000/download
wc -c full.bin # 期望 1048576,状态 200
边界与限制
- 只实现单段 Range。多段请求按不支持处理并回退 200;如需
multipart/byteranges要另行实现。 If-Range只做强 ETag 精确比较;日期形式按不匹配处理,回退完整 200,安全但可能多传。ETag 由文件大小和 mtime 生成,若内容变化但 mtime 未变会误判,生产可改用内容哈希或版本号。- 416 的
Content-Range必须是bytes */总长度;206 的Content-Range必须与Content-Length、实际读取的start/end一致。 - 文件需支持随机读。对象存储场景应把 Range 转发给后端,不要先完整下载到本地;同时注意反向代理超时和客户端重试。
- 并发写入同一文件可能读到不一致内容,建议固定文件句柄或使用版本化对象。
【版权声明】本文为华为云社区用户原创内容,未经允许不得转载,如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱:
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
评论(0)