Go compress/gzip Writer 写入错误的传播与清理方案

Go 的 gzip.Writer 写入失败时，不能只判断某一次 Write。压缩器会缓存数据，底层 io.Writer 的错误可能在写入过程中出现，也可能在 Close 刷新剩余数据和 GZIP 尾部时才暴露。稳妥做法是：记录写入错误，仍然调用一次 Close 收口状态，最后只要任一环节失败就丢弃这份输出。

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

关键结论：gzip.Writer 不会替你关闭底层 Writer；写入失败后的压缩字节也不能当作完整文件交付。生产代码应把压缩输出写到临时目标，只有 Write 和 Close 都成功才提交。

先分开接收 Write 与 Close 的错误

gzip.NewWriter 接受的是一个由调用方管理的 io.Writer。它只负责把压缩字节写进去，不负责关闭文件、网络连接或对象存储上传器。更容易漏掉的是：Write 返回成功，只能说明输入已被压缩器接收，不能保证所有压缩字节已经到达底层。

可以把两个错误分别包装，再按优先级返回。即使中间写入已经失败，也执行一次 Close；但最终输出必须标记为失败。

func compressTo(dst io.Writer, src io.Reader) error {
	// gzip.Writer 不拥有 dst；调用方继续负责底层资源的关闭。
	zw := gzip.NewWriter(dst)
	_, writeErr := io.Copy(zw, src)

	// Close 会刷新缓存并写入 GZIP 尾部，即使 writeErr 非空也要收口。
	closeErr := zw.Close()
	if writeErr != nil {
		return fmt.Errorf("写入压缩流失败: %w", writeErr)
	}
	if closeErr != nil {
		return fmt.Errorf("关闭压缩流失败: %w", closeErr)
	}
	return nil
}

这里的顺序有两个含义：第一，保留更早出现的写入错误，避免后续收口错误遮蔽根因；第二，不能把 Close 写进无条件忽略错误的 defer。若 src 读取失败，也应把结果视为未完成，不向下游返回这份压缩内容。

写入失败后仍要收口，但不要复用半成品

当底层 Writer 返回磁盘满、连接断开或自定义限流错误时，gzip.Writer 内部状态已经不能代表一份完整 GZIP 文件。此时调用 Close 的目的，是结束压缩器生命周期；它不是“修复”此前输出的动作。

如果底层是网络流，失败后通常应停止继续发送，并由上层关闭连接；如果底层是文件，则删除临时文件。不要在错误发生后继续调用 Write，也不要把同一个失败的 Writer 直接交给下一个任务。需要复用对象时，必须确认上一轮已收口，再调用 Reset 指向新的、可写的目标。

文件落盘采用临时目标和原子提交

直接覆盖正式文件会留下最难排查的状态：文件名存在，但内容只写到一半。更可靠的做法是同目录创建临时文件，压缩成功后关闭它，再把临时文件重命名为正式名称。重命名失败也要删除临时文件。

func writeGzipFile(name string, src io.Reader) (err error) {
	// 临时文件和正式文件放在同一目录，便于使用同文件系统的重命名。
	tmp, err := os.CreateTemp(filepath.Dir(name), ".gzip-*")
	if err != nil {
		return err
	}
	tmpName := tmp.Name()
	defer func() {
		// 失败路径清理半成品；成功重命名后该路径已不存在。
		if err != nil {
			_ = os.Remove(tmpName)
		}
	}()

	zw := gzip.NewWriter(tmp)
	if _, err = io.Copy(zw, src); err != nil {
		_ = zw.Close()
		return fmt.Errorf("压缩输入失败: %w", err)
	}
	if err = zw.Close(); err != nil {
		return fmt.Errorf("写入 GZIP 尾部失败: %w", err)
	}
	if err = tmp.Close(); err != nil {
		return fmt.Errorf("关闭临时文件失败: %w", err)
	}
	return os.Rename(tmpName, name)
}

这个示例把“压缩器关闭”和“底层文件关闭”拆开检查。gzip.Writer.Close 不会关闭 tmp，所以两次关闭都不能省略；只有最后的重命名成功，调用方才应把正式文件当成新版本。

用失败 Writer 覆盖真正的排障路径

测试时不要只使用 bytes.Buffer，因为它几乎不会模拟底层失败。可以准备一个达到字节上限后返回固定错误的 Writer，检查压缩函数是否返回错误、是否调用了 Close，以及临时文件是否被清理。

常见问题

只检查 io.Copy 的返回值够吗？

不够。压缩数据可能仍在缓存中，Close 才会刷新缓存并写尾部；两个返回值都要检查。

gzip.Writer.Close 会关闭 os.File 吗？

不会。它只关闭并收口压缩 Writer，底层文件仍由调用方关闭。

写入失败后还能继续使用同一个 Writer 吗？

不要继续写当前输出。完成清理后，只有在明确调用 Reset 并切换到新的目标时，才考虑复用对象。