Go HTTP Server 流式下载如何判断客户端断开

我第一次把大文件下载改成流式输出时，最容易漏掉的不是分块读取，而是用户点了取消以后，服务端还在继续读磁盘、查对象存储，甚至把后续数据继续搬进缓冲区。Go HTTP Server 判断这类客户端断开，首选不是猜某个底层网络错误，而是观察当前请求的 Context。

在 Handler 中监听 r.Context().Done()：客户端连接关闭或 HTTP/2 请求被取消时，上下文会结束；每次读写前后都检查它，并把同一个上下文传给可取消的下游操作。ResponseWriter.Write 返回的错误再作为补充信号。

官方依据：https://pkg.go.dev/net/http#Request.Context

先把流式下载做成一个小项目

这个示例只做一件事：从本地文件按 32 KB 读取并写给客户端。真实项目可以把 os.File 换成对象存储或压缩流，但取消处理的位置不变。这里使用的 Request.Context 是服务端请求上下文；官方文档说明，客户端连接关闭、HTTP/2 请求取消，或 Handler 返回时，它会被取消。

package main

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

func download(w http.ResponseWriter, r *http.Request) {
    f, err := os.Open("./assets/report.zip")
    if err != nil {
        http.Error(w, "文件不存在", http.StatusNotFound)
        return
    }
    defer f.Close() // 无论正常结束还是取消，都释放文件描述符。

    w.Header().Set("Content-Type", "application/zip")
    w.Header().Set("Content-Disposition", `attachment; filename="report.zip"`)

    buf := make([]byte, 32*1024)
    for {
        select {
        case  0 {
            if _, writeErr := w.Write(buf[:n]); writeErr != nil {
                log.Printf("download write stopped: %v", writeErr)
                return
            }
        }
        if errors.Is(readErr, io.EOF) {
            return
        }
        if readErr != nil {
            http.Error(w, "读取文件失败", http.StatusInternalServerError)
            return
        }
    }
}

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

这个 Handler 没有把“写入成功”误当成“客户端一直在线”。上下文检查负责发现取消，Write 错误负责捕捉已经暴露出来的发送失败，文件读取错误则是另一类服务端故障。

为什么要在循环里检查 Context

只在 Handler 开头检查一次没有意义：断开通常发生在下载进行到一半以后。把检查放在下一次读取前，可以避免继续从磁盘或上游取数据；把写入错误单独处理，则可以在底层写操作已经发现连接不可用时尽快退出。

不要把 CloseNotifier 当成新代码的默认方案。它确实提供过一个客户端连接离开的通知通道，但已经被标记为 deprecated；新的 Handler 应以请求上下文为主。

把取消继续传给远程数据源

如果下载内容来自另一个 HTTP 服务，仅让本地循环停止还不够。应使用 http.NewRequestWithContext，让上游请求也共享当前请求的取消信号。否则浏览器已经取消，服务端仍可能占着上游连接。

func proxyDownload(w http.ResponseWriter, r *http.Request) {
    req, err := http.NewRequestWithContext(
        r.Context(), http.MethodGet, "https://storage.example.test/report.zip", nil,
    )
    if err != nil {
        http.Error(w, "创建上游请求失败", http.StatusInternalServerError)
        return
    }

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        // 上下文取消时，错误应交给调用方判断，不要继续写响应。
        if r.Context().Err() != nil {
            return
        }
        http.Error(w, "上游下载失败", http.StatusBadGateway)
        return
    }
    defer resp.Body.Close() // 释放上游响应体，避免连接和资源泄漏。

    w.Header().Set("Content-Type", resp.Header.Get("Content-Type"))
    if _, err := io.Copy(w, resp.Body); err != nil {
        log.Printf("proxy stream stopped: %v", err)
    }
}

这里的重点不是强行把所有错误都记成“客户端断开”，而是先看 r.Context().Err()。如果它已经结束，说明请求生命周期先结束；如果上下文仍然正常，才需要继续区分上游网络故障或本地写入故障。

几个容易误判的边界

• Context 取消不是业务成功。它只说明请求生命周期结束，日志里应记录为 canceled，而不是下载完成。
• Write 没报错不代表客户端没断开。缓冲、代理和内核发送窗口都可能让错误稍后才暴露，所以不要只依赖一次写入结果。
• 任意 Reader 不一定会被 Context 打断。如果下游读取可能长时间阻塞，要选择支持 Context 的客户端或在数据源层实现取消。
• Handler 返回后不要再依赖请求 Context 做后台任务。需要脱离请求继续做的工作，应显式设计独立生命周期，而不是偷偷复用这个上下文。

对我来说，最稳妥的组合是“循环检查 Context + 处理 Write 错误 + 给上游请求传 Context”。三者解决的是不同层面的问题，合在一起才适合长时间流式下载。

相关问题

Q：还需要使用 http.CloseNotifier 吗？
新代码通常不需要，优先使用 r.Context().Done()。只有维护明确依赖旧接口的代码时，才评估兼容性。

Q：客户端断开后要给它返回 499 吗？
通常没有机会可靠地把新的状态码发给已断开的客户端。服务端应停止工作、释放资源，并在日志或指标中记录取消原因。