Go io.SectionReader 怎样读取文件片段而不移动共享偏移量

我在处理一个较大的二进制文件时，经常只想读取其中一小段：文件头在前 64 个字节，索引表从某个偏移开始，正文又是另一个固定范围。直接对同一个可定位文件对象调用 Seek 和 Read，很容易让不同读取逻辑互相影响。

这个场景可以交给 io.NewSectionReader。它接收一个实现 io.ReaderAt 的数据源、起始偏移和长度，返回一个只覆盖这段范围的 *io.SectionReader。窗口内的顺序读取会停在自己的末尾，不需要把底层对象的共享顺序游标改到目标片段。

关键点是：SectionReader 隔离的是“可读范围”和自己的读取位置，不是把底层数据复制成一份，也不自动保证底层数据源可以被多个 goroutine 并发访问。

先确认数据源满足 ReaderAt

NewSectionReader 的第一个参数类型是 io.ReaderAt，它按给定的绝对偏移读取数据，而不是依赖一个共享的当前游标。普通的 io.Reader 只有顺序读取能力，不能直接传给这个构造函数。

文件对象通常同时提供 Read、ReadAt、Seek 等能力，所以可以直接作为数据源。内存里的 bytes.Reader 也实现了 ReaderAt，适合在没有真实文件时组织一个可重复的输入。

package main

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

func main() {
    // bytes.Reader 同时支持顺序读取和按绝对偏移读取。
    source := bytes.NewReader([]byte("header|index|payload"))

    // 这里的赋值只检查接口能力，不会移动 source 的顺序读取位置。
    var positioned io.ReaderAt = source
    fmt.Printf("ReaderAt 类型：%T\n", positioned)
}

如果自定义类型只实现了 Read，需要先补充一个可靠的 ReadAt 实现，或改用能够提供按偏移读取能力的数据源。不要为了让代码通过编译，把带共享状态的 Read 方法伪装成 ReadAt。

用 NewSectionReader 固定读取窗口

构造函数的三个参数分别是数据源、起始偏移 off 和窗口长度 n。窗口只描述“从哪里开始、最多允许读多少字节”，不会把整段数据复制到新的缓冲区。

package main

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

func main() {
    // 用固定内容模拟文件：索引表从第 7 个字节开始，长度为 5。
    source := bytes.NewReader([]byte("header|index|payload"))
    section := io.NewSectionReader(source, 7, 5)

    // Size 返回窗口长度，而不是底层数据源的总长度。
    fmt.Println("窗口长度：", section.Size())
}

这里的偏移是相对于底层数据源起点的绝对位置，长度决定了 SectionReader 的硬边界。即使底层数据后面还有内容，窗口也不会继续越界读取。

用 Read 读取窗口内的连续内容

把 SectionReader 当成一个普通的 io.Reader 使用时，第一次 Read 从窗口起点开始，后续读取沿着这个窗口自己的位置继续前进。读到窗口末尾后，按照 io.Reader 的约定得到 io.EOF。

package main

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

func main() {
    // 窗口只包含 index，不会把后面的 payload 暴露给读取循环。
    source := bytes.NewReader([]byte("header|index|payload"))
    section := io.NewSectionReader(source, 7, 5)

    data, err := io.ReadAll(section)
    if err != nil {
        // 读取窗口失败时保留原始错误，方便区分输入错误和正常 EOF。
        log.Fatal(err)
    }
    fmt.Printf("片段：%s\n", data)
}

如果只需要把一段内容交给解码器、哈希计算或上传函数，这种方式很顺手。要注意的是，io.ReadAll 会把窗口内容放进内存；窗口很大时，应改成带缓冲区的循环读取。

用 ReadAt 读取窗口内的局部位置

ReadAt 的偏移是相对于 SectionReader 窗口起点的局部偏移，不是底层文件的绝对偏移。例如窗口从底层第 7 个字节开始，调用 section.ReadAt(buf, 2) 实际读取的是底层第 9 个字节附近的数据。

package main

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

func main() {
    // 窗口内容为 index；局部偏移 2 从 d 开始读取两个字节。
    source := bytes.NewReader([]byte("header|index|payload"))
    section := io.NewSectionReader(source, 7, 5)
    buf := make([]byte, 2)

    n, err := section.ReadAt(buf, 2)
    if err != nil && err != io.EOF {
        // ReadAt 允许返回已读字节数与错误，先保留 n 再处理异常。
        log.Fatal(err)
    }
    fmt.Printf("读取 %d 字节：%s\n", n, buf[:n])
}

这种读取不会替顺序 Read 推进窗口位置，适合在同一个固定范围内读取几个已知字段。若缓冲区跨过窗口末尾，可能同时得到部分数据和 io.EOF，调用方应根据返回的 n 处理已经拿到的内容。

用 Seek 和 Size 处理窗口边界

SectionReader 同时实现 io.Seeker。但它的 Seek 参照物是这个窗口：io.SeekStart 的 0 代表窗口起点，io.SeekEnd 的 0 代表窗口末尾，而不是底层数据源的结尾。

package main

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

func main() {
    // SectionReader 的逻辑范围是底层数据的 [7, 12) 区间。
    source := bytes.NewReader([]byte("header|index|payload"))
    section := io.NewSectionReader(source, 7, 5)

    // 先定位到窗口内的第 3 个字节，再从该位置顺序读取。
    if _, err := section.Seek(3, io.SeekStart); err != nil {
        log.Fatal(err)
    }
    tail, err := io.ReadAll(section)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("窗口尾部：%s\n", tail)
}

实战中可以把 Size() 当作协议字段或分块读取的边界信息。它只返回构造时传入的窗口长度，不代表当前还剩多少字节；当前顺序位置需要结合 Seek 的结果自行计算。

别把窗口隔离误解成并发安全

我第一次把文件的多个片段交给不同处理函数时，最容易混淆的就是“每个 SectionReader 有自己的范围”和“底层对象可以随便并发访问”不是一回事。前者是窗口语义，后者取决于底层 ReaderAt 的实现以及应用是否还在写入。

SectionReader 通过 ReadAt 访问底层区间，并把窗口边界映射到自己的方法上；它并不替底层数据源增加锁，也不负责协调文件内容在读取期间发生变化。需要并发读取时，应先确认底层类型的文档约束，再决定是否加锁、使用独立句柄或建立不可变输入。

一个小检查表

相关问题

io.SectionReader 和 io.LimitReader 有什么区别？

LimitReader 从一个顺序 Reader 当前所在位置开始限制最多读取多少字节；SectionReader 则要求 ReaderAt，同时明确底层起始偏移和窗口长度，适合随机定位到一个固定片段。

ReadAt 的偏移为什么不是文件绝对偏移？

因为 SectionReader 把底层区间包装成了新的逻辑读取对象。对它调用 ReadAt 时，偏移 0 表示这个逻辑窗口的起点；需要换算底层位置时，再把窗口的起始偏移加上局部偏移。

窗口长度设置得比文件剩余长度大可以吗？

可以创建窗口，但实际读取会在底层数据源可读范围结束时返回相应的读取结果。业务代码不要只依赖窗口长度判断数据完整性，还应处理读取返回的字节数和错误。

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