Go zip.NewReader 为什么必须同时提供文件大小

调用 Go 标准库的 zip.NewReader 读取非文件型 ZIP 时，第二个参数不是“本次准备读取多少字节”，而是整个 ZIP 数据源的总长度。第一个参数 io.ReaderAt 负责按绝对偏移读取，size int64 负责告诉解析器文件末尾在哪里；两者缺一不可。

正确的调用关系是：把能按偏移读取的对象作为 io.ReaderAt，把同一个 ZIP 数据源的完整字节数作为 size。文件用 Stat().Size()，内存字节用 bytes.Reader.Len()，不要传已经读过的长度或中央目录的长度。

官方文档：https://pkg.go.dev/archive/zip#NewReader

本文只解释 ReaderAt、size 与 ZIP 中央目录定位的接口关系，不展开 ZIP 解压安全策略。先把这个契约弄清楚，很多“NewReader 解析失败”的问题就能在输入层解决。

NewReader 的两个参数分别负责什么

函数签名是 zip.NewReader(r io.ReaderAt, size int64)。它要求的不是普通 io.Reader，而是可以从指定偏移读取一段数据的 io.ReaderAt。ZIP 读取器需要访问文件头、目录项和文件尾的不同位置，因此不能只依赖“从当前位置继续读”的顺序接口。

size 也不是一个可选的提示值。它代表 r 所指向的整个 ZIP 数据源长度，单位是字节。解析器据此把搜索范围限定在数据源末尾附近，再找到 ZIP 末尾的结束记录，然后得到中央目录的偏移和大小。

为什么解析器需要整个 ZIP 的 size

ZIP 的中央目录通常位于归档尾部，目录项记录了文件名、压缩方法、压缩大小以及本地文件头偏移。读取器拿到完整长度后，可以从末尾范围查找结束记录，再根据记录中的目录偏移读取所有目录项。

这也是 size 不能随意填写的原因：如果长度比真实 ZIP 小，文件尾会被截断，结束记录可能根本不在搜索范围内；如果长度比真实 ZIP 大，读取器会把不存在的尾部也当成数据源范围，最终可能得到格式错误或意外的 EOF。它不是为了计算“要解压多少”，而是为了建立可寻址的归档边界。

从接口角度看，ReaderAt 解决“能不能从某个偏移取数据”，size 解决“哪些偏移属于这个 ZIP”。把两者看成同一个数据源的两部分元数据，就不会把 size 误写成当前缓冲区长度。

文件来源怎么传入完整大小

如果 ZIP 已经落在本地文件中，*os.File 同时满足随机读取需求。打开文件后调用 Stat()，把文件信息中的 Size() 作为第二个参数；不要用一次 Read 返回的字节数代替它。

package main

import (
    "archive/zip"
    "fmt"
    "os"
)

func openZipFile(path string) (*zip.Reader, *os.File, error) {
    // 打开文件后保留文件句柄，让 ReaderAt 在后续按偏移读取原始 ZIP。
    f, err := os.Open(path)
    if err != nil {
        return nil, nil, fmt.Errorf("打开 ZIP 失败: %w", err)
    }

    // Stat().Size() 表示整个 ZIP 文件长度，而不是当前读取位置。
    info, err := f.Stat()
    if err != nil {
        f.Close() // 获取元数据失败时及时释放文件句柄。
        return nil, nil, fmt.Errorf("获取 ZIP 大小失败: %w", err)
    }

    zr, err := zip.NewReader(f, info.Size())
    if err != nil {
        f.Close() // NewReader 失败时没有可交给调用方的资源。
        return nil, nil, fmt.Errorf("解析 ZIP 失败: %w", err)
    }
    return zr, f, nil // 调用方读取完成后负责关闭 f。
}

func main() {
    // 示例只展示参数关系；真实程序应按业务处理目录项和错误。
    zr, f, err := openZipFile("assets/archive.zip")
    if err != nil {
        panic(err)
    }
    defer f.Close() // Reader 使用的底层文件直到遍历结束再关闭。
    fmt.Println("文件数量:", len(zr.File))
}

这个模式下，f 不能在 NewReader 返回后马上关闭，因为 zip.Reader 保存了底层 ReaderAt，后续调用文件的 Open 仍然需要读取原始数据。可以把文件句柄和读取器一起交给上层，在遍历完成后再释放。

