Go http.ServeContent 如何控制缓存头

给 Go 文件接口加缓存时，最容易误判的一点是：http.ServeContent 会处理内容协商、修改时间、条件请求和 Range，但不会替你选择 Cache-Control 策略。真正稳定的做法是先写入缓存相关 Header，再调用 ServeContent；需要精确校验时，再在同一位置设置符合规范的 ETag。

先把四类缓存信息分开

可以把一次文件响应看成四层信息：缓存多久由 Cache-Control 表达，资源大致何时变化由 Last-Modified 表达，内容指纹由 ETag 表达，断点读取则由 Range 和 Accept-Ranges 负责。它们不是同一个开关。

所以“控制缓存头”通常不是修改 ServeContent 内部行为，而是明确哪些策略由业务决定，然后把它们放在调用边界上。

在 ServeContent 前设置 Cache-Control

下面的 Handler 以已经版本化的静态资源为例。文件名或 URL 发生变化时，旧缓存不会误认成新内容，可以给出较长的缓存时间；如果 URL 不带版本号，就应缩短时间或使用重新验证策略。

func assetHandler(w http.ResponseWriter, r *http.Request) {
    // 版本化资源允许客户端在一段时间内直接复用缓存。
    w.Header().Set("Cache-Control", "public, max-age=86400, immutable")

    // ETag 必须在 ServeContent 写入状态码前设置，值要保持稳定。
    w.Header().Set("ETag", `"asset-home-v3"`)

    f, err := os.Open("public/home.css")
    if err != nil {
        // 文件不存在时返回错误，不把成功资源的缓存策略当作业务承诺。
        http.NotFound(w, r)
        return
    }
    defer f.Close() // 无论是 200、304 还是 Range，都要释放文件句柄。

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

注意设置顺序：一旦 Handler 或 ServeContent 写入状态码，之后再修改 Header 通常已经来不及。Header.Set 比 Header.Add 更适合单值缓存头，避免意外形成多个相互矛盾的策略。

让 modtime 和 ETag 各司其职

传入非零修改时间后，ServeContent 会写入 Last-Modified，并依据 If-Modified-Since 判断是否可以直接返回 304。这个判断适合文件系统时间能代表内容版本的场景。

如果内容来自对象存储、数据库或构建产物，修改时间可能不够精确。此时可以把内容版本、提交号或稳定哈希放进 ETag。ETag 必须在调用前写入，ServeContent 才能参与 If-None-Match、If-Match 和 If-Range 的处理。不要把每次请求时间拼进 ETag，那会让缓存永远无法命中。

也不要把 Cache-Control: no-store 和“希望通过 304 节省传输”混为一谈：前者要求不要存储响应，后者依赖客户端保留验证信息。先确定资源是否允许被保存，再决定是强缓存、每次验证还是完全不缓存。

检查 Range、压缩和错误响应边界

ServeContent 要求内容实现可用的 io.ReadSeeker，它会定位到末尾计算大小，并默认声明 Accept-Ranges: bytes。单段 Range 会产生 206 和 Content-Range；请求无效时会返回 416。若把不可定位的实时流硬塞进来，缓存和范围读取都不再是可靠选择。

另一个坑是动态 gzip 包装。标准库需要知道可定位内容的长度；如果外层 ResponseWriter 改变了实际字节数，Content-Length 就可能失真。更稳的方案是提前生成可定位的压缩文件，或者放弃 ServeContent，自己管理流式响应和对应的缓存语义。

最后，生产环境要区分“资源成功响应的缓存策略”和“异常响应的缓存策略”。文件打开失败时应尽早返回，不要先把长期缓存头写成对所有状态都适用的承诺；如果确实需要统一策略，至少确认网关不会把 404 或 500 长时间缓存。

上线前用一张清单复核

• 资源 URL 是否带版本号？带版本号才适合 immutable。
• Cache-Control 是否在 ServeContent 前设置？是否会被中间件覆盖？
• modtime 是否能反映真实内容变化？不能时是否准备了稳定 ETag？
• 文件是否真的可 Seek？是否需要 Range 或断点下载？
• 压缩中间件是否改变了响应字节数？若改变，是否改为预压缩文件？

把这五点落实后，ServeContent 就适合承担“可定位内容的 HTTP 输出”，而缓存时长、版本策略和是否允许存储仍由你的 Handler 决定。

相关问题

ServeContent 会自动设置 Cache-Control 吗？

不会。它会处理修改时间、条件请求和范围读取，但缓存时长与是否允许公共缓存需要调用方明确设置。

ETag 要在什么时候设置？

在调用 ServeContent 之前设置。标准库会读取已有的 ETag 来处理 If-None-Match 等请求条件。

modtime 传零值会怎样？

零值表示修改时间未知，ServeContent 不会据此生成有效的 Last-Modified 条件判断；可以改用稳定 ETag。

为什么加了 gzip 后 Content-Length 不对？

ServeContent 面向可定位且长度已知的内容，动态压缩改变了实际字节数。优先提供预压缩的可 Seek 文件，或改用自定义流式响应。