Go archive/zip.Reader 怎样保留错误信息

Go archive/zip.Reader 的错误要按发生阶段添加上下文，并用 %w 保留原始原因。初始化成功只代表可以访问归档目录；条目 Open 成功也不代表内容读取成功。读取返回的错误、条目 Close 的错误都应处理，调用方再通过 errors.Is 识别 zip.ErrFormat、zip.ErrAlgorithm 或 zip.ErrChecksum。

官方地址：https://pkg.go.dev/archive/zip

能力解决什么：把“ZIP读取失败”拆成可定位的信息

假设一个内存上传检查函数只返回“文件损坏”，调用方无法知道是中央目录不能解析，还是某个条目的内容读取失败。保留错误信息的目标是同时回答：哪个阶段、哪个条目、底层是什么原因。它不要求把完整归档或用户内容写入日志。

下面以只读的内存归档检查为例，不解压落盘。示例展示错误处理写法，不附实际执行日志。

支持范围：Reader、条目流和底层资源各自负责什么

zip.NewReader 接受 ReaderAt 与归档字节数，返回 *zip.Reader。Reader 本身没有 Close；打开条目得到的读取流要关闭。如果改为 zip.OpenReader，返回的是管理底层文件的 *zip.ReadCloser，归档文件和条目流的关闭职责都要安排。

初始化、打开条目、读取内容并不是同一个失败点。ZIP 的校验和问题可能在读取内容到结尾时才出现；只检查 NewReader，或者只读一小段就 Close，不能据此声明内容完整。当前实现中的条目 Close 转交给解压流，不会替你把剩余数据全部读完。

最小示例：逐层包装并保留读取与关闭原因

下面的包函数可以接收调用方已经取得的字节切片。使用 errors.Join，需要 Go 1.20 或以上。示例设置输入、条目数和单条目读取量上限，遇到首个失败立即返回；这些常量只是示例策略，不代表适合所有服务的容量配置。

package zipcheck

import (
    "archive/zip"
    "bytes"
    "errors"
    "fmt"
    "io"
)

// Inspect 只读取内存归档，不把条目释放到文件系统。
func Inspect(data []byte) error {
    const maxInput = 8  maxInput {
        return fmt.Errorf("归档超过输入大小上限")
    }
    zr, err := zip.NewReader(bytes.NewReader(data), int64(len(data)))
    if err != nil {
        // 本例对所有初始化错误直接拒绝，包括 ErrInsecurePath。
        return fmt.Errorf("解析 ZIP: %w", err)
    }
    if len(zr.File) > 100 {
        return fmt.Errorf("归档条目数超过上限")
    }
    for index, entry := range zr.File {
        if entry.FileInfo().IsDir() {
            continue
        }
        if err := inspectEntry(entry); err != nil {
            // 同名条目也能通过序号区分；%q 避免名称中的换行伪造日志行。
            return fmt.Errorf("条目[%d] %q: %w", index, entry.Name, err)
        }
    }
    return nil
}

func inspectEntry(entry *zip.File) (err error) {
    rc, err := entry.Open()
    if err != nil {
        return fmt.Errorf("打开内容: %w", err)
    }
    defer func() {
        if closeErr := rc.Close(); closeErr != nil {
            err = errors.Join(err, fmt.Errorf("关闭内容: %w", closeErr))
        }
    }()
    const maxEntry = 1  maxEntry {
        return fmt.Errorf("内容超过单条目大小上限")
    }
    return nil
}

// IsChecksumFailure 演示调用方穿过业务包装识别校验和错误。
func IsChecksumFailure(err error) bool {
    return errors.Is(err, zip.ErrChecksum)
}

解析失败用“解析 ZIP”包装；条目失败带上索引与名称，再由内层补充“打开内容”“读取内容”或“关闭内容”。索引避免重复名称造成定位歧义。%w 保留错误关系，单纯的 %v 或 errors.New(err.Error()) 只保留文字，后续原因判断会失去依据。

每个条目的 defer 放在 inspectEntry 内，函数返回就关闭这一条，不把整批资源堆到外层循环结束。命名返回值 err 使关闭错误可以加入主错误；不能直接用关闭结果覆盖已有读取错误。errors.Join 会忽略 nil 原因，允许主操作失败和清理失败同时保留。

兼容处理：原因分类不应靠错误文本

以 errors.Is(err, zip.ErrChecksum) 判断原因，可以穿过包装和 Join 分支。错误树可能包含多个原因，一个错误满足某项分类不意味着不存在其他错误。若上层需要分别处理读取和关闭详情，可以再定义含明确字段的业务错误类型。

NewReader 在特定名称条件与 GODEBUG=zipinsecurepath=0 下，可能同时返回 Reader 和 ErrInsecurePath。本例选择对任何初始化错误拒绝，不使用这个 Reader。不要把“有非空 Reader”误当成“err 可忽略”；接受这类名称必须是明确的调用方政策。这个开关也不能代替应用自身的完整处理规则。

资源与边界：不要把保留原因写成完整验收承诺

LimitReader 提供的 EOF 可能只是限额边界，因此示例多读一个字节检测超限，超限就返回策略错误，不宣称完整读取或完整校验。未超限并读到条目结束时，才有机会接收到读取末尾产生的错误。CRC 本身也不证明文件来源可信。

该函数只检查逐条读取过程，遇到失败就停止，不收集所有条目的错误；它不保证应用层文件格式正确，不执行内容，不验证外部签名。输入长度检查也不约束调用方事先接收数据时的内存占用，网络接收层仍需自己限额。总 CPU、耗时和并发预算需要在实际服务中单独设计。

如果未来把 io.Discard 换成文件或网络写入器，io.Copy 返回的错误还可能来自目标写入。届时阶段说明应改成“传输条目内容”，或用更明确的读取、写入边界；不要继续把所有 Copy 错误都归因于 ZIP 内容。

常见问题

为什么 NewReader 成功后仍然报错？

内容读取有自己的失败点。目录可以解析，不代表每个压缩条目的数据都已被读取过。

Close 成功能替代完整读取吗？

不能。关闭释放读取资源，不等于把剩余内容读完；尤其不要依赖它补做末尾读取检查。

可否每次包装都把完整路径和文件内容放进错误？

通常不需要。记录阶段、受控归档标识、条目索引与必要名称即可；对外响应另外映射，避免暴露内部路径或上传内容。

官方依据：NewReader 与错误常量、条目读取与关闭实现、errors.Join。