Golang实现断点续传HTTP客户端

本文深入解析了如何在 Go 语言中手动实现一个健壮的、支持断点续传的 HTTP 客户端，涵盖从服务端能力探测（HEAD 检查 Accept-Ranges）、Range 请求头的正确构造与发送，到本地文件的安全定位写入（Seek + Truncate 防脏数据）、中断恢复逻辑（识别 416 错误、ETag/Content-Length 校验、指数退避重试）等核心细节，直击 http.Client 不自动支持断点续传的痛点，提供生产可用的工程化实践方案。

如何用 http.Client 发起带 Range 头的请求

断点续传的核心是复用已下载的文件片段，跳过已获取的字节范围。HTTP 协议通过 Range 请求头实现，例如 Range: bytes=1024- 表示从第 1024 字节开始下载剩余内容。Go 的 http.Client 本身不自动处理断点逻辑，但完全支持手动设置该头。

关键点在于：服务端必须返回 206 Partial Content 状态码，并在响应头中包含 Content-Range 和 Accept-Ranges: bytes —— 否则说明服务端不支持断点续传，强行加 Range 可能返回 416 Range Not Satisfiable 或直接忽略。

• 务必先 HEAD 请求检查 Accept-Ranges 响应头，再决定是否启用断点逻辑
• Range 值格式必须严格为 bytes=start-（末尾带短横），不能写成 bytes=start-end（除非你明确知道总长度且想下指定段）
• 使用 req.Header.Set("Range", "bytes="+strconv.FormatInt(offset, 10)+"-") 构造，避免字符串拼接错误

如何安全地追加写入已有文件并校验偏移量

本地文件已存在时，不能直接 os.O_CREATE | os.O_WRONLY 覆盖，而要用 os.O_APPEND 或更稳妥的 os.O_WRONLY | os.O_CREATE + file.Seek() 定位。但注意：os.O_APPEND 会强制写入末尾，无法覆盖中间空洞；断点续传需精确写入指定 offset，因此必须用 Seek。

容易踩的坑是：文件大小 ≠ 当前应续传的 offset —— 比如上次写入中途崩溃，文件末尾可能残留脏数据。所以每次开始前应以 os.Stat() 获取当前长度作为初始 offset，并在写入前用 file.Truncate(offset) 清除多余尾部（可选，视容错策略而定）。

• 打开文件用 os.OpenFile(path, os.O_WRONLY|os.O_CREATE, 0644)，不要用 os.Create()
• 写入前调用 file.Seek(offset, io.SeekStart)，确保写入位置准确
• 写入后建议调用 file.Sync() 防止内核缓存未刷盘导致下次读取 offset 错误

如何处理 416 Range Not Satisfiable 和连接中断重试

遇到 416 通常意味着服务端已变更资源（ETag / Last-Modified 不一致）、或文件已被删除/替换。此时不应盲目重试原 range，而应重新 HEAD 获取最新 Content-Length 和 ETag，比对本地文件 size 是否匹配。若不匹配，说明必须重新下载全量。

网络中断（如 net/http: request canceled、i/o timeout）则需捕获 err 并检查 resp != nil：若已有部分响应体且状态码是 206，可从 resp.Header.Get("Content-Range") 解析实际写入范围；否则回退到当前文件长度继续。

• 重试次数建议限制在 3–5 次，避免无限循环
• 每次重试前 sleep 指数退避（如 time.Second * time.Duration(1）
• 不要依赖 http.DefaultClient 的默认超时，显式设置 Timeout 和 Transport.IdleConnTimeout

完整流程中容易被忽略的细节

最常被跳过的不是代码逻辑，而是服务端兼容性验证和本地状态一致性维护。比如某些 CDN 或 Nginx 配置默认关闭 Accept-Ranges，或对大文件返回 200 却忽略 Range 头；又比如用户手动修改了本地文件大小却没清空内容，导致后续写入错位。

一个轻量但有效的做法是：在文件同目录下保存一个 .resume.json 元数据文件，记录 url、etag、last_modified、downloaded_size、total_size（如果已知）。每次开始前比对 etag 和本地文件 size，不一致就清空重下 —— 这比单纯依赖文件长度健壮得多。

另外，io.CopyN 比 io.Copy 更适合断点场景，它能精确控制最多复制多少字节，配合 Content-Length 做校验更直观。

到这里，我们也就讲完了《Golang实现断点续传HTTP客户端》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！