Go http.ServeContent 如何同时处理 Range 下载与 Last-Modified 缓存？

文件下载接口上线后，最先暴露的通常不是“能不能下载”，而是两个细节：用户拖动进度条时服务端是否只返回需要的那一段，文件没有变化时浏览器能不能直接复用本地副本。Go 标准库的 http.ServeContent 已经把这两条路径接起来了，但它不会替你决定文件名、修改时间和路径边界。

把 Range 和 Last-Modified 交给 http.ServeContent，关键是传入稳定的 io.ReadSeeker、可信的修改时间，并用 curl 验证 206、Content-Range 和 304，而不是只看浏览器能否打开文件。

先把下载接口的边界定清楚

示例服务只暴露 ./downloads 目录里的文件，URL 形如 /files/report.pdf。这里的目标不是写一个完整网盘，而是让 HTTP 语义可观察：整文件返回 200，合法区间返回 206，缓存命中返回 304，越界请求不读到目录之外的内容。

新建一个小项目：

mkdir serve-range
cd serve-range
go mod init example.com/serve-range
mkdir downloads
printf 'page-1\npage-2\n' > downloads/readme.txt

真实项目里，下载目录最好来自配置并在启动时转成绝对路径。示例先固定目录，方便把请求结果和磁盘文件一一对上。

用 http.ServeContent 接住 Range 请求

ServeContent 需要四个关键输入：响应写入器、请求、展示名称、修改时间和一个支持 Seek 操作的文件。它会自动读取请求里的 Range 字段，计算偏移并设置对应响应头；文件句柄本身必须实现 io.ReadSeeker，普通的 *os.File 正好满足这个要求。

package main

import (
    "net/http"
    "os"
    "path/filepath"
    "strings"
)

var downloadRoot = "./downloads"

func fileHandler(w http.ResponseWriter, r *http.Request) {
    name := strings.TrimPrefix(r.URL.Path, "/files/")
    if name == "" || strings.Contains(name, "..") {
        http.Error(w, "invalid file name", http.StatusBadRequest)
        return
    }

    root, err := filepath.Abs(downloadRoot)
    if err != nil {
        http.Error(w, "file root unavailable", http.StatusInternalServerError)
        return
    }
    full, err := filepath.Abs(filepath.Join(root, filepath.FromSlash(name)))
    if err != nil || (full != root && !strings.HasPrefix(full, root+string(os.PathSeparator))) {
        http.Error(w, "file outside root", http.StatusBadRequest)
        return
    }

    f, err := os.Open(full)
    if err != nil {
        http.NotFound(w, r)
        return
    }
    defer f.Close()

    info, err := f.Stat()
    if err != nil || !info.Mode().IsRegular() {
        http.NotFound(w, r)
        return
    }
    http.ServeContent(w, r, filepath.Base(full), info.ModTime(), f)
}

func main() {
    http.HandleFunc("/files/", fileHandler)
    http.ListenAndServe(":8080", nil)
}

这里别急着把 Content-Disposition、鉴权和限速全部塞进处理函数。先确认标准库给出的 Range 行为正确，再单独增加下载权限和审计逻辑。文件名传 filepath.Base(full) 只用于填充响应语义，不能代替前面的根目录校验步骤。

为什么同一个接口会返回 200、206 和 304

用三次请求看状态，比在浏览器开发者工具里凭感觉判断更可靠：

go run .

curl -i http://127.0.0.1:8080/files/readme.txt
curl -i -H 'Range: bytes=0-5' http://127.0.0.1:8080/files/readme.txt
curl -i -H 'Range: bytes=999-1200' http://127.0.0.1:8080/files/readme.txt

整文件请求通常返回 200；合法区间请求返回 206，并带有类似 Content-Range: bytes 0-5/14 的范围说明。最后一个区间超过文件末尾时，标准库会按 HTTP 协议规则处理，客户端应关注响应状态和 Content-Range，不要只断言“返回内容非空”就完事。

在没有 Range 头的情况下，响应会带 Last-Modified。客户端把这个值原样带回请求头：

last_modified=$(curl -sD - http://127.0.0.1:8080/files/readme.txt -o /dev/null | awk -F': ' 'tolower($1)=="last-modified"{print $2}' | tr -d '\r')
curl -i -H "If-Modified-Since: $last_modified" http://127.0.0.1:8080/files/readme.txt

如果文件的修改时间没有变化，响应可以直接返回 304，正文为空。修改时间来自 f.Stat().ModTime()；如果业务把文件内容放在对象存储或数据库里，就不能随便传当前时间，否则每次请求都会让缓存完全失去意义。

迁移时最容易漏掉的三个细节

ReadSeeker 不能被一次性读取替代

把文件先读进 []byte 再交给一个只会返回固定内容的 Reader，会直接丢掉按偏移读取的能力。小文件可以使用 bytes.NewReader，但要确认它实现了 io.ReadSeeker；大文件直接打开原生文件句柄更稳妥。

修改时间要与内容版本绑定

如果生成文件后又覆盖了原文件，却保留旧的 mtime，客户端可能错误地拿到 304 缓存响应。写临时文件、fsync 后 rename 的流程，应在替换完成后确认最终文件的时间戳，或者改用内容摘要做更强的缓存校验。

不要把路径判断简化成字符串前缀

/srv/downloads2 不是 /srv/downloads 的子目录。路径比较至少要补上分隔符，并先统一清理成绝对路径再判断；更复杂的服务可以用白名单映射文件 ID 到真实存储路径，彻底避免用户控制目录层级。

用测试把四种结果锁住

迁移完成后，最小回归集应覆盖以下边界：

• 不带 Range：状态 200，正文等于完整文件。
• 合法 Range：状态 206，Content-Range 的总长度正确。
• 带正确 If-Modified-Since：状态 304，正文长度为 0。
• 路径含 .. 或目标不是普通文件：返回错误，不访问根目录之外。

还要注意测试时间精度。HTTP 日期按秒表达，而文件系统的修改时间可能带纳秒；比较时按协议允许的精度处理，不要把纳秒级差异误判为缓存失效。

常见问题

ServeContent 能直接支持断点续传吗？

它能处理常见的单个 Range 请求并返回 206，但鉴权、下载记录、并发限速和多区间策略仍需要业务层自己设计。

为什么拿到的不是 304？

先检查请求是否带回了完整的 Last-Modified 值，再确认服务端传入的 modtime 没有每次刷新；代理层改写响应头也会影响结果。

文件内容变了但时间没变怎么办？

修复文件替换流程，保证最终文件有新的修改时间；如果内容版本控制要求更严格，可以额外提供 ETag 并在应用层维护内容摘要。

收尾检查

http.ServeContent 适合把标准 HTTP 文件语义落地，但它的正确性依赖调用方提供的路径和时间。把目录约束、io.ReadSeeker、Range/缓存请求和四类回归结果一起验收，下载接口才算真正可上线。