Go Web 实现流式实时输出技巧

在 Go Web 开发中，实现真正的流式实时输出（如日志推送、进度更新或服务器事件）并非简单循环写入响应体即可，关键在于主动调用 `http.Flusher.Flush()` 打破 `ResponseWriter` 的默认缓冲机制——否则数据将滞留在服务端缓冲区，前端长时间无感知；本文深入剖析了如何通过类型断言获取 Flusher、正确设置响应头、处理代理与 HTTP/2 兼容性、监听请求上下文取消等实战要点，并给出即用型示例代码，帮你避开“看似运行却毫无输出”的常见陷阱，让每一行实时数据都稳稳抵达浏览器。

在 Go 中实现 HTTP 流式响应（如服务器发送事件或长连接日志推送）时，需主动调用 http.Flusher.Flush() 手动刷新缓冲区，否则 ResponseWriter 的默认缓冲机制会导致前端 HTML 无法及时接收数据。

在 Go 中实现 HTTP 流式响应（如服务器发送事件或长连接日志推送）时，需主动调用 `http.Flusher.Flush()` 手动刷新缓冲区，否则 `ResponseWriter` 的默认缓冲机制会导致前端 HTML 无法及时接收数据。

要让 Go Web 服务实现真正“实时”的流式响应（例如持续向浏览器输出日志、进度或状态更新），仅循环写入 http.ResponseWriter 是不够的——因为 Go 标准库的 ResponseWriter 默认基于 bufio.Writer，所有 fmt.Fprintln(w, ...) 等写操作均被缓冲，直到响应结束或缓冲区满才会实际发送到客户端。这导致前端页面长时间无响应，看似“卡住”。

✅ 正确做法是：每次写入后立即调用 Flush()，前提是底层 ResponseWriter 实现了 http.Flusher 接口（HTTP/1.1 连接下标准 ResponseWriter 默认支持，但需显式断言）。

以下是优化后的完整处理函数示例：

func handler(w http.ResponseWriter, r *http.Request) {
    if r.Method != "GET" {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }

    // 设置必要的响应头：禁用缓存 + 指定 Content-Type（如 text/event-stream 或 text/plain）
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")

    // 可选：发送初始空行，确保部分浏览器（如旧版 Safari）触发流式解析
    fmt.Fprint(w, "\n")
    if f, ok := w.(http.Flusher); ok {
        f.Flush()
    }

    ticker := time.NewTicker(1 * time.Second)
    defer ticker.Stop()

    for range ticker.C {
        fmt.Fprintln(w, "repeating... ", time.Now().Format("15:04:05"))

        // 关键：每次写入后必须 Flush！
        if f, ok := w.(http.Flusher); ok {
            f.Flush()
        } else {
            // 若 Flush 失败（如 HTTP/2 或某些代理环境），应记录并退出
            log.Println("Warning: ResponseWriter does not support http.Flusher")
            return
        }
    }
}

? 注意事项与最佳实践：

• ✅ 务必检查 w.(http.Flusher) 类型断言是否成功：在反向代理（如 Nginx）、HTTP/2 连接或某些中间件环境下，Flusher 可能不可用；未校验直接调用会 panic。
• ✅ 设置合适的响应头：Cache-Control: no-cache 和 Connection: keep-alive 是流式响应的基础保障；若用于 SSE（Server-Sent Events），还应设 Content-Type: text/event-stream 并遵循 data: 格式。
• ⚠️ 避免无限循环阻塞 goroutine：生产环境应结合 r.Context().Done() 监听请求取消，及时退出循环，防止资源泄漏。
• ? 前端需配合流式读取：HTML 页面建议使用 EventSource（SSE）或 fetch().body.getReader()（ReadableStream）接收分块响应，而非普通