Go io.SectionReader 如何限制读取片段起止偏移

需要从一个大文件或字节流中只取中间一段时，io.NewSectionReader 比手动维护起始位置和剩余长度更直观。它把底层 io.ReaderAt 的数据包装成一个片段视图：off 是底层起点，n 是最多可读的字节数，实际范围可以理解为 [off, off+n)。

最小写法是 section := io.NewSectionReader(source, off, n)。之后用 Read 做顺序读取，用 ReadAt 做片段内随机读取，用 Size() 复核长度；不要把 ReadAt 的第二个参数误当成底层文件绝对偏移。

先把起点和长度写成一个片段

NewSectionReader 要求源对象实现 io.ReaderAt。内存里的 strings.Reader、打开后的 *os.File 都可以作为示例输入。下面的代码截取字符串的第 5 个字节开始、长度为 12 的区域，并转换成文本：

package main

import (
    "fmt"
    "io"
    "log"
    "strings"
)

func main() {
    source := strings.NewReader("header|payload-2026|tail")
    // off 是底层字节起点，n 是片段最多暴露的字节数。
    section := io.NewSectionReader(source, 7, 12)

    data, err := io.ReadAll(section)
    if err != nil {
        log.Fatal(err)
    }
    // 这里转换的是片段内容，不会把完整 source 一起读出。
    fmt.Printf("%q size=%d\n", string(data), section.Size())
}

这个范围对应从 off 开始的 12 个字节。Size() 返回的是片段定义长度，而不是本次调用已经读取的数量。对于固定格式的二进制头、归档中的单个成员或大文件的一段校验数据，这种表达比先读全部内容再切片更节省内存。

Read、ReadAt 和 Seek 的偏移口径不同

顺序读取时，Read 会推进 SectionReader 自己的游标。片段耗尽后，后续读取返回 io.EOF。随机读取时，ReadAt 的偏移从片段起点算，不会改变 Read 使用的游标：

// localOff 是片段内偏移，不是 source 的绝对偏移。
buf := make([]byte, 4)
n, err := section.ReadAt(buf, 3)
if err != nil && err != io.EOF {
    log.Fatal(err)
}
fmt.Printf("read=%d data=%q\n", n, buf[:n])

// Seek 也使用片段内坐标；SeekStart=0 表示 section 的开头。
pos, err := section.Seek(2, io.SeekStart)
if err != nil {
    log.Fatal(err)
}
fmt.Println("local position:", pos)

例如创建片段时使用 off=7，然后调用 ReadAt(buf, 3)，底层实际访问位置是 10。这样既能避免把文件头或下一段数据读进来，也能在同一个片段上并行安排多个只读范围；但底层 ReaderAt 是否适合并发仍要遵循其自身约束。

把片段复制出去时，先检查字节边界

如果目标是上传、哈希或写入另一个文件，可以直接把 SectionReader 当成普通 io.Reader 交给 io.Copy。复制量受 n 限制，调用方不需要额外再套一个同长度的 LimitReader。若目标是文本，要注意这里所有边界都按字节计算：UTF-8 字符可能被截断，不能把任意字节片段直接当成完整字符串。

var dst strings.Builder
// io.Copy 只消费 section 暴露的字节范围，返回实际复制字节数。
written, err := io.Copy(&dst, section)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("written=%d text=%q\n", written, dst.String())

对二进制格式，应以字段长度和协议边界计算 off、n；对文本，应先确认切分点落在字符边界，或者在完整字节片段读出后再用解码器处理。ReadAt 读到末尾只拿到部分数据时，业务代码应优先依据 n 判断数据是否完整，不能只看缓冲区剩余的旧内容。

用 Size 和 Outer 留下可复核的范围信息

调试分段读取时，建议把底层起点、片段长度和本地偏移一起记录。Size() 给出长度；Go 1.22 起，Outer() 可以取回创建 SectionReader 时传入的底层 ReaderAt、起点和长度，适合做日志或包装器的范围核对：

reader, base, length := section.Outer()
// reader 用于识别底层对象，base 和 length 用于复核原始范围。
fmt.Printf("reader=%T range=[%d,%d) size=%d\n", reader, base, base+length, section.Size())

实际排查时重点看三件事：base+length 是否溢出或超出业务允许范围，调用 ReadAt 时是否传入了错误的绝对偏移，以及 Read 前是否已经被同一个 SectionReader 的其他操作推进了游标。需要独立游标时，创建多个 SectionReader，或统一使用 ReadAt。

常见问题

NewSectionReader 的 n 是结束偏移吗？

不是。n 是长度，结束位置为 off+n，有效字节范围是左闭右开区间。

ReadAt 的偏移为什么不能直接传文件位置？

因为它以 SectionReader 的开头为零点。要表达底层绝对位置，需要先减去片段的 off。

SectionReader 会关闭底层文件吗？

不会。它只是 ReaderAt 的包装器，不负责关闭源文件；打开文件的代码仍应负责 Close。

把 off、n 和局部偏移的口径固定下来，SectionReader 就能稳定用于文件分片、归档成员读取和有限范围转换；真正需要额外小心的是字节与字符的区别，以及顺序游标是否被复用。