Go gzip Reset 后为什么需要重新设置 Header

这里说的是 gzip.Writer.Reset，不是 Reader.Reset。Writer 的 Reset 会丢弃当前流状态，并让对象回到“刚由 NewWriter 或 NewWriterLevel 创建”的等价状态，只是改为写向新的 io.Writer。因此上一条流的 Name、Comment、Extra、ModTime 等 Header 元数据不会被继承，新流必须重新设置。

• Reset 前：先 Close 旧流，确保压缩缓存和 gzip footer 已写完。
• Reset 后：重新设置本次流的全部 Header，再进行首次 Write、Flush 或 Close。
• 可复用内容：压缩器对象和压缩级别可以复用，但业务元数据属于每条独立流。

Reset 的能力边界：复用压缩器，不复用上一条流

gzip.Writer 既保存可复用的压缩器，也保存当前流的 Header、校验和、未压缩长度、错误与关闭状态。Reset 的目标是减少重复分配，而不是把上一条 gzip 流“续写”到新目标。

Go 官方实现会重新初始化整个 Writer：保留已有 compressor 并让它改写新目标，同时保留原压缩级别；其余字段回到新 Writer 状态，Header 只带默认 OS: 255。因此上一轮设置的 Name、Comment、Extra 和 ModTime 会消失，这是设计行为，不是 bug。

最小正确写法：Close 旧流，再 Reset 和配置

func writeNext(
    zw *gzip.Writer,
    dst io.Writer,
    name string,
    modTime time.Time,
    payload []byte,
) error {
    zw.Reset(dst) // 切换到新的底层输出，并清空上一条流状态

    // Reset 后为当前 gzip 流重新设置全部业务元数据。
    zw.Name = name
    zw.Comment = "generated export"
    zw.ModTime = modTime.UTC()
    zw.OS = 255

    if _, err := zw.Write(payload); err != nil {
        return fmt.Errorf("写入 gzip 正文: %w", err)
    }
    if err := zw.Close(); err != nil {
        return fmt.Errorf("完成 gzip 流: %w", err)
    }
    return nil
}

调用这个函数前，上一条流也必须已经 Close。Reset 本身不会替上一条流写 footer；如果压缩数据尚未结束就直接 Reset，旧输出会成为不完整的 gzip 流。相反，本轮 Close 完成后，底层 dst 仍由调用者负责关闭。

把 Header 配置做成每次必经的入口

复用场景最容易出现两类错误：一类是假设 Header 会保留，导致新文件名为空；另一类是只覆盖部分字段，误以为未覆盖字段仍来自上一轮。解决办法是让 Header 配置成为完整赋值，而不是零散修改。

type GzipMeta struct {
    Name    string
    Comment string
    Extra   []byte
    ModTime time.Time
}

func applyHeader(zw *gzip.Writer, meta GzipMeta) {
    // 对当前新流做完整赋值，不依赖上一轮残留状态。
    zw.Name = meta.Name
    zw.Comment = meta.Comment
    zw.Extra = append(zw.Extra[:0], meta.Extra...)
    zw.ModTime = meta.ModTime.UTC()
    zw.OS = 255
}

Extra 是字节切片。这里复制数据而不是直接长期引用调用方切片，可减少调用方后续修改底层数组带来的意外。Name 和 Comment 还受 gzip 格式的字符范围约束，不适合未经处理地保存任意 Unicode 文本。

对象池中怎样避免 Header 串用

如果用 sync.Pool 减少分配，池里只保存 Writer，不保存“已经配置好某客户 Header 的 Writer”。每次取出后都要 Reset，再应用当前任务的元数据；Close 后才能放回池。

var gzipPool = sync.Pool{
    New: func() any {
        // 初始目标只是占位，实际任务会先调用 Reset。
        return gzip.NewWriter(io.Discard)
    },
}

func encode(dst io.Writer, meta GzipMeta, payload []byte) error {
    zw := gzipPool.Get().(*gzip.Writer)
    defer gzipPool.Put(zw) // 函数结束后才归还，避免并发共享

    zw.Reset(dst)
    applyHeader(zw, meta)

    if _, err := zw.Write(payload); err != nil {
        return fmt.Errorf("压缩正文: %w", err)
    }
    if err := zw.Close(); err != nil {
        return fmt.Errorf("关闭 gzip writer: %w", err)
    }
    return nil
}

常见问题 1：Reset 会自动 Close 旧流吗？
不会。必须先 Close，确保旧流的压缩数据和 footer 完整写出，再 Reset 到新目标。

常见问题 2：为什么 OS 还是 255？
新 Writer 的默认 OS 值就是 255，表示未知。Reset 重新初始化 Header 后会回到这个默认值。

常见问题 3：Reset 后可以先 Write 再补 Header 吗？
不可以。Reset 后仍遵守同一规则：Header 必须在首次 Write、Flush 或 Close 前设置。

所以，Reset 的心智模型应当是“复用机器，开始一条全新的 gzip 流”。压缩能力可以复用，Header 属于本次流的协议数据，必须由本次任务重新提供。