zip Reader 在 HTTP Range 数据上的读取方式

我第一次把远程 ZIP 接到 Go 服务里时，直觉是把 http.Response.Body 传给 archive/zip。这条路走不通：zip.NewReader 要的是 io.ReaderAt，还要知道压缩包的完整字节数；HTTP 响应体通常只有从头到尾的顺序读取能力。

比较稳妥的做法是把支持 Range 的 HTTP 资源包装成一个按偏移读取的适配器。适配器每次收到 ReadAt(p, off)，就请求 bytes=off-end，再把响应交给 ZIP 读取器。这样不必先把整个远程文件下载到内存，但要接受它会产生多次区间请求。

远程 ZIP 能否按需读取，关键不在 zip.Reader 是否支持网络，而在远端是否稳定返回与请求区间匹配的 206 Partial Content、Content-Range 和总大小。普通的 200 OK 整体响应不能直接冒充随机读取。

先看清 zip.NewReader 的接口边界

zip.NewReader(r, size) 的两个参数缺一不可。第一个参数是 io.ReaderAt，表示读取者可以从任意偏移取得指定长度的字节；第二个参数是整个 ZIP 文件的大小，读取器需要据此定位尾部目录和中央目录。

这也是普通 HTTP Body 不适合直接传入的原因。Body 实现的是顺序 Read，它不知道怎样从偏移 800000 的位置重新读取，更不会自动把一次读取转换成 HTTP Range。io.NewSectionReader 可以限制一个已有 ReaderAt 的区间，但它不能把顺序网络流变成 ReaderAt。

因此，适配层至少要保存三类信息：HTTP 客户端和资源地址、远程资源总大小、把偏移与长度翻译成 Range 头的规则。若服务端、CDN 或代理会删除 Range 头，适配器应该尽早报错，而不是把完整响应中的错误位置交给 ZIP 解析器。

先用一次 Range 响应确认总大小

实践中可以请求 bytes=0-0，从响应的 Content-Range: bytes 0-0/总大小 里取得总大小。下面的代码只展示适配层核心，实际项目还应按自己的重试、超时和日志策略补齐。

package remotezip

import (
    "fmt"
    "io"
    "net/http"
    "strconv"
    "strings"
)

