当前位置：首页 > 文章列表 > Golang > Go教程 > Go compress/gzip 如何流式压缩 HTTP 响应

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

来源：17golang原创 2026-09-12 18:52:34 0浏览收藏

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

要点速览

gzip.Writer.Write 可能暂存压缩数据，单纯 Write 不代表客户端已经收到这一块。
流式发送的顺序是 gzip.Flush() → http.Flusher.Flush()，后者还要做运行时能力判断。
Close() 不能只放在没有返回值的 defer 里；至少要把错误记录下来，并区分客户端断开和服务端压缩失败。

先把 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，代码仍能完成响应，只是不能保证每一块立刻向客户端可见。

Go compress/gzip 流式 HTTP 响应中 Write、gzip Flush 与 HTTP Flusher Flush 的关系示意 — 图1：Go gzip 流式响应的写入与双层 Flush 操作示意图。

阶段	调用	需要观察的结果
请求协商	`Accept-Encoding`	不支持 gzip 时走普通响应
压缩写入	`gz.Write`	错误可能表示客户端断开或底层写失败
块边界	`gz.Flush` + `flusher.Flush`	压缩数据已推出，HTTP 实现允许时继续推进
正常结束	`gz.Close`	写出 footer，并报告收尾错误

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

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

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

Go gzip 流式响应中 gzip Flush、HTTP Flush、代理缓冲和 Close 写入 GZIP footer 的边界示意 — 图2：gzip.Flush、HTTP Flush、代理缓冲与 Close 收尾边界的结果示意图。

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 包装策略。