Go compress/gzip 怎样根据客户端协商返回压缩响应

Go 服务端给 HTTP 响应加 gzip，真正容易出错的地方通常不在 gzip.NewWriter，而在“是否应该压缩”和“什么时候结束压缩流”。如果请求没有声明支持 gzip，就应该发送普通响应；如果请求声明支持，就要同时处理 Content-Encoding、Vary、响应头时机和 writer 的关闭顺序。

官方依据：https://pkg.go.dev/compress/gzip、https://pkg.go.dev/net/http

最小可靠做法是：先读取 Accept-Encoding 决定是否启用 gzip，在任何正文写入前设置响应头，正文写完后显式关闭 gzip.Writer，并让 Vary: Accept-Encoding 告诉缓存响应有两种表示。

先从“响应能打开但内容不对”开始定位

常见症状有三种：客户端没有声明 gzip 却收到压缩字节；响应头没有 Content-Encoding: gzip，客户端因此把压缩数据当成文本；代码调用了 Write 却没有关闭 gzip writer，尾部校验信息没有写完。它们看起来都像“压缩失败”，实际分别属于协商、头部和生命周期问题。

这里的边界也要先说清：本文只处理服务端响应协商，不讨论压缩级别压测、文件压缩或通用流式传输优化。静态结构图只表达代码实体之间的关系，不是浏览器或终端截图。

根据 Accept-Encoding 决定是否包裹 ResponseWriter

不要用“请求里出现 gzip 字符串”作为唯一判断。下面的示例把判断集中在一个小函数里；生产代码还可以继续补充质量值、通配符和已有编码的策略，但不要把未支持的编码误判成 gzip。

package main

import (
    "compress/gzip"
    "net/http"
    "strings"
)

// acceptsGzip 只判断请求是否明确声明支持 gzip，避免把普通文本误当成压缩响应。
func acceptsGzip(r *http.Request) bool {
    // 只取请求头语义，不根据 User-Agent 或 URL 猜测客户端能力。
    value := strings.ToLower(r.Header.Get("Accept-Encoding"))
    for _, item := range strings.Split(value, ",") {
        // 去掉质量参数；本例只演示最小的 gzip 协商边界。
        parts := strings.SplitN(strings.TrimSpace(item), ";", 2)
        if parts[0] == "gzip" {
            return len(parts) == 1 || !strings.Contains(parts[1], "q=0")
        }
    }
    return false
}

// handler 根据协商结果选择普通 writer 或 gzip writer。
func handler(w http.ResponseWriter, r *http.Request) {
    w.Header().Add("Vary", "Accept-Encoding")
    if !acceptsGzip(r) {
        // 不支持 gzip 时直接写普通响应，保持默认的 HTTP 语义。
        w.Write([]byte("plain response"))
        return
    }

    // 这些头必须在第一次写正文前设置，否则状态码和头部可能已经发送。
    w.Header().Set("Content-Encoding", "gzip")
    zw := gzip.NewWriter(w)
    defer zw.Close() // 关闭会写入 gzip 尾部；真实项目应记录 Close 错误。
    zw.Write([]byte("compressed response"))
}

图 1 只把请求头、处理器、gzip writer 和响应头放在同一张关系图中，重点是“协商结果决定是否包裹输出”，不是描述一次真实请求的执行截图。

响应头、正文写入和 Close 必须在同一生命周期内

gzip.Writer 写入的是压缩格式数据，Close 负责完成末尾信息并把缓冲内容交给底层 writer。只调用 Flush 不能替代最终关闭；而且 defer zw.Close() 适合简单处理器，若业务必须感知关闭错误，就应显式处理返回值。

func compressedHandler(w http.ResponseWriter, r *http.Request) {
    // 先声明缓存需要按 Accept-Encoding 区分响应版本。
    w.Header().Add("Vary", "Accept-Encoding")
    w.Header().Set("Content-Encoding", "gzip")

    zw := gzip.NewWriter(w)
    // 关闭顺序由外到内决定：先结束 gzip 数据，再让 HTTP 响应自然结束。
    if _, err := zw.Write([]byte("payload")); err != nil {
        http.Error(w, "write compressed body failed", http.StatusInternalServerError)
        return
    }
    if err := zw.Close(); err != nil {
        // 这里记录错误即可；响应头可能已经发出，不能再假装回写一个新状态码。
        return
    }
}

图 2 关注的是静态生命周期关系：响应头描述编码，gzip writer 承载压缩格式，底层 ResponseWriter 承载网络响应。三者不是可以随意互换的同类 writer。

四个容易被忽略的边界

还要避免重复压缩：如果上游已经设置了 Content-Encoding，当前处理器不要再次包裹；如果响应是很小的错误页，也可以按业务策略跳过压缩，但这属于策略选择，不是 gzip API 的必需步骤。

相关问题

为什么一定要设置 Vary？ 因为同一个 URL 可能根据 Accept-Encoding 返回普通版或 gzip 版，缓存需要知道这个请求头会影响响应表示。

能否只调用 Flush？ Flush 用于把当前缓冲内容推出去，不能代替 Close 完成 gzip 流的收尾。

压缩响应要不要自己设置 Content-Length？ 通常不要沿用原始正文长度；让 HTTP 层根据实际写入处理，除非你已经掌握压缩后的完整字节数并明确需要固定长度。

把 gzip 响应拆成“协商选择、头部声明、压缩生命周期、缓存区分”四个边界后，排查就不会只盯着 gzip.NewWriter。先确认客户端能力，再确认头部是否在正文前设置，最后确认压缩 writer 是否真正关闭。