Go实现HTTP缓存与ETag优化技巧

本文深入解析了 Go 语言中 HTTP 缓存机制的核心实践，聚焦 Cache-Control、ETag 和 Last-Modified 三大关键头字段的语义差异、优先级规则与协同逻辑，并手把手演示如何用 http.ServeContent 实现安全可靠的 ETag 校验——从自定义强 ETag 生成、正确解析 If-None-Match 头（避开 strings.Contains 坑）、到 embed.FS 与 os.DirFS 场景下的差异化策略，同时强调易被忽视却至关重要的细节：ETag 必须用英文双引号包裹、no-cache 并非不缓存而是强制验证、大文件哈希的性能权衡，以及动态接口滥用 max-age 的隐患，助你构建既高效又健壮的生产级缓存体系。

HTTP 缓存头该设哪些字段，顺序和组合有影响吗

Go 的 http.ServeFile 和 http.FileServer 默认不加任何缓存控制，必须手动设置。关键字段就三个：Cache-Control、ETag、Last-Modified，但它们不是随便加就能生效的。

优先级上，Cache-Control 会覆盖 Expires；而 ETag 和 Last-Modified 同时存在时，客户端优先用 ETag 做校验（RFC 7232 明确规定）。所以如果你打算用 ETag，Last-Modified 可以不设，避免冗余或冲突。

• Cache-Control: public, max-age=3600 表示可被 CDN 和浏览器缓存 1 小时
• Cache-Control: no-cache 不代表“不缓存”，而是强制每次向服务端验证（走 304）
• Cache-Control: no-store 才是真不存——连内存都不许缓存，敏感数据才用
• 不要在动态接口上硬塞 max-age=86400，哪怕内容一时没变，也容易掩盖逻辑 bug

用 http.ServeContent 实现带 ETag 的流式响应

http.ServeContent 是 Go 标准库里唯一能自动处理 If-None-Match 和 If-Modified-Since 并返回 304 的函数，但它要求你提供内容长度、修改时间、以及一个生成 ETag 的函数。

注意：它不会帮你算 ETag，得自己实现。常见做法是用文件内容哈希（如 sha256），但对大文件要避免读全量——可以用 io.Seeker + 分块哈希，或者退而求其次用 file.ModTime().UnixNano() + file.Size() 拼接后哈希（简单够用，但有碰撞风险）。

func serveWithETag(w http.ResponseWriter, r *http.Request, file os.FileInfo, content io.ReadSeeker) {
	etag := fmt.Sprintf(`"%x"`, sha256.Sum256([]byte(fmt.Sprintf("%d-%d", file.Size(), file.ModTime().UnixNano()))))
	http.ServeContent(w, r, file.Name(), file.ModTime(), &etagger{content, etag})
}

type etagger struct {
	io.ReadSeeker
	etag string
}

func (e *etagger) ModTime() time.Time { return time.Now() } // ServeContent 会调这个，但实际用不到
func (e *etagger) Size() int64          { return 0 }        // 同上，ServeContent 要求实现但可返回 0
func (e *etagger) Etag() string         { return e.etag }

上面代码里 Size() 返回 0 是安全的，因为 http.ServeContent 在已知长度时会跳过部分逻辑；真正起作用的是你传入的 file.ModTime() 和自定义 Etag() 方法。

手动处理 ETag 校验时，If-None-Match 的解析不能靠 strings.Contains

客户端发来的 If-None-Match 可能是 "abc"、"abc", "def"、甚至带 W/"weak" 前缀。直接用 strings.Contains(r.Header.Get("If-None-Match"), myETag) 会漏掉弱校验、误判逗号分隔场景，还可能被注入干扰。

标准做法是用 http.ParseETag（注意不是 ParseHeader）：

if match := r.Header.Get("If-None-Match"); match != "" {
	if list, err := http.ParseETag(match); err == nil {
		for _, etag := range list {
			if etag.Value == myETag && !etag.Weak {
				w.WriteHeader(http.StatusNotModified)
				return
			}
		}
	}
}

这里有个坑：http.ParseETag 会把 W/"abc" 解析成 Weak=true，而你的 myETag 如果是强 ETag（没带 W/），就不能匹配——所以要么统一用强 ETag，要么校验时同时支持弱比对（但语义不同，弱 ETag 允许语义等价即可，Go 标准库不帮你做语义判断）。

静态文件服务中，fs.FS 和 embed.FS 对 ETag 的影响

Go 1.16+ 的 embed.FS 是只读、编译期确定的，文件内容不可变，适合用内容哈希做 ETag；而 os.DirFS 或自定义 fs.FS 可能运行时变更，用 ModTime 更稳妥。

• embed.FS 推荐用 embed.FS.ReadFile 读取后计算 sha256，再拼进 ETag，这样部署更新后哈希自然变，CDN 也能及时失效
• os.DirFS 下如果文件可能被热更新（比如配置文件），别用内容哈希——读文件时可能正被写入，导致哈希出错或 panic
• 所有基于 fs.FS 的服务，记得在 http.FileServer 外包一层 handler，否则 ETag 和 Cache-Control 都不会自动加

最易忽略的一点：ETag 值必须用英文双引号包裹，且内部不能含双引号或控制字符；很多手写的 ETag 忘了加外层引号，导致客户端直接忽略该头——这不是 bug，是 RFC 强制要求。

本篇关于《Go实现HTTP缓存与ETag优化技巧》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于Golang的相关知识，请关注golang学习网公众号！