Go net/http ServeContent 处理 Range 请求与缓存标头

如果 Go 静态文件接口既要支持断点续传，又要让浏览器利用缓存，直接手写 Range 解析很容易漏掉条件请求和文件偏移。http.ServeContent 已经把这些协议细节收进标准库：调用方只需准备资源名、修改时间和实现了 io.ReadSeeker 的内容对象。本文围绕这三个输入，给出一套可落地的处理方式。

核心做法是让 ServeContent 负责 HTTP 协议判断，让打开文件的代码负责路径边界和资源生命周期；成功的完整读取通常返回 200，合法分段返回 206，命中修改时间条件则可能返回 304，非法范围则返回 416。

准备 ServeContent 的文件与修改时间

ServeContent 的第四个参数是资源的修改时间，第五个参数必须能读取并定位。文件打开后要在同一个处理函数内关闭，避免高并发下载把文件描述符耗尽。

func fileHandler(root string) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 只允许把 URL 路径映射到明确的根目录，避免把用户输入直接当作系统路径。
        name := filepath.Clean(r.URL.Path)
        name = strings.TrimPrefix(name, string(filepath.Separator))
        full := filepath.Join(root, name)

        f, err := os.Open(full)
        if err != nil {
            http.NotFound(w, r)
            return
        }
        defer f.Close() // 处理完整响应、Range 响应后都要释放文件描述符。

        info, err := f.Stat()
        if err != nil || info.IsDir() {
            http.NotFound(w, r)
            return
        }
        // name 只用于响应中的资源名；ServeContent 读取 f 并使用 info.ModTime。
        http.ServeContent(w, r, filepath.Base(name), info.ModTime(), f)
    })
}

这里的关键不是把路径清洗得多复杂，而是先确定服务根目录，再对最终路径做边界检查。若业务允许符号链接，还要额外决定是否允许它指向根目录之外，不能把 ServeContent 当成路径授权组件。

处理 Range 与条件请求

ServeContent 会读取请求中的 Range、If-Modified-Since 等协商信息，并通过 Seek 定位到需要传输的位置。资源对象如果不支持 Seek，Range 场景就不适合直接交给它，应该改用明确的分块存储或临时文件。

func serveBytes(w http.ResponseWriter, r *http.Request, data []byte, modtime time.Time) {
    // bytes.Reader 同时实现 io.Reader、io.Seeker，适合小型静态资源示例。
    reader := bytes.NewReader(data)
    http.ServeContent(w, r, "payload.bin", modtime, reader)
}

客户端不带 Range 时，成功读取完整内容通常是 200；带合法 Range 时，响应会带 Content-Range 并返回 206。若客户端携带的条件时间表示资源没有变化，服务端可能直接返回 304，此时不要再自行写入正文。请求范围完全落在文件之外时，验收应关注 416 及其 Content-Range 边界。

补充缓存标头与文件安全边界

ServeContent 处理的是 HTTP 文件传输语义，不会替业务决定缓存时长、鉴权和下载文件名。公共只读资源可以在调用前设置 Cache-Control；私有资源则应在鉴权成功后再进入 ServeContent。

func cachedFile(w http.ResponseWriter, r *http.Request, f *os.File, modtime time.Time) {
    // 缓存策略属于业务层；私有文件不要照搬 public。
    w.Header().Set("Cache-Control", "public, max-age=300")
    w.Header().Set("Content-Disposition", "inline; filename=manual.pdf")
    // f 必须由调用方打开并确认过权限、目录和关闭责任。
    http.ServeContent(w, r, "manual.pdf", modtime, f)
}

如果文件内容会在服务期间被替换，修改时间并不能独立保证强一致。需要稳定版本时，可把版本号放进 URL 或 ETag 体系，由业务层保证版本和文件句柄对应；不要用一个长生命周期打开的文件对象跨请求共享 Seek 位置。

用响应状态核对实现

可以把验收拆成四个互不混淆的请求：普通 GET 看 200 和内容长度；带一个合法 Range 看 206、Content-Range 和正文片段；携带上次的 Last-Modified 看 304；请求超出文件长度的范围看 416。本文只给出检查维度，不把示例输出冒充为本机运行结果。

最后再确认关闭文件、鉴权、根目录和缓存策略都由外层代码承担。这样 ServeContent 负责协议细节，业务代码负责资源权限，问题定位会比把所有逻辑塞进一个 Handler 更清楚。

常见问题

为什么 Range 请求仍然返回 200？先确认请求头确实到达 Handler，再确认内容对象实现了 io.Seeker，并检查中间件是否提前写入了响应头或正文。

为什么浏览器缓存命中后没有正文？304 本来就表示客户端可以使用已有缓存，服务端不应继续写完整正文；若业务要求重新下载，应调整缓存条件或 URL 版本策略。