Go 静态资源接口怎么处理 ETag 和条件请求

给 Go 静态资源接口加缓存时，关键不是把文件内容再算一遍摘要，而是让“资源版本”和响应头里的 ETag 稳定对应。首次请求返回 200；客户端再次带上匹配的 If-None-Match 时，handler 应返回 304，不重复发送正文。用 net/http 的 ServeContent 可以把条件请求、Range 和 MIME 类型处理交给标准库，但 ETag 仍要在调用前写入 ResponseWriter。

ServeContent 前为什么一定要先写 ETag

ServeContent 的职责是服务一个 io.ReadSeeker，并处理 Range、内容类型以及多种条件请求。它不会替应用决定资源指纹，所以 ETag 要先放到 w.Header() 里。最小 handler 可以把文件大小和修改时间组合成版本键；如果发布流程已经有内容哈希，优先直接使用哈希。

func asset(w http.ResponseWriter, r *http.Request) {
	// 版本键必须与实际资源版本绑定，不能每次随机生成。
	const etag = `"site-css-v17"`
	w.Header().Set("ETag", etag)

	file, err := os.Open("./public/site.css")
	if err != nil {
		// 文件不可读时不要继续调用 ServeContent。
		http.Error(w, "resource unavailable", http.StatusNotFound)
		return
	}
	defer file.Close()

	// name 用于推断 MIME 类型，file 必须支持 Seek。
	http.ServeContent(w, r, "site.css", time.Time{}, file)
}

这里的 ETag 使用带双引号的实体标签格式。time.Time{} 表示不额外依赖 Last-Modified；如果资源来自文件系统，也可以传入文件的修改时间，让 If-Modified-Since 一并参与判断。

客户端带 If-None-Match 时会发生什么

客户端第一次拿到响应头中的 ETag 后，可以在下一次请求里发送同一个值：

req, err := http.NewRequest(http.MethodGet, "http://localhost:8080/assets/site.css", nil)
if err != nil {
	// URL 构造失败时直接返回，避免发送不完整请求。
	return
}
req.Header.Set("If-None-Match", `"site-css-v17"`)
resp, err := http.DefaultClient.Do(req)
if err != nil {
	// 网络错误与 HTTP 状态码是两层问题，需要分开处理。
	return
}
defer resp.Body.Close()

// 304 表示复用本地缓存，200 才需要继续读取正文。
if resp.StatusCode == http.StatusNotModified {
	return
}
body, err := io.ReadAll(resp.Body)
_ = body
_ = err

如果 ETag 匹配，ServeContent 会让 GET/HEAD 请求走 304；这不是错误，也不是空响应异常。客户端应继续使用本地已缓存的文件。若 ETag 不匹配，则得到 200 和新的正文。

怎么判断 200、304 和资源更新后的结果

排查时只看三个字段就够了：请求中的 If-None-Match、响应中的 ETag、状态码。不要只看到 304 就认定缓存一定正确，还要确认它对应的是当前发布版本。

资源替换时最容易踩的三个坑

第一，不要把 ETag 写成每次请求都变化的随机值，否则客户端永远无法稳定命中。第二，不要只用文件名当 ETag；同名覆盖会让旧缓存误认为资源没有变化。第三，若自定义的资源读取器不支持从末尾定位，ServeContent 无法确定内容长度，应该改用真正实现 io.ReadSeeker 的对象。

另外，弱 ETag（例如 W/"site-css-v17"）适合表达语义等价但字节可能不同的表示；需要严格字节一致时使用强 ETag。Range 下载还要确保代理层没有改写 ETag 和响应正文的对应关系。

相关问题

ETag 能不能直接用文件修改时间？

可以，但修改时间粒度和跨机器同步可能造成误判。稳定的内容哈希或发布版本通常更可靠。

304 响应要不要写正文？

不需要。304 的意义就是让客户端复用已有正文，重点是保持 ETag 等缓存元数据一致。

ServeContent 会自动生成 ETag 吗？

不会。调用方需要在调用前设置 ETag；标准库再据此处理相关条件请求。

参考：Go net/http ServeContent 官方文档。