Go http.ServeContent 怎样利用修改时间处理缓存

我排查过一类很容易误判的文件接口：服务端明明调用了 http.ServeContent，客户端却每次都重新接收完整内容。问题往往不在“有没有设置缓存”这一句，而在资源的修改时间有没有被正确传入，以及请求是否真的带着合法的 If-Modified-Since。

实用结论是：把稳定的资源修改时间作为 modtime 传给 ServeContent，它就能自动生成 Last-Modified，并对 GET/HEAD 的条件请求做修改时间比较；时间没有更新时可以返回 304。这个参数负责“资源是否变化”的校验，不等于完整的缓存寿命策略。

官方地址：https://pkg.go.dev/net/http#ServeContent

先分清 modtime 和缓存策略

ServeContent 的第四个参数是资源的修改时间。只要它不是零时间或 Unix epoch，标准库就会把它格式化成 UTC 的 Last-Modified 响应头；下一次请求如果带上 If-Modified-Since，标准库就有了比较依据。

所以排查时应先看三件事：服务端传入的时间是否稳定，响应是否出现 Last-Modified，后续请求是否带回了 If-Modified-Since。单独设置一个响应头，不能替代这条闭环。

把文件修改时间交给 ServeContent

文件资源最直接的来源是 os.File.Stat 返回的 FileInfo.ModTime。下面的处理器只展示资源时间和可读取内容之间的衔接，错误分支也要保留，否则文件打不开时很容易把缓存问题误判成客户端问题。

package main

import (
    "net/http"
    "os"
)

func download(w http.ResponseWriter, r *http.Request) {
    f, err := os.Open("public/report.pdf")
    if err != nil {
        // 打开失败先返回 404，避免把不存在的资源当成缓存命中。
        http.NotFound(w, r)
        return
    }
    defer f.Close()

    info, err := f.Stat()
    if err != nil {
        // 读取元数据失败时停止处理，不能凭当前时间伪造 Last-Modified。
        http.Error(w, "读取文件信息失败", http.StatusInternalServerError)
        return
    }

    // name 用于推断类型，ModTime 用于 Last-Modified 和条件请求比较。
    http.ServeContent(w, r, info.Name(), info.ModTime(), f)
}

这里的关键不是把当前时间传进去，而是传入资源本身的修改时间。每次请求都用 time.Now() 会让校验时间不断前移，客户端几乎不可能带回一个能命中的旧值；传零时间则会让 ServeContent 失去这条条件判断依据。

If-Modified-Since 为什么会得到 304

标准库源码中的判断有几个容易漏掉的边界。它只对 GET 和 HEAD 检查 If-Modified-Since；请求头为空、日期解析失败，或 modtime 是零时间时，都会放弃这条条件判断并继续正常返回内容。

另外，HTTP 的 Last-Modified 只保留到秒。Go 源码会先把 modtime 截断到秒，再和解析出的请求时间比较：当截断后的修改时间小于或等于请求时间时，资源被视为没有更新，可以写入 304；否则继续发送内容。

// 这段伪代码对应标准库的判定含义，展示逻辑而非运行输出。
if (r.Method == "GET" || r.Method == "HEAD") &&
    r.Header.Get("If-Modified-Since") != "" && !modtime.IsZero() {
    // HTTP 日期没有亚秒精度，比较前要统一到秒。
    requestTime, err := http.ParseTime(r.Header.Get("If-Modified-Since"))
    if err == nil && modtime.Truncate(time.Second).Compare(requestTime) 

上面代码只是帮助理解标准库内部关系，实际项目不需要自己复制这套判断；正确做法是让 ServeContent 统一处理。若资源在同一秒内被替换，单靠修改时间可能看不出变化，这正是需要更强实体校验时补充 ETag 的边界。

缓存没有命中时按三层排查

遇到“每次都返回 200”时，我会按下面的顺序缩小范围，而不是先改客户端缓存设置：

1. 看资源时间：确认所有实例拿到的是同一份文件或同一份对象元数据，不能一台机器返回旧时间、另一台返回新时间。
2. 看响应头：检查 Last-Modified 是否存在，时间是否随着资源真实更新而变化；零时间通常意味着传参来源没有接上。
3. 看条件请求：确认后续 GET/HEAD 是否带回 If-Modified-Since，并且值是合法的 HTTP 日期。没有请求头时，服务端没有条件比较的输入。

如果三层都成立仍然没有命中，再检查是否有其他前置处理器改写了响应，或资源在同一秒内频繁替换。不要把 Cache-Control 的 max-age 和 Last-Modified 混成同一个开关：前者偏向新鲜度策略，后者偏向修改时间校验。

常见延伸问题

modtime 传 time.Now() 可以吗？

不建议。它代表请求发生时间而不是资源修改时间，会让每次响应的校验基准变化，条件请求难以稳定命中。应从文件、对象存储元数据或数据库记录中取得真实修改时间。

为什么同一秒内更新文件，客户端仍可能复用旧内容？

因为 Last-Modified 的表达精度是秒，标准库比较前也会截断亚秒部分。需要区分同一秒内的不同版本时，应为响应提供稳定的 ETag，并让调用方按内容身份做更强校验。

HEAD 请求也会使用 If-Modified-Since 吗？

会。标准库对 GET 和 HEAD 都检查这个条件；HEAD 本身不返回正文，但仍可用于确认资源元数据和状态。

Last-Modified 出现了就说明浏览器一定不下载吗？

不是。它只提供了一个可参与条件请求的修改时间。客户端是否保存副本、何时发起条件请求，还会受到缓存策略、请求方式和中间层行为影响。

这次问题最后可以收敛成一句话：ServeContent 能否利用修改时间处理缓存，取决于你是否把稳定、真实的资源 ModTime 传进来，以及客户端是否带回合法的 If-Modified-Since。先把这两个点对齐，再讨论更复杂的缓存策略，排查会清楚很多。