Go io用 SectionReader 读取文件片段的范围方案

只想读取大文件中的一段内容时，先用 ReadAll 把整份文件装进内存并不划算。Go 的 io.NewSectionReader 可以把一个实现 io.ReaderAt 的对象包装成“有起点、有长度”的读取器：从 off 开始，最多读 n 个字节，读完后以 io.EOF 收尾。

实用的范围方案是把“文件绝对偏移”和“片段相对偏移”分开记录，再用 Size 与实际读取字节数双重核对。SectionReader 只限制读取范围，不负责关闭文件，也不会替底层对象提供并发保护。

先把文件范围表达成起点加长度

例如文件从字节 4096 开始的 8192 字节是一个独立数据块，那么 SectionReader 的参数应写成 off=4096、n=8192。结束位置 12288 只是计算结果，不应直接作为第三个参数。这个区分很关键：把结束位置误当成长度，会让读取器多读一段数据。

建议在业务边界先统一使用半开区间 [start, end)，创建读取器时再计算 length=end-start。若来自 HTTP Range、分片索引或文件头，先检查 start >= 0 且 end >= start，不要让无效范围进入 I/O 层。

用 ReaderAt 创建只覆盖目标区间的读取器

SectionReader 的底层参数是 io.ReaderAt，因此普通只实现 Read 的流不能直接传入。文件对象、bytes.Reader 等类型可以作为底层输入。创建后，包装器的当前位置从片段相对偏移 0 开始，外部不需要手动先把文件游标移到 off。

package main

import (
    "bytes"
    "fmt"
    "io"
)

func main() {
    source := bytes.NewReader([]byte("header|payload-2026|footer"))
    // off 是底层数据的绝对起点，n 是要暴露的字节长度。
    section := io.NewSectionReader(source, 7, 12)

    buf := make([]byte, section.Size())
    // Read 从片段相对位置 0 开始，成功时返回实际字节数。
    count, err := section.Read(buf)
    if err != nil && err != io.EOF {
        panic(err)
    }
    fmt.Printf("%q (%d bytes)\n", buf[:count], count)
}

上例中真正暴露的是 payload-2026 这一段。Size() 返回 12，表示片段的逻辑长度；它不是底层数据当前剩余长度，也不会因为已经读过一部分而改变。

按读取方式选择 Read、ReadAt 或 Copy

连续消费片段时使用 Read 最自然；需要从片段内部某个位置读取固定字节时使用 ReadAt。注意 ReadAt(p, off) 的 off 是相对于片段起点的偏移，不是底层文件的绝对偏移。若想把片段写入另一个 io.Writer，可以直接把 SectionReader 交给 io.Copy，它会在片段结束时停止。

func readHeader(section *io.SectionReader) ([]byte, error) {
    header := make([]byte, 4)
    // 这里的 0 表示片段起点，不是原文件的绝对位置。
    n, err := section.ReadAt(header, 0)
    if err != nil && err != io.EOF {
        return nil, err
    }
    // 固定长度字段不足时，返回实际字节数，避免把残缺头部当成完整数据。
    if n != len(header) {
        return nil, io.ErrUnexpectedEOF
    }
    return header, nil
}

func copySection(dst io.Writer, section *io.SectionReader) error {
    // Copy 只消费片段，不会越过 SectionReader 的 n 字节边界。
    _, err := io.Copy(dst, section)
    return err
}

多个调用方需要独立位置时，可以为同一个底层 ReaderAt 创建多个 SectionReader，或者优先使用 ReadAt 这类不改变共享当前位置的接口。底层对象是否支持并发安全，仍要以它自己的文档为准，SectionReader 不会自动加锁。

用 Size、字节数和 EOF 验收读取范围

范围读取的门禁可以固定成三项：创建后检查 Size() 是否等于预期长度，消费后检查累计字节数，循环结束时只把 io.EOF 当成正常结束。若底层只剩更少数据，可能会先返回部分字节，再以 io.EOF 结束；这时“读取器完成”不等于“业务数据完整”，还必须与期望长度比较。

参数、并发和资源生命周期的失败处理

第一类常见错误是把业务的结束位置直接传给 n，第二类是把底层绝对偏移再次传给 ReadAt，第三类是把 EOF 当成异常日志。可以在入口构造一个小的范围函数，统一检查 start、end 和溢出风险，再把合法范围交给 SectionReader。

第二个边界是并发。ReadAt 更适合多个协程读取不同片段；若多个协程共享同一个 SectionReader 并调用 Read 或 Seek，当前位置会形成共享状态，不能想当然地认为安全。第三个边界是关闭：SectionReader 没有 Close 方法，使用 os.File 时仍由创建文件的代码负责 Close。

在日志或指标里记录 start、length、实际字节数和错误分类，就能区分“请求范围错了”“文件内容不足”和“底层读取失败”。这样通知回路指向的是可修复的边界，而不是笼统地提示读取失败。

常见问题

SectionReader 的第三个参数是结束位置吗？

不是。它是从 off 开始允许读取的字节数；使用结束位置时应先计算 end-off。

ReadAt 的偏移为什么和文件偏移对不上？

因为 SectionReader 把片段起点重置为相对位置 0。要读底层绝对位置 absolute，应传入 absolute-off。

读到 EOF 是否一定代表失败？

不一定。达到 SectionReader 的限定长度时，EOF 是正常收尾；只有实际字节数不足业务预期时，才应升级为截断或数据不完整。

收尾检查

把范围写成 [start,end)，创建时传入 off=start 与 n=end-start；固定偏移读取用 ReadAt，顺序复制用 Read 或 io.Copy；最后用 Size()、实际字节数和错误值完成验收。掌握这三层边界，SectionReader 就能成为轻量而可控的文件分片读取工具。