Go io.SectionReader 怎么把大文件的一段导出成独立 Reader

做大文件下载、分段校验或归档切片时，最容易踩的坑是先用 io.ReadAll 把整个文件读进内存，再从字节切片里取一段。更合适的做法是把底层文件作为 io.ReaderAt，交给 io.NewSectionReader 创建一个固定范围的只读视图。这个视图可以继续作为普通 io.Reader 使用，导出时只读取指定区间。

直接结论：io.NewSectionReader(r, off, n) 表示从底层输入的 off 字节开始，最多暴露 n 个字节。它不会把整段内容预先复制到内存，也不会改变底层文件的共享游标。对于文件分段导出，通常用 os.File、范围起点和范围长度创建它，再用 io.Copy 写入响应或目标文件。

官方文档：https://pkg.go.dev/io#SectionReader

先把底层输入和区间参数对齐

SectionReader 依赖的是 io.ReaderAt，而不是只有顺序读取能力的 io.Reader。*os.File 实现了这个接口，因此打开一个文件后可以直接创建范围视图。三个参数的含义分别是底层输入、绝对起点 off 和允许读取的最大字节数 n。

这里的区间可以理解为半开范围 [off, off+n)。下游只看见这段范围，不需要知道原文件剩余内容。偏移和长度应在进入文件层前做非负检查；如果它们来自 HTTP Range、命令行或数据库，不能直接信任外部输入。

用 NewSectionReader 创建独立的范围视图

创建动作本身很轻量，它保存底层 ReaderAt、范围起点、长度和当前读取位置。下面的函数把文件区间包装成一个可顺序读取的 *io.SectionReader，同时把文件句柄的关闭责任留在函数调用方之外。

package main

import (
    "fmt"
    "io"
    "os"
)

