Go net/http ServeContent 如何处理 Range 请求：部分响应、缓存头与文件偏移

给文件下载接口加上断点续传时，最容易踩的坑不是读取文件，而是把 Range、文件偏移和缓存条件混在一起。Go 的 net/http.ServeContent 已经把这条响应链路封装好了：只要传入可正常 Seek 的 io.ReadSeeker，它就能按请求头返回完整内容或部分内容，并处理常见的条件请求。

如果接口只是把一个文件可靠地提供给浏览器或下载器，优先让 ServeContent 负责 Range 与响应头；你的代码主要负责找到正确的文件、设置稳定的名称和修改时间。

先看清 ServeContent 解决了哪一段工作

手写下载接口时，开发者常从 io.Copy 开始，然后再补 Range 解析、文件长度、Content-Length、缓存头和异常响应。这样做并非不可能，但每补一个分支，就多一个偏移或状态码没有对齐的机会。

ServeContent(w, req, name, modtime, content) 把这些判断放在同一条响应路径里。官方文档明确说明，它处理 Range 以及 If-Match、If-Unmodified-Since、If-None-Match、If-Modified-Since 和 If-Range；当响应头没有预先设置时，还会根据 name 的扩展名推断 Content-Type。

这里的关键前提是 content 必须能 Seek。*os.File 天然满足 io.ReadSeeker，而只实现 io.Reader 的流不能直接套用这条接口。

一个最小文件处理器，先验证正常响应

下面的处理器只做三件事：打开文件、提供修改时间、交给 ServeContent。name 写成带扩展名的稳定值，便于类型推断；它不会改变磁盘路径。

func download(w http.ResponseWriter, r *http.Request) {
    f, err := os.Open("./assets/release.zip")
    if err != nil {
        http.NotFound(w, r)
        return
    }
    defer f.Close()

    info, err := f.Stat()
    if err != nil {
        http.Error(w, "cannot stat asset", http.StatusInternalServerError)
        return
    }

    http.ServeContent(w, r, "release.zip", info.ModTime(), f)
}

验证普通请求时，先看 200 OK、Content-Length 和 Content-Type。如果传入非零修改时间，响应还可能带有 Last-Modified。不要把这一步误解成“已经支持断点续传”，它只说明完整内容路径是通的。

Range 请求改变的是起点和响应状态

客户端发送 Range: bytes=1024-2047 时，ServeContent 会先得到内容大小，再判断区间是否与文件重叠。成功时响应状态变为 206 Partial Content，并通过 Content-Range 告诉客户端实际返回的范围和总长度，例如 bytes 1024-2047/8192。

这条路径的因果关系可以压缩成一句话：Range 决定读取区间，Content-Range 公开区间结果，底层 io.ReadSeeker 负责把读取位置移动到区间起点。没有 Range 时则沿着 Seek 之后的完整响应路径返回。只检查响应体长度而不检查这两个响应头，无法证明偏移正确。

req, _ := http.NewRequest(http.MethodGet, "/download", nil)
req.Header.Set("Range", "bytes=1024-2047")

rr := httptest.NewRecorder()
download(rr, req)

fmt.Println(rr.Code) // 206
fmt.Println(rr.Header().Get("Content-Range")) // bytes 1024-2047/8192

示例中的总长度只是测试文件的预期值，真实程序应以文件实际大小为准。多段 Range、非法区间和文件大小变化时，不能把这个字符串硬编码进生产逻辑。

缓存头与文件名参数，别按直觉理解

modtime 不是装饰参数。它让 ServeContent 可以结合 If-Modified-Since 判断客户端是否仍可使用缓存；若条件已经满足，响应可能直接结束而不发送完整正文。若业务自己设置了符合 RFC 7232 的 ETag，还能参与 If-Match、If-None-Match 和 If-Range 的判断。

相反，name 并不等于文件下载名。官方说明是：它主要用于扩展名推断媒体类型，名称本身不会被发送到响应中。需要 Content-Disposition 时，应明确设置，并对用户输入的文件名做安全编码。

三个常见失败点，按证据定位

传入不可 Seek 的内容

如果内容来自只读网络流或自定义 Reader，却没有稳定的 Seek，ServeContent 无法先确定大小，也无法跳到 Range 起点。此时应先落盘、使用内存中的可 Seek 缓冲，或换成真正支持随机定位的存储读取方式。

把 200 当成 Range 成功

客户端发出 Range 后，如果服务仍然返回完整内容，先检查中间层是否改写或删除了请求头，再看服务端是否真的调用了 ServeContent。成功的部分响应至少要同时核对状态码与 Content-Range。

文件在请求期间被替换

文件更新会让长度、修改时间和内容版本互相错位。生产环境可以使用临时文件写入完成后再原子替换，并让打开的文件描述符对应一个稳定版本；不要在同一个请求里先 Stat 一个文件、再无条件打开另一个路径。

用一组请求把边界跑完

最小验收不需要复杂压测，准备一个固定内容的测试文件，依次发送普通 GET、单段 Range、无重叠 Range 和带 If-Modified-Since 的请求，记录状态码、Content-Length、Content-Range 和响应体长度。普通 GET 证明基础路径，Range 证明偏移路径，条件请求证明缓存判断没有被忽略。

这里别急着把所有下载需求都交给一个函数：如果还需要鉴权、下载审计、限速或对象存储签名，应在调用 ServeContent 前完成这些业务检查，并保留响应头核验。

相关问题

ServeContent 是否只能服务本地文件？

不是。只要对象实现了可用的 io.ReadSeeker，它就能提供所需的定位和读取能力；本地 *os.File 只是最常见的实现。

Range 请求一定返回 206 吗？

不一定。区间无效、条件请求提前结束或服务端无法满足请求时，状态和响应体都会不同，应该以响应头和状态码联合判断。

为什么还要传 modtime？

它为 Last-Modified 和 If-Modified-Since 提供判断依据；如果版本时间不可靠，缓存验证也就失去了稳定参照。

把判断留在标准库，把验收留在响应头

这个问题的分界很清楚：文件定位、权限和业务审计属于应用代码；Range 区间、Seek 偏移、条件请求和基础媒体类型属于 ServeContent 的职责。上线前至少保留普通响应与部分响应两组测试，并把 206、Content-Range、实际体长作为一组证据检查。