Go http.ServeContent实现范围请求时的文件时间处理要点

我在给大文件下载接口补 Range 支持时，最容易写错的不是 Range: bytes=...，而是传给 http.ServeContent 的 modtime。它应该代表“这份资源何时发生变化”，不能在每次请求里用 time.Now() 代替。磁盘文件直接取 FileInfo.ModTime()；动态内容没有可靠修改时间时传零值，再用稳定的 ETag 管理缓存。

官方文档：https://pkg.go.dev/net/http#ServeContent

先把时间条件和范围条件分开处理

ServeContent 的调用顺序可以理解成两层：先根据 ETag、If-Modified-Since 等条件判断是否已经可以返回，之后才解析 Range。因此，收到 Range 不代表必然返回 206；如果条件未满足，可能先返回 304；如果日期型 If-Range 与当前 modtime 不一致，Range 会被放弃，回到完整响应。

这也是排查“客户端明明带了 Range，服务端却返回 200”的第一处边界：先看 If-Range 是否失败，再看资源是否真的可 Seek，而不是只盯着 Range 字符串。

正确传入 modtime，范围响应才有稳定的缓存边界

本地文件场景通常不需要自己实现范围解析。关键是打开文件、读取同一个文件的元数据，再把可定位的文件句柄交给 ServeContent。name 主要用于推断 MIME 类型，不是下载文件名。

func serveAsset(w http.ResponseWriter, r *http.Request) {
	// 文件字节和文件元数据必须来自同一份资源。
	f, err := os.Open("public/video.mp4")
	if err != nil {
		http.Error(w, "asset unavailable", http.StatusNotFound)
		return
	}
	defer f.Close() // 请求结束后释放文件描述符。

	info, err := f.Stat()
	if err != nil {
		http.Error(w, "asset metadata unavailable", http.StatusInternalServerError)
		return
	}

	// 使用稳定的文件修改时间；不要把请求时间当成资源版本。
	http.ServeContent(w, r, info.Name(), info.ModTime(), f)
}

如果资源来自内存，可以使用 bytes.NewReader(data) 提供 io.ReadSeeker，但 modtime 仍应来自构建时间、对象版本时间等稳定元数据。若没有可信时间，传 time.Time{}，这会关闭基于 Last-Modified 的判断，而不是关闭 Range。

用请求矩阵检查 200、206 和 304

我更愿意把下面这张表当成上线前的最小检查清单。它不要求把内部实现改成一套新的下载器，只检查输入头和关键输出是否符合资源语义。

如果显式设置了 ETag，要在调用前完成，因为 ServeContent 会利用响应头中的 ETag 处理 If-Match、If-None-Match 和 ETag 型 If-Range。动态压缩也要谨慎：范围读取依赖可定位且长度稳定的表示，边读边改变字节的包装方式容易让 Content-Length 与实际内容失配。

几个容易混淆的边界

• modtime 不是 Range 起点。它描述资源版本；Range 起点由请求头决定。
• 零时间不等于禁用部分响应。它只是不提供 Last-Modified 条件，Seekable 内容依然可以处理 Range。
• 亚秒时间不要拿来直接比较。HTTP 的 Last-Modified 按秒表达，Go 实现会先按秒截断再做条件判断。
• 无效范围要接受 ServeContent 的错误响应。不要为了强行返回 206 而手工拼接 Content-Range。

相关问题

为什么不能每次传 time.Now()？

因为客户端下一次带回的 If-Modified-Since 几乎总会早于新的请求时间，缓存条件就失去复用价值，资源没有变化也可能重复传输。

只有内存字节切片，能不能支持 Range？

可以，用 bytes.NewReader 作为 io.ReadSeeker，同时为这份内容选择稳定的构建时间或版本 ETag。

收到 Range 却看到 200 是错误吗？

不一定。若 If-Range 校验失败，ServeContent 会忽略范围并返回完整内容；先检查 ETag 或日期是否对应同一版本。