Go ServeContent 怎样处理范围请求

如果接口只是把文件复制到 http.ResponseWriter，普通下载看起来没有问题，但播放器拖动进度条、下载器断点续传时就可能始终得到整份内容。这个问题的关键不是手动解析 Range，而是把可定位的数据源交给 http.ServeContent。

ServeContent 会根据请求头处理范围与条件请求，必要时返回 206 Partial Content、Content-Range 和正确的长度；它的前提是传入对象实现可工作的 io.ReadSeeker。本文只围绕这个前提复盘一遍常见故障。

一、先看症状：为什么请求带了 Range 仍然返回 200

一次典型的范围请求大致是：

Range: bytes=100-399

如果服务端响应为 200 OK 且没有 Content-Range，通常说明处理器走了“从当前位置一直写到结尾”的普通复制路径，或者传给标准库的数据源无法正确定位。对断点下载而言，状态码、范围头和实际字节区间要一起看，不能只看响应体是否有内容。

这次排障可以拆成三个时间点：先确认请求确实带有 Range；再确认数据源能取得总长度；最后确认它能回到开头并跳到指定偏移。任何一步缺失，范围处理就会退化或直接返回错误。

二、最小修复：用 os.File 直接接入 ServeContent

磁盘文件是最省事的数据源，因为 *os.File 已经实现了 io.ReadSeeker。文件打开成功后，把文件名、修改时间和文件对象交给 ServeContent，不要提前把文件读进一个只会顺序输出的包装器。

package main

import (
    "log"
    "net/http"
    "os"
)

func fileHandler(w http.ResponseWriter, r *http.Request) {
    file, err := os.Open("./assets/demo.mp4")
    if err != nil {
        // 文件不存在时直接返回 404，避免把内部错误暴露给客户端。
        http.NotFound(w, r)
        return
    }
    defer file.Close()

    info, err := file.Stat()
    if err != nil {
        // Stat 失败时无法可靠判断长度，不能继续伪装成文件下载。
        http.Error(w, "无法读取文件信息", http.StatusInternalServerError)
        return
    }

    // ServeContent 会利用 file 的 Seek 处理 Range 和条件请求。
    http.ServeContent(w, r, info.Name(), info.ModTime(), file)
}

func main() {
    http.HandleFunc("/media", fileHandler)
    log.Fatal(http.ListenAndServe(":8080", nil))
}

这里的 name 主要用于推断 Content-Type，modtime 用于 Last-Modified 和条件请求；它们不是 Range 的替代品。真正决定范围能力的是最后一个参数能否正确执行 Seek。

三、根因定位：ServeContent 为什么一定要 Seek

ServeContent 需要知道完整内容长度，才能判断 bytes=start-end 是否越界，并生成 Content-Range: bytes start-end/total。标准库实现会先把数据源定位到末尾取得大小，然后恢复到开头；确定范围后，再定位到对应起点读取。

因此，只实现 Read 的流不适合作为直接输入。例如一个实时网络流可能只能向前读，无法回答“总长度是多少”或“请回到第 100 字节”。把它强行传入后，问题不是 Range 头写错，而是数据源的能力不满足接口契约。

package main

import (
    "bytes"
    "net/http"
    "time"
)

func memoryHandler(w http.ResponseWriter, r *http.Request) {
    data := []byte("这是可以随机定位的内存内容。")

    // bytes.Reader 同时实现 Reader、Seeker，适合演示小型内存资源。
    reader := bytes.NewReader(data)
    http.ServeContent(w, r, "demo.txt", time.Time{}, reader)
}

这个示例的重点是对象类型，而不是把大文件全部放进内存。大文件仍应优先使用文件、支持随机读取的对象，或一个真正实现 Read 与 Seek 语义的适配器。

四、自定义数据源和条件请求要怎么处理

如果内容来自对象存储、数据库或自定义归档格式，先判断底层是否支持按偏移读取。仅仅给包装类型加一个形式上的 Seek 方法还不够：它必须更新位置，正确处理 io.SeekStart、io.SeekCurrent、io.SeekEnd，并在越界时返回清晰错误。

package main

import (
    "errors"
    "io"
)

type rangedSource struct {
    // 实际项目中这里应连接到支持偏移读取的底层存储。
    data []byte
    pos  int64
}

func (s *rangedSource) Read(p []byte) (int, error) {
    if s.pos >= int64(len(s.data)) {
        return 0, io.EOF
    }
    n := copy(p, s.data[s.pos:])
    s.pos += int64(n)
    return n, nil
}

func (s *rangedSource) Seek(offset int64, whence int) (int64, error) {
    // 先把三种定位方式统一成绝对位置，再检查边界。
    var base int64
    switch whence {
    case io.SeekStart:
        base = 0
    case io.SeekCurrent:
        base = s.pos
    case io.SeekEnd:
        base = int64(len(s.data))
    default:
        return 0, errors.New("不支持的定位方式")
    }
    next := base + offset
    if next  int64(len(s.data)) {
        return 0, errors.New("定位超出内容范围")
    }
    s.pos = next
    return s.pos, nil
}

完整代码还需要导入 errors 和 io。这个内存实现只用于说明契约；生产代码要把定位动作映射到真实存储，并考虑并发请求是否会共享可变位置。每个请求都应拥有独立的 Reader，不能让多个 Handler 共用同一个会移动游标的对象。

modtime 也不要随意填当前时间。若文件或对象有稳定的修改时间，可以传给 ServeContent，这样 If-Modified-Since、Last-Modified 等条件请求才有判断依据；没有可靠时间时传零值，重点先保证数据与范围一致。

五、按响应结果排查 200、206 和 416

排查时先记录请求的 Range、响应状态、Content-Length 和 Content-Range，再单独检查 Reader 的 Seek 调用。不要先通过手写响应头“修正”状态码，那会把长度、读取位置和缓存条件之间的不一致隐藏起来。

结论

Go 的 ServeContent 已经负责了范围请求、MIME 类型和多种条件请求的通用处理。文件场景直接传入 *os.File；内存场景可以使用 bytes.Reader；自定义后端则必须提供真实可用的 io.ReadSeeker，并为每次请求隔离游标。

相关问题

ServeContent 和 io.Copy 最大的区别是什么？

io.Copy 只负责顺序复制；ServeContent 还会根据请求头定位内容并构造范围与条件响应。

为什么自定义 Reader 不能只实现 Read？

因为 ServeContent 需要通过 Seek 获取总长度并定位到范围起点，只会顺序读取的流无法提供这个契约。

多个请求可以共用一个 os.File 吗？

更稳妥的做法是每个请求独立打开或独立构造 Reader，避免共享可移动位置带来的并发干扰；文件关闭也应绑定当前请求的生命周期。