内存字节怎么传入完整大小

如果 ZIP 来自 HTTP 响应、对象存储下载结果或数据库字段，先把完整字节放进切片，再用 bytes.NewReader 创建随机读取源。*bytes.Reader 实现了 io.ReaderAt，它的 Len() 可以提供尚未消费的长度；在一个刚创建、尚未移动读取位置的 reader 上，这个值就是整个 ZIP 的长度。

package main

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

func readZipBytes(data []byte) (*zip.Reader, error) {
    // data 必须包含完整 ZIP；不要只传正文片段或已截断的响应体。
    source := bytes.NewReader(data)

    // Len() 给出这个内存读取源的剩余字节数，此处等于完整 ZIP 长度。
    zr, err := zip.NewReader(source, int64(source.Len()))
    if err != nil {
        return nil, fmt.Errorf("解析内存 ZIP 失败: %w", err)
    }
    return zr, nil
}

func main() {
    // 真实项目可把完整 HTTP 响应体或文件内容传入 readZipBytes。
    data := []byte{/* 省略完整 ZIP 二进制 */}
    zr, err := readZipBytes(data)
    if err != nil {
        panic(err)
    }
    fmt.Println("文件数量:", len(zr.File))
}

如果先对同一个 bytes.Reader 调用了 Read，再用它的 Len()，得到的是“当前位置之后的剩余长度”，不一定是原始切片总长。最稳妥的做法是使用刚创建的 reader，并在创建时保存完整长度；或者直接使用 int64(len(data)) 表达原始切片长度。

哪些 size 写法容易出错

下面几种写法表面上都传入了一个整数，但语义与 NewReader 的契约不一致：

• 传单次读取返回值：n 只说明这次读到了多少字节，不能说明整个 ZIP 有多大。
• 传剩余长度：对已经移动过位置的 bytes.Reader 调用 Len()，可能把 ZIP 的前半段排除在外。
• 传中央目录大小：中央目录只是归档的一部分，NewReader 还需要根据目录项回到各个本地文件头和数据区域。
• 传上层缓冲区容量：cap(data) 是分配容量，不是有效 ZIP 字节数；应使用有效长度 len(data)。
• 传业务截断后的长度：如果下载或读取过程只保留了前 N 字节，必须先修复数据完整性，不能靠调整 size 把截断内容变成有效 ZIP。

排查时可以先问三个问题：ReaderAt 是否指向整个归档？size 是否对应同一份数据？创建 reader 前是否已经消费过数据？只要其中一项答案是否定的，就先修正输入边界。

错误症状和排查顺序

如果 zip.NewReader 返回格式错误或意外 EOF，不要先从解压算法入手。可以按照“数据是否完整—长度是否一致—来源是否支持随机读取”的顺序排查：

1. 确认字节源确实包含完整 ZIP，而不是只拿到了 HTTP 响应的一段。
2. 确认 size 与这个字节源对应：文件用实际文件大小，内存用有效切片长度。
3. 确认实现的是 io.ReaderAt，并且偏移从这份 ZIP 的起点计算。
4. 确认文件在遍历完成前没有被关闭，内存切片也没有被修改或复用。

这些检查只针对接口契约和数据边界。即使 NewReader 成功，后续读取文件内容时仍可能遇到压缩算法、校验和或具体条目数据问题；那是另一个阶段，不要与“size 传错导致无法定位中央目录”混为一谈。

常见问题

为什么不能只传 io.Reader？ 因为 ZIP 读取需要从不同绝对偏移读取数据，io.Reader 只有顺序读取语义，不能满足 ReaderAt 契约。

size 可以写成 ZIP 的解压后大小吗？ 不可以。它描述的是原始 ZIP 数据源的字节长度，不是某个条目的解压大小，也不是所有条目解压后的总和。

用 bytes.NewReader(data) 时应该传什么？ 如果 reader 尚未读取过，传 int64(len(data)) 或 int64(source.Len()) 都能表达完整数据长度；关键是不要在消费后把剩余长度误当作原始长度。

文件句柄可以在 NewReader 后关闭吗？ 不建议。读取器会在后续访问条目时继续使用底层 ReaderAt，应等遍历和内容读取结束后再关闭。