静态内容缓存

http.ServeContent 的 modtime 不是随便填的展示字段，它决定了响应里的 Last-Modified，也参与 If-Modified-Since 条件请求判断。静态文件应传文件元数据的修改时间；内存里的内容则应传一个与内容版本绑定、且在内容不变时保持不变的时间。每次请求都传 time.Now()，反而会让客户端很难命中 304。

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

ServeContent 的缓存判断到底依赖什么

ServeContent 接收的是一个可定位读取的内容对象、一个资源名和一个修改时间。它会根据资源名尝试设置 MIME 类型，根据 ReadSeeker 的末尾位置计算长度，并处理 Range 与多种条件请求。这里的 modtime 负责的是“这个版本什么时候修改过”这一事实，不是“本次请求什么时候到达”。

当服务端把 modtime 写成稳定值时，可以在响应中提供 Last-Modified。客户端后续带上 If-Modified-Since，服务端就能比较请求中的时间和当前资源版本，决定是否还需要发送正文。资源没有变化时，响应可以是 304，客户端继续使用已有副本。

真实文件直接使用 FileInfo.ModTime

文件服务最简单，也最不容易错：打开文件后读取 FileInfo，把 ModTime() 传给 ServeContent。文件内容和时间来自同一个文件对象，发布替换文件时，内容版本与修改时间通常会一起变化。

package main

import (
	"net/http"
	"os"
)

func serveAsset(w http.ResponseWriter, r *http.Request) {
	const path = "public/app.js"

	f, err := os.Open(path)
	if err != nil {
		http.NotFound(w, r) // 文件不存在时直接返回，避免把半打开的资源继续发送
		return
	}
	defer f.Close() // ServeContent 返回后再关闭文件，保证读取期间句柄有效

	info, err := f.Stat()
	if err != nil {
		http.Error(w, "读取文件信息失败", http.StatusInternalServerError) // 元数据失败时不要伪造缓存时间
		return
	}

	// ModTime 描述当前文件版本；不要改成 time.Now()。
	http.ServeContent(w, r, info.Name(), info.ModTime(), f)
}

这里的 name 主要参与 MIME 类型推断，并不会把文件名自动写进响应；真正决定条件请求版本的是 info.ModTime()。如果文件由原子替换发布，建议让“写临时文件、完成写入、替换目标文件”保持在一个清晰的发布边界内，避免读取到内容和元数据不匹配的中间状态。

内存内容要保存内容版本时间

如果内容来自数据库、配置中心或模板渲染结果，不能从文件系统读取 ModTime。这时需要在内容更新时同时保存版本时间，读取请求时复用它。下面的示例把正文和发布时间放在同一个快照里，保证两者不会分别取值。

type contentSnapshot struct {
	body     []byte
	modTime time.Time
}

func serveSnapshot(w http.ResponseWriter, r *http.Request, s contentSnapshot) {
	// 每个请求使用与正文绑定的版本时间，而不是请求到达时间。
	reader := bytes.NewReader(s.body)
	http.ServeContent(w, r, "index.html", s.modTime, reader)
}

func newSnapshot(body []byte) contentSnapshot {
	return contentSnapshot{
		body:     bytes.Clone(body), // 快照拥有独立字节，避免上游继续修改正文
		modTime: time.Now().UTC(),   // 只在内容版本创建时取一次当前时间
	}
}

上面的代码需要导入 bytes 和 time。关键不是使用 UTC 还是本地时区，而是同一份内容在生命周期内保持同一个时间。内容更新时创建新快照，时间随新版本变化；内容未更新时，后续请求继续复用旧快照的时间。

为什么 time.Now() 放在请求函数里会破坏缓存

下面这种写法看起来“时间总是最新”，但它把资源版本误写成了请求时间：

func wrong(w http.ResponseWriter, r *http.Request, body []byte) {
	// 错误：每次请求都会得到新时间，客户端带回的旧时间几乎不会再次匹配。
	http.ServeContent(w, r, "index.html", time.Now(), bytes.NewReader(body))
}

如果正文完全没有变化，缓存判断仍然应该认为它是同一版本。把当前时间传进去后，服务端每次都宣称“资源刚刚修改”，这会让 Last-Modified 持续变化，并削弱条件请求带来的节省。正确做法是把时间放在内容快照、数据库版本记录或文件元数据中，由更新动作而不是访问动作改变它。

ModTime、ETag 与时间精度怎样分工

ModTime 适合表达“内容版本的大致修改时间”，但它不是内容哈希。不同内容如果落在相同的时间精度内，单靠时间可能无法区分；如果业务需要更强的版本识别，可以在写响应前设置稳定的 ETag，让 ServeContent 参与处理 If-Match、If-None-Match 或 If-Range。

几个容易忽略的边界

• 零时间和 Unix epoch：它们表示修改时间未知，不能指望 ServeContent 用它们生成有意义的 Last-Modified。
• 必须可 Seek：ServeContent 会定位到内容末尾计算大小，再回到开头；只会顺序输出的流不适合直接传入。
• 只改响应头不改版本：如果中间件覆盖了 Last-Modified，客户端看到的时间就可能与正文版本脱节。
• 不要把 304 当作故障：304 本来就不带新的正文，它表示客户端已有的表示仍可复用。

常见问题

ServeContent 的 modtime 传零值可以吗？

可以调用，但零值表示修改时间未知，不能依赖它生成有效的 Last-Modified 条件缓存。能获得稳定版本时间时，应传入真实时间。

内存字符串没有文件时间怎么办？

在内容更新时创建快照并记录发布时间或版本时间，之后所有请求使用同一份时间。不要在每次请求中调用 time.Now()。

有了 ModTime 还需要 ETag 吗？

不一定。普通静态文件可以先使用时间条件；如果内容可能在相同时间精度内变化，或者需要更强的实体匹配，再增加稳定 ETag。

为什么 bytes.Buffer 不能直接传给 ServeContent？

bytes.Buffer 实现的是读写缓冲接口，不是可定位的 io.ReadSeeker。可以先用 bytes.NewReader 包住不可变字节切片，或使用文件等可 Seek 的对象。

最后记一个判断句

ServeContent 的 modtime 应回答“这份正文属于哪个修改版本”，而不是“请求何时到达”。文件用 FileInfo.ModTime()，内存内容保存版本时间；当时间条件不足以区分内容时，再用稳定的 ETag 补上实体级判断。