Go gzip Writer 怎样设置可追踪的文件头信息

Go 的 compress/gzip 会把压缩文件的部分元数据放进 gzip 文件头。要让归档带有可追踪的文件名、修改时间或简短备注，直接设置 gzip.Writer 的 Name、ModTime 和 Comment 即可。关键顺序是：这些字段必须在第一次调用 Write、Flush 或 Close 之前设置；一旦 Writer 开始输出，再修改字段不会改变已经写出的文件头。

官方文档：https://pkg.go.dev/compress/gzip

本文只围绕 Header 和写入时机展开，不讨论压缩级别，也不把 gzip 文件的具体字节布局当成应用契约。

先把可追踪信息放进 Header

gzip.Writer 内嵌了 Header，因此可以直接赋值。最常用的追踪信息是逻辑文件名和修改时间：前者帮助接收方知道压缩内容原本对应哪个文件，后者便于归档系统保留源文件时间。不要把服务器真实路径、访问令牌或其他秘密塞进 Name、Comment。

package main

import (
    "compress/gzip"
    "fmt"
    "io"
    "time"
)

// writeGZIP 把来源内容写成带有逻辑文件名和修改时间的 gzip 流。
func writeGZIP(dst io.Writer, name string, modified time.Time, src io.Reader) error {
    zw := gzip.NewWriter(dst)

    // Header 必须在首次 Write、Flush 或 Close 之前设置。
    zw.Name = name
    zw.ModTime = modified.UTC()
    zw.Comment = "归档元数据"

    // io.Copy 的目标是 gzip.Writer，数据会被压缩后写入 dst。
    if _, err := io.Copy(zw, src); err != nil {
        // 写入失败时仍尝试关闭，避免留下未释放的压缩状态。
        _ = zw.Close()
        return fmt.Errorf("写入gzip内容: %w", err)
    }
    // Close 会刷新剩余数据并写入 gzip 尾部，必须检查它的错误。
    if err := zw.Close(); err != nil {
        return fmt.Errorf("关闭gzip写入器: %w", err)
    }
    return nil
}

这个函数使用业务上的逻辑文件名，而不是本机绝对路径；调用方可以把原始文件的修改时间传入，再统一转成 UTC。Close 不会关闭底层的 io.Writer，因此底层文件或网络连接仍由调用方负责关闭。

为什么写入顺序比字段值更重要

官方文档把 Writer 的 Header 标记为“在第一次调用 Write、Flush 或 Close 时写出”。这意味着下面三种写法都可能提前提交文件头：先写一小段数据、先为了网络传输调用 Flush，或者什么都没写就直接 Close。

因此，创建 Writer 后应先完成所有 Header 赋值，再决定是否写内容。如果某个中间函数可能接收 Writer 并调用 Flush，就不要把 Header 设置放在这个函数之后。迁移旧代码时，可以把“创建 Writer、设置 Header”收拢到同一个小函数，减少隐式写出的机会。

// 反例与正确顺序：zw已经创建，dst是底层io.Writer。
// 错误：Write 已经可能写出 Header，之后再改 Name 没有追踪效果。
_, _ = zw.Write([]byte("first chunk"))
zw.Name = "report.txt"

// 正确：先集中设置元数据，再执行任何输出动作。
zw.Name = "report.txt"
zw.ModTime = sourceTime.UTC()
if _, err := zw.Write(data); err != nil {
    // 生产代码应把写入错误传回调用方，并按边界关闭 zw。
    return err
}

这里的“没有追踪效果”指新赋值不会回写已经输出的文件头；它不代表程序一定会立即收到错误。测试和审查时应关注调用顺序，而不是只检查字段最终在内存中的值。

几个 Header 字段分别解决什么问题

Header 暴露的字段不止文件名和时间。可以把它们当作压缩成员的少量描述信息，但不要把它们当成完整的业务索引。

字符串字段必须是 UTF-8，并且受 GZIP 格式允许的 Unicode 范围限制。若文件名可能来自用户输入，先做路径脱敏和字符策略，再写入 Header；不要因为 Header 可读就把它当作可信输入。

