Gin 默认不开启 Gzip 压缩是为避免与 Nginx 等反向代理重复压缩导致客户端解压失败；gzip 中间件必须在路由注册前全局挂载，且需排除已压缩资源、验证 magic bytes 和解压有效性，并推荐使用 BestSpeed 级别与 MinSize 阈值优化性能。
Gin 默认不开启 Gzip 压缩，不是忘了加，而是刻意不加——应用层压缩容易和 Nginx 等反向代理重复编码，导致 Content-Encoding: gzip 被套两层，客户端解压失败，返回空白或乱码。
为什么 gin-contrib/gzip 中间件要放在 r.Use() 里且必须在路由注册前
中间件挂载顺序决定执行时机。gzip.Gzip() 必须在 r.GET()、r.POST() 等路由注册之前调用，否则对这些路由的响应不会被拦截。它依赖 Gin 的 middleware chain，在 context.Next() 前后包裹写入逻辑；如果挂得太晚（比如在某个 group 里局部 Use），静态文件（gin.Static()）或健康检查接口就完全绕过压缩逻辑。
- 错误写法：
r.Static("/assets", "./public"); r.Use(gzip.Gzip(...))→/assets下所有文件不压缩 - 正确写法：
r.Use(gzip.Gzip(...)); r.Static("/assets", "./public) - 注意：
gin.StaticFS和gin.DataFromReader类响应也受此规则约束
如何避免对 PDF/ZIP/already-gzipped 响应重复压缩
gin-contrib/gzip 默认只按 MIME 类型白名单（如 text/*、application/json）过滤，不检查 Content-Encoding 头或文件扩展名。若上游已压缩（如 Nginx 返回了 Content-Encoding: gzip），或后端直接返回 .pdf 文件，中间件仍可能强行再压一次，导致体积变大甚至损坏。
- 显式排除路径：
gzip.WithExcludedPaths([]string{"/download/report.pdf", "/api/v1/export.zip"}) - 用正则排除动态路径：
gzip.WithExcludedPathsRegexp("^/files/.*\.(pdf|zip|jpg|jpeg|png)$") - 手动检查响应头：
if ctx.GetHeader("Content-Encoding") != "" { ctx.Next(); return }插入自定义前置逻辑
验证 Gzip 是否真生效：别只看响应头
很多中间件会错误地写入 Content-Encoding: gzip 头，但实际没压缩 body —— 客户端收到后尝试解压，结果是 unexpected end of file 或空响应。真正验证得看三件事：
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 响应头有
Content-Encoding: gzip且Vary: Accept-Encoding - 响应体二进制开头是
1f 8b（gzip magic bytes） - 用
curl -H "Accept-Encoding: gzip" -I http://localhost/xxx查看Content-Length显著小于未压缩时（例如 JSON 从 12KB → 3.2KB）
用 curl -H "Accept-Encoding: gzip" http://localhost/api/data | gunzip -t 直接测试解压是否成功，比肉眼检查更可靠。
生产环境推荐的压缩级别与阈值设置
默认 gzip.DefaultCompression（级别 6）在 CPU 和压缩率之间折中，但对 API 响应而言，gzip.BestSpeed（级别 1）更合适：JSON/YAML/HTML 等文本压缩率损失不到 5%，CPU 占用下降 60%+，延迟更稳定。
- 设最小压缩阈值：
gzip.Gzip(gzip.BestSpeed, gzip.MinSize(1024))→ 小于 1KB 的响应不压（避免 header 开销反超收益） - 禁用对 HEAD 请求压缩：
ctx.Request.Method == "HEAD"时跳过，因无 body 却加头会误导客户端 - 注意：
MinSize对 chunked 响应无效（无Content-Length），此时中间件靠首次Write()的字节数判断，所以别在 Write 前多次 Write 小块数据
最易被忽略的点：gzip.Writer 必须 Close 才写入 CRC 和 ISIZE 尾部；gin-contrib/gzip 内部已封装好，但如果你自己手写中间件，漏掉 w.Close() 就会导致客户端解压失败——现象是响应头正常，body 解不开，且 gunzip -t 报 “invalid compressed data”。
