Go net/http ServeContent 如何处理断点续传：Range 响应与缓存校验

文件下载接口一开始看起来只是把 os.Open 交给 http.ServeContent，真正上线后却常遇到两个问题：拖动进度条没有从中间继续，浏览器刷新也没有命中缓存。关键不在手写一套 Range 解析器，而是把文件名、修改时间和请求头交给 ServeContent，并用响应状态验证它的判断结果。

单文件下载优先让 http.ServeContent 处理 Range 与缓存条件请求；业务代码只负责打开文件、提供稳定的修改时间，并检查 206、304 和 200 三种结果。

先把下载任务缩小成一个可验收的接口

假设服务要提供 /download/report.zip。这一篇不把目录遍历、登录鉴权和对象存储混进来，只做一个固定文件的下载入口。这样每一个请求头都能和一个可见的响应状态对应起来：首次访问是 200 OK，拖动下载是 206 Partial Content，缓存未变化时是 304 Not Modified。

下面的处理函数保留了一个重要细节：modTime 来自文件的实际修改时间，而不是每次请求都调用 time.Now()。时间不稳定，缓存校验自然失去意义。

func downloadReport(w http.ResponseWriter, r *http.Request) {
    f, err := os.Open("./data/report.zip")
    if err != nil {
        http.Error(w, "file unavailable", http.StatusNotFound)
        return
    }
    defer f.Close()

    info, err := f.Stat()
    if err != nil {
        http.Error(w, "file unavailable", http.StatusNotFound)
        return
    }

    http.ServeContent(w, r, info.Name(), info.ModTime(), f)
}

ServeContent 先判断请求头，再决定读取哪一段

调用链可以按三个问题理解。ServeContent 先读取请求中的 Range，判断客户端是否只要文件的一段；随后结合 If-Modified-Since 与传入的修改时间做缓存校验；最后才把文件内容写入响应。业务处理函数不应在外面再复制一份这些判断，否则两套规则很容易在边界条件上分叉。

对一个从字节 1048576 开始继续的请求，成功的关键证据不是“浏览器能播放”，而是响应同时包含 206 Partial Content 和 Content-Range。如果服务仍返回 200 OK，通常说明请求头没有到达处理函数，或者中间层改写了请求。

用 curl 先确认 206，而不是先看下载文件大小

curl -i -H "Range: bytes=1048576-" http://127.0.0.1:8080/download/report.zip

检查响应头中的 206 Partial Content 和 Content-Range。这里的 1048576 只是验收用的请求起点，不是接口必须写死的分片大小。客户端可以提交其他合法范围，具体边界由 ServeContent 根据文件长度判断。

缓存校验要看 304，不要把它误判成下载失败

第一次响应中的 Last-Modified 是下一次缓存请求的依据。把它原样带回 If-Modified-Since，并保持文件未变化，服务就有机会返回 304 Not Modified。304 没有响应体，这正是“无需重新传输文件”的成功状态。

last_modified=$(curl -sI http://127.0.0.1:8080/download/report.zip | awk -F': ' '/^Last-Modified:/ {print $2}' | tr -d '\r')
curl -i -H "If-Modified-Since: ${last_modified}" http://127.0.0.1:8080/download/report.zip

如果第二次请求仍然是 200 OK，先看 Last-Modified 是否每次变化，再看代理是否删除了 If-Modified-Since。不要为了“强制缓存”手写一个永远返回 304 的分支，那会把已经更新的文件也藏起来。

几个容易把断点续传弄坏的改法

先读完整文件再写 ResponseWriter

这种写法把文件读取和 HTTP 范围协商拆开了，既浪费内存，也让 Range 失去作用。单文件场景下直接把可定位的文件句柄交给 http.ServeContent，边界更清楚。

用当前时间替代文件修改时间

每次请求都传入 time.Now()，客户端看到的 Last-Modified 会不断变化，If-Modified-Since 很难命中。修改时间应该跟文件版本绑定；文件被替换时，再让它变化。

只检查响应体是否为空

304 本来就没有响应体，空 body 不能单独说明请求失败。验收时应同时看状态码、Content-Range、Last-Modified 和是否真的发送了文件内容。

把验收写成三条可重复的检查

1. 不带特殊请求头访问，确认响应为 200 OK，并能读取完整文件。
2. 带 Range: bytes=1048576- 访问，确认响应为 206 Partial Content，且存在 Content-Range。
3. 把首次响应的 Last-Modified 带入 If-Modified-Since，文件未变化时确认响应为 304 Not Modified。

相关问题

ServeContent 能不能直接服务对象存储文件？

它需要一个可定位读取的文件对象；对象存储通常要先由网关处理签名、范围和转发，不能把这段本地文件示例直接当成云端下载方案。

为什么 Range 请求返回 416？

通常是请求范围已经超过文件长度，或者代理改写了范围。先用完整请求确认文件长度，再检查客户端发送的字节区间。

为什么浏览器没有发 If-Modified-Since？

缓存策略由客户端和中间层共同决定。先确认首次响应确实有 Last-Modified，再用 curl 手动复现，区分客户端策略和服务端逻辑。

这个接口的核心不是增加更多下载分支，而是让 ServeContent 看见真实文件、真实修改时间和原始请求头。用 200、206、304 三个状态做回归，断点续传和缓存校验就有了可以重复执行的验收标准。