compress/gzip Reader.Multistream 怎样控制拼接 gzip 成员的读取

处理 gzip 文件时，最容易被忽略的一点是：一个输入不一定只有一个 gzip 成员。日志轮转、归档拼接或网络封装都可能把多个完整的 gzip 数据流首尾相连。Go 的 compress/gzip.Reader 默认会继续读取后续成员；如果你的格式需要把每个成员当成独立记录，就要显式调用 Multistream(false)。

需要把拼接的 gzip 内容合并解压时，保持默认设置即可；需要在第一个成员结束处停下来时，调用 Multistream(false)，并让底层 Reader 实现 io.ByteReader，之后用 Reset 逐个处理后续成员。

官方地址：https://pkg.go.dev/compress/gzip#Reader.Multistream

先确认 gzip 输入的边界

gzip 格式允许多个成员连续出现，每个成员都有自己的头部、压缩数据和尾部。默认的 gzip.NewReader 会把这些成员的解压结果拼成一个连续的 io.Reader，调用方通常只需要持续读取，直到得到整体的 io.EOF。

这和“一个文件只有一个压缩块”的假设不同。若代码只关心最终文本、日志或归档内容，默认模式最省事；若输入协议把每个 gzip 成员当作独立消息，默认模式会把边界吞掉，此时才需要关闭多成员行为。

默认模式：把多个成员读成一段连续数据

默认值相当于开启多成员读取。下面的代码适合“所有成员都属于同一份逻辑内容”的场景，例如拼接后的压缩日志或连续归档。示例只展示 API 关系，未把命令行或运行结果冒充成截图。

package main

import (
    "compress/gzip"
    "io"
    "log"
    "os"
)

func readAllMembers(src io.Reader) error {
    // NewReader 默认允许读取串联的多个 gzip 成员。
    zr, err := gzip.NewReader(src)
    if err != nil {
        return err
    }
    // Close 不会关闭 src；读取到 EOF 后再关闭，才能完成校验语义。
    defer zr.Close()

    // Copy 会持续读取，直到所有成员的解压内容都结束。
    _, err = io.Copy(os.Stdout, zr)
    if err != nil {
        return err
    }
    return nil
}

func main() {
    if err := readAllMembers(os.Stdin); err != nil {
        log.Fatal(err)
    }
}

这里的关键不是 io.Copy 本身，而是 Reader 的多成员策略：第一个成员读完后，gzip Reader 会检查后面是否还有新的 gzip 头，并把后续成员继续暴露为同一个解压流。只有收到整体 EOF，调用方才知道输入全部结束。

单成员模式：在当前 gzip 成员处停下

当上层协议需要逐个处理成员时，创建 Reader 后立即调用 Multistream(false)。此时读到当前成员末尾会返回 io.EOF，但底层 Reader 应实现 io.ByteReader，这样 gzip Reader 才能把位置准确留在当前成员之后，而不是因为预读而越过边界。

package main

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

func readMembers(src io.Reader) error {
    zr, err := gzip.NewReader(src)
    if err != nil {
        return err
    }
    defer zr.Close()

    for index := 1; ; index++ {
        // 关闭多成员后，本次 Reader 只负责当前 gzip 成员。
        zr.Multistream(false)

        fmt.Printf("member %d:\n", index)
        if _, err := io.Copy(os.Stdout, zr); err != nil {
            return err
        }
        fmt.Println()

        // Reset 复用 Reader；EOF 表示没有下一个成员，而不是当前成员读取失败。
        err := zr.Reset(src)
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }
    }
}

func main() {
    if err := readMembers(os.Stdin); err != nil {
        log.Fatal(err)
    }
}

这段循环有两个容易写错的边界。第一，io.Copy 返回的 EOF 已经被 Copy 消费掉了，所以“还有没有下一个成员”的判断放在 Reset 上。第二，Reset 返回 EOF 表示底层输入没有下一段 gzip 成员；其它错误则应按损坏头部、校验失败或底层读取失败处理。

为什么必须关注 io.ByteReader

gzip.NewReader 接受的是 io.Reader，但在关闭多成员后想精确停在成员边界，底层对象还需要提供单字节读取能力。原因是普通 Reader 可能一次读进超过当前 gzip 成员的数据；如果这些数据已经被内部缓冲，调用方就无法把它们无损地交还给下一个解析阶段。

文件对象通常具备足够的定位能力，但自定义网络 Reader、带缓冲包装器或消息队列适配器要特别注意接口组合。不能只看到 Read 可用，就默认关闭多成员后一定能安全解析下一段。若协议不要求成员级边界，保持默认模式反而更简单。

Close、EOF 和校验错误怎么分工

Reader.Close 不会关闭底层 Reader。更重要的是，gzip 的长度和校验信息在读到成员尾部时才有机会被核对。官方文档建议把收到 io.EOF 之前的已读数据视为暂定结果；如果数据提前结束或校验不匹配，读取阶段可能返回 gzip.ErrChecksum 等错误。

func copyOneMember(src io.Reader, dst io.Writer) error {
    zr, err := gzip.NewReader(src)
    if err != nil {
        return err
    }
    // 只关闭解压器，不替调用方关闭底层输入。
    defer zr.Close()
    zr.Multistream(false)

    // 只有 Copy 正常读完，当前成员的输出才可视为完整。
    if _, err := io.Copy(dst, zr); err != nil {
        return err
    }
    return nil
}

工程上可以按下面的表快速选择：

常见误区

• 把默认行为当成“只读一个 gzip 文件”，结果多个成员被无感合并。
• 调用 Multistream(false) 后仍使用不支持 io.ByteReader 的底层包装器，并期待下游从精确位置继续读。
• 只检查 Read 返回的数据，不把校验完成前的数据当作最终可靠结果。
• 把 Reset 返回的 io.EOF 当成损坏；它只说明没有下一个 gzip 成员。

总结

Reader.Multistream 解决的是“多个 gzip 成员是否属于同一个解压流”的边界问题。默认模式适合连续内容；false 模式适合成员级协议。逐个读取时，把 Multistream(false)、io.ByteReader、Reset 和 EOF 语义放在一起考虑，才能既不吞掉下一段输入，也不把完整性错误误判成正常结束。

相关问题

• gzip Reader 读到 EOF 前返回的数据可以直接落盘吗？
• Multistream(false) 关闭后为什么 Reset 会返回 EOF？
• gzip Reader.Close 会不会自动关闭底层文件？
• 普通 io.Reader 不支持 ByteReader 时，应该保持默认多成员模式吗？