Go HTTP 响应怎么启用 gzip 压缩

接口已经返回 200，但抓包时响应体还是原始 JSON，最常见的原因不是 compress/gzip 不能用于 HTTP，而是压缩协商和响应头写入顺序出了问题。Go 的做法是：先看请求的 Accept-Encoding，确认客户端接受 gzip 后，用一个包装器接管 handler 的输出，在真正写出状态码和响应体之前设置 Content-Encoding: gzip，同时补上 Vary: Accept-Encoding。

一、先确认压缩协商和响应头时机

HTTP 压缩是内容协商，不是服务端单方面宣布“我压缩了”。客户端通常通过 Accept-Encoding: gzip 表示能力，服务端选中后返回 Content-Encoding: gzip。因为同一个 URL 可能同时返回压缩和未压缩两种表示，缓存还需要看到 Vary: Accept-Encoding，否则缓存可能把一种版本错误地复用给另一种请求。

顺序也很关键。net/http.ResponseWriter 在第一次 Write 时会隐式发送 200 和当前响应头；之后再改 Header 已经太晚。因此不要在 handler 写完一部分内容后才补 Content-Encoding。

二、用 gzip.Writer 包装 ResponseWriter

下面这个示例只压缩明确支持 gzip 的普通响应。包装器把 handler 的 Write 转给 gzip.Writer，但延迟到真正有响应体时才创建压缩 Writer，避免“只写状态码却产生一个空 gzip 响应”。

type gzipResponseWriter struct {
    http.ResponseWriter
    gz          *gzip.Writer
    status      int
    wroteHeader bool
    compressed  bool
}

func (w *gzipResponseWriter) WriteHeader(status int) {
    if w.wroteHeader {
        return
    }
    w.wroteHeader = true
    w.status = status

    // 这些响应没有可供普通 middleware 压缩的消息体。
    if status == http.StatusNoContent || status == http.StatusNotModified ||
        (status >= 100 && status 

中间件只在请求头包含 gzip 时使用这个包装器；否则直接交给原 handler。实际项目还应跳过已经有 Content-Encoding 的响应，并按业务排除图片、压缩包和已经压缩过的格式。

func Gzip(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        accepts := strings.Contains(strings.ToLower(r.Header.Get("Accept-Encoding")), "gzip")
        if r.Method == http.MethodHead || !accepts || w.Header().Get("Content-Encoding") != "" {
            next.ServeHTTP(w, r)
            return
        }

        gw := &gzipResponseWriter{ResponseWriter: w}
        defer gw.Close()
        next.ServeHTTP(gw, r)
    })
}

这个最小判断适合教程演示；生产代码若要严格遵循 q=0、通配符和多种编码的优先级，应使用完整的 Accept-Encoding 解析逻辑，而不是简单的字符串包含。

三、处理关闭、无响应体和流式响应

gzip.Writer.Write 写入的是压缩数据，但文档明确说明数据不一定立即刷到底层 Writer；Close 会刷新未写出的内容并写入 gzip 尾部。因此 defer gw.Close() 不是装饰代码。若 Close 返回错误，生产服务至少应记录它，因为这意味着响应可能被截断。

不要把所有响应都交给同一套压缩逻辑：HEAD 没有响应体，204 和 304 也没有普通消息体；文件下载如果已经是 zip、图片或视频，二次压缩通常只增加 CPU。流式输出则要额外转发 http.Flusher，并在合适的边界调用 gzip Writer 的 Flush，否则客户端可能长时间收不到中间数据。

四、用请求矩阵排查压缩不生效

排查时不要只看浏览器开发者工具里“大小变小没有”。先用一个明确带请求头的请求验证，再看四个字段：

curl -i -H 'Accept-Encoding: gzip' http://localhost:8080/api/items
curl -i http://localhost:8080/api/items

第一条请求应能看到 Content-Encoding: gzip；第二条没有能力声明时应返回普通内容。若两条结果完全一样，优先检查 middleware 是否真正包住了路由、handler 是否在包装前写过 Header，以及是否已经有上游代理负责压缩。若响应头正确但流式内容迟迟不到，再检查 Flusher 转发和刷新策略。

相关问题

为什么设置了 Content-Encoding 还是解压失败？

通常是响应体没有经过 gzip.Writer，或者中间件对已经压缩的内容又压了一次。抓取原始字节并确认 gzip 头、Content-Encoding 和实际 Writer 路径。

gzip 压缩等级应该怎么选？

默认等级适合先上线；如果 CPU 紧张可评估 gzip.NewWriterLevel 的速度优先等级，但要用真实响应体做 CPU、延迟和体积对比。

为什么缓存还要设置 Vary？

同一 URL 对不同客户端可能有压缩和未压缩两种表示。Vary: Accept-Encoding 告诉缓存按这个请求头区分对象，避免把 gzip 字节发给不支持的客户端。