复用 Writer 时要重新设置元数据

Writer.Reset 可以让 Writer 改为向新的底层 io.Writer 写入，适合批量生成多个 gzip 成员。但复用的重点不是“只换一个输出缓冲区”，而是把下一份归档的 Header 当成一组新的输入重新设置。

// 每个成员都要在首次输出前设置自己的Header。
zw := gzip.NewWriter(&buf)
for _, item := range items {
    buf.Reset()
    zw.Reset(&buf)

    // Reset 后按当前成员覆盖上一份元数据。
    zw.Name = item.Name
    zw.ModTime = item.ModTime.UTC()
    zw.Comment = "批量归档"

    if _, err := zw.Write(item.Body); err != nil {
        return err
    }
    if err := zw.Close(); err != nil {
        return err
    }
    // 这里再读取或复制buf中的完整gzip成员。
}

不要在循环开始前只设置一次 Name，否则后面的成员可能继续携带上一项的文件名。每次 Reset 后都重新写入完整的元数据集合，并把 Close 的错误作为当前成员的失败结果处理。

怎样读回 Header 确认追踪契约

读取端通过 gzip.NewReader 得到 Reader 后，可以从它的 Header 读取 Name、ModTime 和 Comment。这让归档处理器可以先拿到逻辑文件名，再决定如何命名解压结果。若需要让 gzip 校验完整生效，应持续读取到 io.EOF，最后再关闭 Reader。

package main

import (
    "compress/gzip"
    "fmt"
    "io"
)

// inspectGZIP 读取文件头并消费正文，返回可用于归档索引的元数据。
func inspectGZIP(src io.Reader) (gzip.Header, error) {
    zr, err := gzip.NewReader(src)
    if err != nil {
        return gzip.Header{}, fmt.Errorf("打开gzip流: %w", err)
    }
    defer zr.Close()

    // 先复制到丢弃目标，直到EOF，避免只读Header而跳过正文校验。
    if _, err := io.Copy(io.Discard, zr); err != nil {
        return gzip.Header{}, fmt.Errorf("读取gzip正文: %w", err)
    }
    return zr.Header, nil
}

返回的 Header 适合做展示或索引字段，但不要只凭 Name 决定文件系统路径：解压前仍要做路径规范化、覆盖策略和权限控制。对于多成员 gzip 流，读取器还存在连续成员的语义；如果业务必须区分每个成员，应在设计中明确读取边界，而不是把所有 Name 拼成一个文件名。

迁移清单：把 Header 设置集中起来

• 创建 gzip.Writer 后，先设置 Name、ModTime 和必要的 Comment。
• 确认设置动作发生在第一次 Write、Flush 或 Close 之前。
• 用逻辑文件名替代绝对路径，不把令牌、密码和长日志写入 Header。
• 每次复用 Reset 后重新覆盖完整元数据，并检查 Close 错误。
• 读取端通过 Reader.Header 建立索引，但解压到磁盘前仍要独立处理路径和权限。

常见问题

可以在 Write 之后修改 Name 吗？

不应这样做。Header 可能已经在第一次 Write 时写出，后续字段赋值不会修改已经发送到下游的文件头。

Flush 会不会影响 Header 设置？

会。Flush 也属于可能触发 Header 写出的调用，因此网络流场景应先设置元数据，再 Flush。

ModTime 应该使用哪个时间？

通常使用源内容的修改时间，并在写入前确定时区策略。不要把压缩任务开始时间和源文件修改时间混为一谈。

Header 能不能存业务追踪 ID？

只有在双方明确约定并接受暴露风险时才考虑。更稳妥的做法是把追踪 ID 放在外部索引或受控的归档清单中，Header 只放必要的非敏感描述。

归档可追踪性的关键不在于设置很多字段，而在于把 Header 视为一次性写出的输入：先准备好逻辑文件名和时间，再让 Writer 输出内容，最后检查 Close。这样生成和读取两端的契约都更清晰。