Go http.ServeContent 怎么支持范围请求与缓存校验

http.ServeContent 可以把一个支持定位的内容源变成具备范围请求和缓存协商能力的 HTTP 响应：它会处理 Range、If-Range、If-Modified-Since、If-None-Match 等请求头。调用方要做的关键工作是提供可用的 io.ReadSeeker、正确的修改时间，并在调用前设置好合法的 ETag。

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

项目目标：一个可续传、可协商缓存的文件端点

我第一次给 PDF 下载接口加断点续传时，直接使用了 io.Copy。完整下载没有问题，但浏览器拖动进度、下载器续传和客户端缓存都需要额外处理。继续手写协议细节很容易遗漏边界，所以这个小项目改用 http.ServeContent：业务代码只准备资源元数据，范围解析和条件请求交给标准库。

函数签名是 ServeContent(w, req, name, modtime, content)。其中 name 主要用于根据扩展名判断 MIME 类型，不会作为文件名自动发送给客户端；modtime 用于生成和比较 Last-Modified；content 必须实现 io.ReadSeeker，因为标准库需要定位范围并寻址到末尾计算总长度。

ServeContent 的调用契约

核心代码：启动时准备资源并交给 ServeContent

下面用一个内存版资源完成最小可用端点。启动时只读取和散列一次文件，请求到达后用新的 bytes.Reader 提供独立的 Seek 游标，避免多个请求共享同一偏移量。

package main

import (
    "bytes"
    "crypto/sha256"
    "fmt"
    "log"
    "net/http"
    "os"
    "time"
)

type asset struct {
    name    string
    data    []byte
    modTime time.Time
    etag    string
}

func loadAsset(path, name string) (*asset, error) {
    // 小文件在启动时读入内存，避免每次请求都重复读取和计算摘要。
    data, err := os.ReadFile(path)
    if err != nil {
        return nil, err
    }
    info, err := os.Stat(path)
    if err != nil {
        return nil, err
    }

    // 强 ETag 必须带双引号；摘要变化时校验值也会变化。
    sum := sha256.Sum256(data)
    return &asset{
        name:    name,
        data:    data,
        modTime: info.ModTime(),
        etag:    fmt.Sprintf(`"%x"`, sum[:]),
    }, nil
}

func (a *asset) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // ETag 必须在 ServeContent 之前设置，标准库才会处理相关条件请求。
    w.Header().Set("ETag", a.etag)
    w.Header().Set("Cache-Control", "public, max-age=300")
    w.Header().Set("Content-Disposition", `inline; filename="manual.pdf"`)

    // 每次请求创建独立 Reader，同时满足 Reader 和 Seeker。
    http.ServeContent(w, r, a.name, a.modTime, bytes.NewReader(a.data))
}

func main() {
    // 示例文件路径可替换为项目自己的静态资源路径。
    doc, err := loadAsset("./assets/manual.pdf", "manual.pdf")
    if err != nil {
        log.Fatal(err)
    }
    http.Handle("/manual.pdf", doc)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

如果没有预先设置 Content-Type，ServeContent 会先看 name 的扩展名；仍无法判断时，会读取内容开头并使用 DetectContentType。因此应给 name 一个真实扩展名，而不是随手写成没有后缀的业务 ID。

范围请求：206、Content-Range 与 416

客户端发送 Range: bytes=0-99 时，ServeContent 会验证范围、移动读取位置并返回对应片段。有效范围通常得到 206；超出内容长度或语法无效的范围会进入错误响应，常见状态是 416。调用方不需要自己切片，也不应在调用前把内容 Reader 移到某个偏移量。

# 查看完整响应的状态与响应头。
curl -D - -o /dev/null http://127.0.0.1:8080/manual.pdf

# 只请求前 100 字节，预期观察 206 与 Content-Range。
curl -D - -o /dev/null -H 'Range: bytes=0-99' \
  http://127.0.0.1:8080/manual.pdf

ServeContent 需要通过 Seek 到末尾获得总大小，所以自定义内容源即使能顺序读取，也必须正确实现从起点、当前位置和末尾定位。普通 *os.File 已经满足 io.ReadSeeker，是大文件最直接的内容源。

缓存校验：Last-Modified 与 ETag 各管什么

modtime 负责时间校验。当它是有效时间时，标准库会写入 Last-Modified，并处理 If-Modified-Since。ETag 则适合表达资源版本，即使修改时间粒度相同，只要内容摘要不同，标签也能变化。ServeContent 不替你计算 ETag，但会使用调用前已经设置的标签处理 If-Match、If-None-Match 和 If-Range。

# 把响应中的真实 ETag 填到这里；命中时通常得到 304。
curl -D - -o /dev/null -H 'If-None-Match: "实际标签"' \
  http://127.0.0.1:8080/manual.pdf

# 条件范围命中时返回片段，校验值过期时回退为完整响应。
curl -D - -o /dev/null -H 'Range: bytes=0-99' \
  -H 'If-Range: "实际标签"' \
  http://127.0.0.1:8080/manual.pdf

范围请求与缓存校验如何协作

大文件与生产环境的边界

内存版本适合体积可控、读取频繁的静态资源。对大视频或安装包，不要在每次请求里执行 os.ReadFile 和 SHA-256。更稳妥的做法是：每个请求打开一个独立的 *os.File，读取 Stat 获得修改时间，把发布版本号、对象存储版本或预计算摘要作为 ETag，最后把文件直接传给 ServeContent。请求结束时关闭文件，避免描述符泄漏。

还要注意错误响应头：官方文档说明，范围无效等错误发生时，默认会移除 Cache-Control、Content-Encoding、ETag 和 Last-Modified，防止错误页继承资源元数据。只有明确理解兼容性影响时，才考虑 GODEBUG=httpservecontentkeepheaders=1；它不应成为掩盖错误处理的默认配置。

上线前检查清单

• 每个请求拥有独立的 Seek 游标，或对共享对象做了正确同步。
• ETag 格式合法且带双引号，并在调用 ServeContent 前设置。
• modtime 来自真实资源版本；不可靠时宁可传零值。
• 下载文件名通过 Content-Disposition 设置，不依赖 name 参数。
• 反向代理没有删除 Range、If-Range、ETag 或 Last-Modified。
• 用完整请求、有效范围、无效范围、命中缓存和过期 If-Range 五组场景做验收。

相关问题

可以把 bytes.Buffer 直接传给 ServeContent 吗？

不可以，bytes.Buffer 没有实现 io.Seeker。内存字节应包装成 bytes.NewReader，字符串可以使用 strings.NewReader。

ServeContent 会自动生成 ETag 吗？

不会。调用方要根据内容摘要、发布版本或稳定的资源版本生成标签，并在调用前写入响应头。

为什么 If-Range 不匹配时返回完整内容？

因为客户端持有的旧片段可能来自另一个资源版本。回退到 200 完整响应可以避免把新旧字节拼成损坏文件。