// remoteSize 用最小的 Range 请求确认服务器返回的完整资源大小。
func remoteSize(client *http.Client, url string) (int64, error) {
    req, err := http.NewRequest(http.MethodGet, url, nil)
    if err != nil {
        return 0, err
    }
    // 只取一个字节，避免为了探测大小下载整个 ZIP。
    req.Header.Set("Range", "bytes=0-0")

    resp, err := client.Do(req)
    if err != nil {
        return 0, err
    }
    defer resp.Body.Close()

    // 206 表示服务器确实按区间返回，而不是忽略 Range 后返回全文件。
    if resp.StatusCode != http.StatusPartialContent {
        return 0, fmt.Errorf("range size probe: unexpected status %s", resp.Status)
    }
    contentRange := resp.Header.Get("Content-Range")
    slash := strings.LastIndexByte(contentRange, '/')
    if slash 

这里只认明确的 206。有些服务器会在忽略 Range 时返回 200，这时虽然响应体可能看起来“有内容”，但它没有证明偏移请求成立。若确实只能拿到整文件，就应切换到本地临时文件或内存文件，再用文件实现的 ReaderAt，不要把 200 当作远程随机读取成功。

把 ReadAt 翻译成 HTTP Range

下面的适配器遵守 io.ReaderAt 的基本语义：正常情况下填满调用方给的缓冲区；到达文件尾部时允许返回部分数据和 io.EOF；负偏移直接报错。示例中每次调用只发一个区间请求，便于看懂边界。

type rangeReaderAt struct {
    client *http.Client
    url    string
    size   int64
}

// ReadAt 只负责一个区间，避免把远程资源错误地当成连续流。
func (r *rangeReaderAt) ReadAt(p []byte, off int64) (int, error) {
    if off = r.size {
        return 0, io.EOF
    }

    // 文件尾部可能不足一个完整缓冲区，按总大小收缩请求末端。
    want := int64(len(p))
    if remain := r.size - off; want > remain {
        want = remain
    }
    end := off + want - 1

    req, err := http.NewRequest(http.MethodGet, r.url, nil)
    if err != nil {
        return 0, err
    }
    // Range 是闭区间，所以结束位置必须减一。
    req.Header.Set("Range", fmt.Sprintf("bytes=%d-%d", off, end))

    resp, err := r.client.Do(req)
    if err != nil {
        return 0, err
    }
    defer resp.Body.Close()

    // 200 可能意味着代理或源站忽略了 Range，不能继续读取错误位置。
    if resp.StatusCode != http.StatusPartialContent {
        return 0, fmt.Errorf("read range %d-%d: unexpected status %s", off, end, resp.Status)
    }

    n, err := io.ReadFull(resp.Body, p[:int(want)])
    if err != nil {
        // ReadFull 的部分结果仍然要返回，让调用方能区分 EOF 与传输错误。
        return n, err
    }
    if want 

生产实现还可以解析并比对 Content-Range 的起止位置，防止缓存层返回与请求不相符的区间。也可以在适配器内做有限缓存，把 ZIP 读取器对同一小段的重复读取合并掉；缓存大小要和并发量、对象大小一起评估，不能因为想减少请求就无边界地把远程 ZIP 整体放进内存。

把适配器交给 ZIP Reader

取得总大小并构造 rangeReaderAt 后，调用关系很直接。zip.NewReader 会根据总大小寻找归档目录，返回的 Reader.File 列表可以继续按名称打开成员。

func openRemoteZip(url string) (*zip.Reader, error) {
    client := &http.Client{Timeout: 20 * time.Second}

    size, err := remoteSize(client, url)
    if err != nil {
        return nil, fmt.Errorf("discover remote ZIP size: %w", err)
    }

    source := &rangeReaderAt{
        client: client,
        url:    url,
        size:   size,
    }
    // NewReader 需要 ReaderAt 和完整大小，二者由同一个远程资源对应。
    reader, err := zip.NewReader(source, size)
    if err != nil {
        return nil, fmt.Errorf("open remote ZIP: %w", err)
    }
    return reader, nil
}

func readMember(reader *zip.Reader, name string) ([]byte, error) {
    for _, file := range reader.File {
        if file.Name != name {
            continue
        }
        body, err := file.Open()
        if err != nil {
            return nil, err
        }
        // ZIP 成员的读取器也必须关闭，避免解压过程留下资源。
        defer body.Close()
        return io.ReadAll(body)
    }
    return nil, fmt.Errorf("ZIP member %q not found", name)
}

上面的完整示例还需要在 import 中加入 archive/zip 和 time。这里把资源大小探测、随机读取和成员解压拆开，是为了让错误更容易定位：目录解析失败不一定是 ZIP 损坏，也可能是某次 Range 请求拿到了错误区间。

我会重点盯住这四类失败

另外，HTTP Range 只解决“怎样取得字节”，不解决 ZIP 内容本身的安全边界。读取成员后仍要限制解压输出大小，处理异常压缩比，并对成员名称做业务侧的路径约束。Go 文档也提醒，归档中出现非本地路径名时可能返回 ErrInsecurePath；不要因为远程读取成功，就跳过成员名和解压目标目录检查。

什么时候值得采用这种方案

如果远程 ZIP 很大、只需要读取少量成员，而且对象存储或源站稳定支持 Range，这种方案可以避免完整下载，适合索引包、按需读取归档配置和低频抽取场景。代价是请求次数、远端延迟和缓存一致性都进入了应用的故障面。

如果 ZIP 较小，或者同一请求会读取大部分成员，我通常会选择先下载到临时文件，再使用本地文件的 ReaderAt。代码更简单，失败重试也更清晰。我的判断标准不是“能不能把 Body 接上”，而是远程区间请求节省的传输量，是否值得承担额外的随机请求成本。

相关问题

HTTP Range 支持后就一定只下载需要的内容吗？

不一定。目录定位和成员解压都会触发读取，适配器还可能因为重复请求产生额外流量；是否节省取决于成员分布、压缩方式、缓存和实现的区间粒度。

可以把 RangeReaderAt 并发复用吗？

可以让多个 ReadAt 并发发请求，但要确认 HTTP 客户端、限流器和缓存实现的并发安全性。不要把可变的共享响应体或复用缓冲区直接暴露给并发调用。

为什么拿到完整 ZIP 后反而更容易处理？

落到临时文件后，文件本身已经提供稳定的随机读取和大小信息，ZIP 解析不再依赖网络状态。对于小文件或会读取大多数成员的业务，先落盘的额外步骤往往比远程随机读取更划算。

总结

zip.NewReader 和 HTTP Range 并不是直接兼容的两层 API：前者要 io.ReaderAt + size，后者提供的是带响应状态和区间语义的网络请求。用一个严格检查 206、Content-Range 和边界的 ReaderAt 适配层把两者连接起来，才能按需定位 ZIP 目录和成员。若源站不可靠、对象很小或读取面很大，落盘后再解析通常是更朴素的选择。