func openSection(path string, off, length int64) (*os.File, *io.SectionReader, error) {
    // 偏移和长度来自外部时，先拒绝负数，避免把错误参数带进文件读取层。
    if off 

这个函数返回文件句柄和范围 Reader，是为了让调用方明确调用 file.Close()。关闭的是底层文件，不是 SectionReader；后者没有关闭方法。实际工程中，如果打开成功后的后续步骤失败，也要在返回前关闭文件。

用 io.Copy 把这一段导出到目标流

范围 Reader 实现了 io.Reader，因此可以接入 io.Copy、压缩器、哈希计算器或 HTTP 响应写入器。复制过程会在 SectionReader 的范围末尾看到 EOF，不会继续读后面的文件内容。

func exportRange(srcPath string, dst io.Writer, off, length int64) (int64, error) {
    file, section, err := openSection(srcPath, off, length)
    if err != nil {
        return 0, err
    }
    defer func() {
        // 文件关闭错误不能覆盖 Copy 的主错误；生产代码可按需记录它。
        _ = file.Close()
    }()

    // Copy 只消费 section 视图，成功时返回实际写出的字节数和 nil。
    written, err := io.Copy(dst, section)
    if err != nil {
        return written, fmt.Errorf("copy section: %w", err)
    }
    return written, nil
}

如果底层文件至少有 off+length 个字节，正常复制的数量就是 length。如果文件在范围结束前就结束，复制会提前完成，数量小于声明长度；是否把它视为错误，应由下载协议、分片校验或业务层决定，而不是把所有 EOF 都当成异常。

读到边界时会发生什么

SectionReader 有自己的相对坐标。对它调用 Read 时，当前位置从区间的 0 开始；当累计读取到 Size() 字节后，继续读取就会得到 EOF。这个 EOF 是范围边界，不代表一定读到了原文件的物理末尾。

例如原文件从绝对偏移 4096 开始建立长度为 8192 的视图，那么 SectionReader 的相对位置 0 对应原文件 4096；相对位置 100 对应原文件 4196。下游无需自己重复做绝对偏移换算。

func readPiece(section *io.SectionReader) ([]byte, error) {
    // ReadAt 的 off 是 SectionReader 视图内的相对偏移，不是原文件偏移。
    buf := make([]byte, 16)
    n, err := section.ReadAt(buf, 100)
    if err != nil && err != io.EOF {
        return nil, fmt.Errorf("read section at relative offset: %w", err)
    }

    // n 可能小于缓冲区长度；只返回实际读到的字节，避免带出零值尾巴。
    return buf[:n], nil
}

ReadAt 不依赖 SectionReader 当前的顺序读取位置，适合读取范围内的固定小块。Seek 则会改变下一次 Read 的相对位置；Size 返回创建时声明的长度。需要注意，Size 是视图长度，不是底层文件当前实际剩余长度。

声明长度和实际文件长度不一致时要留意

NewSectionReader 接收的是“最多读取多少字节”，并不会替你把底层文件扩展到这个长度。如果 off+length 超过文件实际大小，读取会在底层 EOF 处提前结束。对于分片下载，通常应把“实际写出数量小于期望长度”记录成不完整分片，再决定是否重试。

func copyExactRange(srcPath string, dst io.Writer, off, length int64) error {
    file, section, err := openSection(srcPath, off, length)
    if err != nil {
        return err
    }
    defer func() {
        // 这里仍由调用方负责释放底层文件句柄。
        _ = file.Close()
    }()

    written, err := io.Copy(dst, section)
    if err != nil {
        return fmt.Errorf("copy section: %w", err)
    }
    if written != length {
        // 业务要求完整分片时，把提前结束转换成可识别的错误。
        return fmt.Errorf("short section: want %d bytes, got %d", length, written)
    }
    return nil
}

是否要求精确长度要看场景。读取日志尾部、尽力返回可用数据时，短读可能是正常结果；做分片校验、固定格式文件切片或断点续传时，短读往往意味着源文件被截断或范围参数失效。

把范围 Reader 接入下载和校验流程

一个实用的分层方式是：文件层只负责打开和创建范围 Reader，传输层决定响应长度，校验层决定是否对这段数据计算摘要。这样同一段范围可以被多个下游消费，而不需要先复制成一个巨大的 []byte。

func streamAndHash(srcPath string, dst io.Writer, off, length int64, sum io.Writer) (int64, error) {
    file, section, err := openSection(srcPath, off, length)
    if err != nil {
        return 0, err
    }
    defer func() {
        // 无论复制成功还是失败，都要释放文件描述符。
        _ = file.Close()
    }()

    // MultiWriter 同时把范围数据送到输出流和摘要计算器。
    written, err := io.Copy(io.MultiWriter(dst, sum), section)
    if err != nil {
        return written, fmt.Errorf("stream and hash section: %w", err)
    }
    return written, nil
}

这里的重点不是把 SectionReader 当成新的文件，而是把它当成一个遵守 Reader 契约的有限视图。HTTP 层如果需要设置 Content-Length，可以使用预期的长度或实际文件大小计算结果；校验层则应该根据实际写出字节数确认分片是否完整。

几个容易混淆的问题

SectionReader 会复制选中的内容吗？

不会。它保存底层 ReaderAt 和范围信息，读取发生在调用 Read、ReadAt 或复制函数时。

为什么不能把普通 io.Reader 传给 NewSectionReader？

因为它需要按绝对偏移读取。只有顺序 Reader 无法在不消费前面内容的情况下定位到指定区间，io.ReaderAt 才提供了这个能力。

ReadAt 的偏移是原文件偏移吗？

不是。对 SectionReader 调用 ReadAt 时，偏移是范围视图内的相对偏移；底层起点由创建时的 off 自动加上。

文件提前 EOF 一定是程序错误吗？

不一定。SectionReader 的长度是上限，源文件短于该上限时提前 EOF 是符合读取语义的。是否报错取决于业务是否要求完整分片。

把大文件的一段导出成独立 Reader 时，可以记住一条主线：用实现 io.ReaderAt 的输入建立 io.NewSectionReader，用 io.Copy 或其他 Reader 消费它，再用 Size 和实际写出字节数处理边界。这样范围定义、顺序读取、随机读取和完整性判断各自有清楚的责任，代码也不会因为一次 ReadAll 把内存峰值推高。