gzip Multistream 读取拼接压缩流的边界

遇到“一个输入里拼了多个 gzip 文件，Go 却一次性读出了全部内容”的情况，通常不是 gzip.Reader 失控，而是它的默认行为就是支持 multistream。默认情况下，连续的 gzip 成员会被当成一条逻辑数据流，Reader 依次解压并拼接结果。只有需要识别每个成员的边界，或者 gzip 后面还跟着另一种格式时，才应该显式调用 Multistream(false)。

先确认默认 Reader 会不会跨成员继续读

gzip 文件可以由多个独立成员串接而成，每个成员都有自己的头部和尾部。Go 官方文档把这种输入视为连续的 gzip 数据流：默认 Multistream(true) 会继续寻找下一个成员，读完全部成员后才返回 io.EOF。

下面的示例先在内存中写入两个 gzip 成员，再用一个 Reader 读取。这里的重点是数据组织方式，不依赖第三方包。

package main

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

func appendMember(dst *bytes.Buffer, text string) {
	// 每次 Close 都写出一个完整的 gzip 成员尾部，随后才能安全追加下一个成员。
	zw := gzip.NewWriter(dst)
	if _, err := zw.Write([]byte(text)); err != nil {
		log.Fatal(err)
	}
	if err := zw.Close(); err != nil {
		log.Fatal(err)
	}
}

func main() {
	var input bytes.Buffer
	appendMember(&input, "第一段|")
	appendMember(&input, "第二段")

	zr, err := gzip.NewReader(&input)
	if err != nil {
		log.Fatal(err)
	}
	defer zr.Close()

	data, err := io.ReadAll(zr)
	if err != nil {
		log.Fatal(err)
	}
	// 默认 Multistream(true)，两个成员的解压结果被连续读出。
	fmt.Println(string(data))
}

这个结果适合“把分片压缩文件当成一个整体解压”的场景。成员边界不会自动暴露给调用方，io.ReadAll 得到的是两个成员的未压缩内容拼接结果。

完整读取到 EOF，校验结果才算确定

gzip 成员的尾部包含未压缩长度和校验信息。Reader.Read 返回的字节，在真正收到 io.EOF 前都应该视为暂定结果；如果长度或校验不匹配，Reader 可能在接近成员末尾时返回错误。只检查已经读到的字节数量，不能替代对 EOF 或错误的处理。

func readWhole(zr *gzip.Reader) ([]byte, error) {
	// ReadAll 会持续读取直到 EOF，因此能把 gzip 尾部校验纳入结果判断。
	data, err := io.ReadAll(zr)
	if err != nil {
		return nil, fmt.Errorf("读取 gzip 数据失败: %w", err)
	}
	return data, nil
}

如果只调用一次 Read，即使拿到了部分正文，也不能据此断定整个 gzip 成员已经正确结束。对于流式处理，可以在循环中持续读取，并把除 io.EOF 外的错误原样交给上层。

需要按成员处理时关闭 Multistream

当输入格式要求“一个 gzip 成员对应一份记录”，或者 gzip 成员之后还有未压缩的索引、协议帧或结束标记，就应在第一次创建 Reader 后调用 Multistream(false)。此时，Reader 到达当前成员末尾会返回 io.EOF，但底层 Reader 的位置仍需要满足边界定位要求。

package main

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

func readMembers(input *bytes.Buffer) error {
	zr, err := gzip.NewReader(input)
	if err != nil {
		return err
	}
	defer zr.Close()

	for index := 1; ; index++ {
		// 关闭多成员模式：一次只处理当前 gzip 成员。
		zr.Multistream(false)
		member, err := io.ReadAll(zr)
		if err != nil {
			return fmt.Errorf("第 %d 个成员读取失败: %w", index, err)
		}
		fmt.Printf("成员 %d: %s\n", index, member)

		// Reset 从底层 Reader 当前位置开始寻找下一个 gzip 成员。
		err = zr.Reset(input)
		if err == io.EOF {
			return nil
		}
		if err != nil {
			// 非 gzip 的尾随数据通常会落到 ErrHeader，而不是被吞掉。
			return fmt.Errorf("成员 %d 之后不是 gzip: %w", index, err)
		}
	}
}

func main() {
	var input bytes.Buffer
	appendMember(&input, "第一段")
	appendMember(&input, "第二段")
	if err := readMembers(&input); err != nil {
		log.Fatal(err)
	}
}

示例中的 bytes.Buffer 实现了 io.ByteReader，因此 gzip Reader 能在成员结束后停在合适的位置。对于文件、网络流等自定义 Reader，要注意 Go 文档对这一点的要求：关闭 multistream 后，底层 Reader 需要实现 io.ByteReader，才能可靠地定位到当前 gzip 成员之后。

尾随普通数据为什么会改变错误判断

“没有下一个 gzip 成员”和“后面有一段不是 gzip 的数据”不是同一件事。如果底层已经到真正的 EOF，下一次 Reset 可以得到 io.EOF；如果后面还有普通协议数据，Reset 尝试解析它时可能返回 gzip.ErrHeader。因此，混合格式的解析器不能把所有错误都当成“成员读取结束”。

func appendTail(input *bytes.Buffer) {
	appendMember(input, "压缩正文")
	// gzip 成员之后追加协议层尾巴，由上层格式自行解释。
	input.WriteString("TAIL")
}

func classifyNextMember(err error) string {
	switch {
	case err == nil:
		return "发现下一个 gzip 成员"
	case err == io.EOF:
		return "输入真正结束"
	case err == gzip.ErrHeader:
		return "后面是非 gzip 数据，交给上层协议"
	default:
		return "解析失败，需要保留错误"
	}
}

如果业务协议明确规定 gzip 后只能出现另一个 gzip 成员，那么 ErrHeader 应该是格式错误；如果协议允许尾随数据，则要把底层 Reader 交给上层继续解析，不能直接丢弃。

按场景选择三种读取策略

最终可以把判断压缩成一句话：默认模式解决“连续解压”，关闭 multistream 解决“边界管理”。不要为了读取单个成员而手动扫描 gzip 头部，也不要在还没读到 EOF 时把已得到的字节当成已经校验通过。

常见问题

gzip.Reader 默认会读取多个成员吗？ 会。默认 Multistream(true) 会把连续 gzip 成员的解压结果当成一条连续数据流。

Multistream(false) 会自动读取下一个成员吗？ 不会。当前成员读完后要调用 Reset，并继续处理返回值。

为什么 Reset 后不是 io.EOF？ 如果底层还有尾随普通数据，Reader 会尝试把它当作 gzip 头部解析，可能返回 gzip.ErrHeader；这代表格式边界需要交给上层处理。

Close 能代替读到 EOF 吗？ 不能。Reader 的 Close 不会替底层数据完成 gzip 校验，调用方仍应完整读取并处理最终错误。

技术依据：https://pkg.go.dev/compress/gzip