Go compress/gzip 如何流式压缩 HTTP 响应

在 Go 的 HTTP 服务里，想把大响应“边生成边压缩”，关键不是把 gzip.NewWriter 套上去就结束，而是处理好三件事：第一次写入前设置响应头；每个数据块写入后先刷新 gzip 缓冲，再刷新 HTTP writer；循环结束时检查 Close，因为它还负责写 GZIP footer。下面的写法适合日志导出、长列表和分块 JSON 等场景。

先把 gzip 响应的职责分开

压缩流和 HTTP 响应是两层 writer。业务字节先进入 gzip.Writer，压缩后的字节再进入 http.ResponseWriter。因此一次“刷新”也有两层含义：gzip.Flush 只保证待压缩数据写到底层 writer；HTTP 的 Flush 才是要求响应实现把已经写出的数据向客户端推进。

客户端没有在 Accept-Encoding 中声明 gzip 时，不要强行返回压缩内容。启用压缩后，Content-Encoding 应为 gzip，并设置 Vary: Accept-Encoding，避免缓存把压缩版本错误地给不支持压缩的请求。因为响应长度会随着数据生成才确定，通常要删除预设的 Content-Length。

最小可用写法：写入、刷新、关闭都留出错误出口

下面示例用固定间隔模拟持续产生的数据。它是操作示意代码，不代表图中的输出已在本机运行；真实项目可以把循环体换成数据库游标、日志读取器或分页查询。

package main

import (
    "compress/gzip"
    "fmt"
    "log"
    "net/http"
    "strings"
    "time"
)

func gzipStream(w http.ResponseWriter, r *http.Request) {
    // 先确认客户端能力，避免把 gzip 数据发给不会解压的客户端。
    if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
        http.Error(w, "client does not accept gzip", http.StatusNotAcceptable)
        return
    }

    // 第一次 Write/WriteHeader 之前设置所有会影响缓存和解码的头。
    w.Header().Set("Content-Encoding", "gzip")
    w.Header().Add("Vary", "Accept-Encoding")
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.Header().Del("Content-Length")

    gz := gzip.NewWriter(w)
    defer func() {
        // Close 会写入尚未落盘的数据和 GZIP footer，错误不能静默丢弃。
        if err := gz.Close(); err != nil {
            log.Printf("close gzip response: %v", err)
        }
    }()

    flusher, canFlush := w.(http.Flusher)
    for i := 1; i 

这里没有对 http.Flusher.Flush 返回错误，是因为该接口的方法本身没有返回值；真正可见的压缩层错误来自 Write 和 gzip.Flush。如果底层响应 writer 不支持 Flusher，代码仍能完成响应，只是不能保证每一块立刻向客户端可见。

为什么只调用一个 Flush 仍然感觉“不流式”

只调用 http.Flusher.Flush 不够：如果 gzip writer 还把业务数据留在自己的缓冲区，底层 HTTP writer 根本没有新字节可推。反过来只调用 gz.Flush，也只是把压缩结果交给 HTTP 层，网络服务器或代理仍可能继续缓冲。所以顺序不能反过来。

还要接受一个现实：Go 文档提醒，即使响应实现支持 Flusher，客户端前面若有 HTTP 代理，数据也可能直到响应结束才到达。测试时可以观察客户端是否分块收到内容，但不能把“服务端调用过 Flush”当成端到端实时性的保证。

Close、压缩等级和接口包装的常见坑

不要把 Close 当成关闭 ResponseWriter。 gzip.Writer.Close 会刷新压缩数据并写 footer，但不会关闭底层 io.Writer。它通常只调用一次，且应在循环正常结束和提前返回时都能执行。

不要在首个写入后再改头。 Write 可能隐式发送 200 状态和响应头；压缩头、Vary 和内容类型都应提前设置。若中途已经写出响应，再尝试改成 JSON 错误码也不会可靠生效。

压缩等级按瓶颈选择。 需要更低 CPU 延迟时可以使用 gzip.NewWriterLevel 和 gzip.BestSpeed；更高压缩率会增加 CPU 消耗，不应脱离响应大小、带宽和 CPU 指标盲选。等级参数非法时该函数会返回错误。

包装 ResponseWriter 时保留所需接口。 如果中间件返回一个只实现 Write 的新类型，上层 handler 可能再也断言不到 http.Flusher。除了 Flusher，某些服务还会依赖 Hijacker、Pusher 或 ReaderFrom；应按实际框架契约补齐或使用成熟的响应 writer 包装策略。

上线前用四项检查确认边界

1. 用支持和不支持 gzip 的两类请求分别检查响应头与正文是否可解压，不要只看状态码。
2. 让响应分成多个明显间隔的数据块，分别记录 Write、Flush 和 Close 的错误。
3. 在直连和经过反向代理的环境各测一次，把代理缓冲策略纳入时延判断。
4. 用真实响应大小比较压缩节省的带宽与 CPU、内存开销；小响应或已压缩格式未必值得再压缩。

常见问题

gzip.Flush 会不会写出完整的 GZIP 文件？

不会。它推出待压缩数据，但完整收尾和 footer 由 Close 完成；因此两者不能互相替代。

ResponseWriter 一定实现 http.Flusher 吗？

不一定。标准 HTTP/1.x 和 HTTP/2 实现通常支持，但包装器可能不支持，代码应通过类型断言判断。

已经设置 Content-Encoding，还需要 Vary 吗？

需要。只要响应是否压缩取决于请求头，就应让缓存按 Accept-Encoding 区分版本。