Go http.ServeContent 怎么处理 Range 请求：If-Modified-Since、ETag 与下载验收

给一个几十 MB 的安装包或视频文件做下载接口时，最容易误判的是“返回 200 就算成功”。浏览器暂停后继续下载，通常需要服务器正确回应 Range；文件没变化时，If-Modified-Since 可以让客户端拿到 304；而 ETag 并不是 http.ServeContent 自动替你生成的，应用仍要自己决定版本标识和比较规则。

先把下载接口缩成一个能验收的小项目

这次场景很具体：服务把 public/releases/demo.bin 提供给客户端，客户端可能第一次完整下载，也可能只请求其中一段。接口不需要先把文件读进内存，重点是让标准库根据文件大小、修改时间和请求头生成正确响应。

目录可以保持最小结构：

download-demo/
├── main.go
└── public/
    └── releases/
        └── demo.bin

文件内容可以先用一份可重复的测试数据代替，验收时不要依赖“浏览器看起来能下载”，而要保存响应头和字节数。

核心代码：先设置 ETag，再交给 ServeContent

ServeContent 接收一个名称、修改时间和 io.ReadSeeker。它会处理 Range、If-Modified-Since 以及 HEAD 请求，但 ETag 不在它的自动职责里。下面用文件大小和修改时间构造一个简单版本标识；生产环境如果文件内容会原地覆盖，应该改用发布版本或内容哈希。

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "net/http"
    "os"
    "strconv"
)

func release(w http.ResponseWriter, r *http.Request) {
    f, err := os.Open("public/releases/demo.bin")
    if err != nil {
        http.Error(w, "release not found", http.StatusNotFound)
        return
    }
    defer f.Close()

    info, err := f.Stat()
    if err != nil {
        http.Error(w, "release stat failed", http.StatusInternalServerError)
        return
    }

    version := sha256.Sum256([]byte(strconv.FormatInt(info.Size(), 10) + ":" + info.ModTime().UTC().Format("20060102150405")))
    etag := `"` + hex.EncodeToString(version[:8]) + `"`
    w.Header().Set("ETag", etag)
    if r.Header.Get("If-None-Match") == etag {
        w.WriteHeader(http.StatusNotModified)
        return
    }

    http.ServeContent(w, r, info.Name(), info.ModTime(), f)
}

func main() {
    http.HandleFunc("/releases/demo.bin", release)
    fmt.Println("listening on http://127.0.0.1:8080")
    if err := http.ListenAndServe(":8080", nil); err != nil {
        panic(err)
    }
}

这里的 ETag 只用于演示协商流程。注意它不是文件内容哈希，而是“大小 + 修改时间”的短指纹；如果部署系统会保留原修改时间却替换文件内容，这个方案就不够安全，应在发布阶段生成内容哈希并保存。

不要把 ETag 比较和 Range 逻辑混在一起

示例先处理 If-None-Match，命中后直接返回 304。未命中时才进入 ServeContent 的正常路径。这样读者能清楚看到：ETag 是应用自己的缓存协商；Range 是下载表示的局部传输，两者可能同时出现在请求中，最终规则仍要按 HTTP 条件请求语义设计和测试。

运行后分别观察 200、206、304 和 416

启动服务后，先准备一份足够大的 demo.bin。第一次完整请求应该得到 200，并能看到 Last-Modified、ETag 和完整的 Content-Length：

curl -i http://127.0.0.1:8080/releases/demo.bin

拿到响应中的 ETag 后，带上 If-None-Match 再请求。命中时正文为空，状态是 304：

curl -i -H 'If-None-Match: "把响应里的值填在这里"' \
  http://127.0.0.1:8080/releases/demo.bin

Range 请求只取前 1024 个字节，正常情况下状态为 206，响应里应有 Content-Range: bytes 0-1023/总大小：

curl -i -H 'Range: bytes=0-1023' \
  http://127.0.0.1:8080/releases/demo.bin

如果范围从文件末尾之外开始，服务应返回 416。这个状态不是“服务器挂了”，而是客户端请求的区间没有可传输内容；验收时要确认响应里的范围提示，而不是只检查 HTTP 是否为 2xx。

把文件部署到真实服务时，保留这三个边界

文件名和响应类型要由服务端控制

ServeContent 会根据名称推断部分响应信息，但下载接口仍应固定资源目录和路由，不要把用户提交的任意路径直接拼进文件系统。若需要动态选择版本，先从白名单映射到服务端路径，再打开文件。

修改时间不是内容版本

If-Modified-Since 适合表达“这个时间之后文件是否变化”。它受时间精度和部署时钟影响，不能替代内容版本。发布系统最好同时维护不可变版本名，并把 ETag 或版本号绑定到真正的发布产物。

不要用一次性读入内存验证大文件

测试时可以比对响应体哈希，但服务实现应让 ServeContent 从可定位的文件句柄读取。这样 Range 请求只需要读取对应区间，内存占用不会随文件整体大小线性增长。

常见问题

为什么 Range 请求返回 200 而不是 206？

先确认请求头确实发送到了目标路由，再检查资源是否支持定位读取、范围格式是否有效，以及中间层是否改写或移除了 Range。最终应以服务端原始响应头为准。

ServeContent 会自动生成 ETag 吗？

不会。它会根据名称和修改时间处理部分缓存行为，但 ETag 需要应用设置，并明确比较 If-None-Match 的策略。

下载接口只测浏览器够不够？

不够。浏览器可能隐藏了 206、304 和 Content-Range 的细节。至少用命令行分别验收完整请求、合法 Range、缓存命中和越界 Range，并检查响应体长度。

把验收标准写成响应头清单

这个小项目真正有用的地方，不是记住一个函数名，而是把下载成功拆成可观察结果：完整请求看 200 和长度，分片请求看 206 与 Content-Range，缓存命中看 304 与空正文，非法范围看 416 与范围提示。ETag 则单独由应用维护，不能把它和 ServeContent 的默认能力混为一谈。