Go io.SectionReader 怎么限制随机读取范围：偏移计算、EOF 边界与并发复用

处理对象存储里的大文件时，常见需求不是把整个文件读进内存，而是只读取从某个字节开始的一段内容。Go 的 io.SectionReader 正好把一个 io.ReaderAt 限制在指定区间内：调用方看到的是一个普通 Reader，却不会越过这段范围。真正容易出错的地方在于结束位置是“长度”而不是“终点偏移”，以及读到边界时返回的 EOF。

把起点和长度算对，再把 Read、ReadAt、Seek 的边界测出来，io.SectionReader 就能安全地复用在分片读取、压缩包索引和断点校验中。

先把“起点、长度、终点”分开

io.NewSectionReader 的签名是：

func NewSectionReader(r ReaderAt, off int64, n int64) *SectionReader

如果需要读取文件中从 off=1024 开始的 n=512 个字节，那么有效范围是 [1024, 1536)。右边的 1536 不属于本 section。把 1536 直接作为第三个参数，会让读取范围变成 1536 字节，这是最隐蔽也最常见的偏移错误。

用 ReaderAt 验证 SectionReader 的数据路径

下面的例子用 bytes.NewReader 提供 ReaderAt，把字符串中的 go 片段限制出来。section 内部的逻辑位置从 0 开始，但真正读取仍然落到底层的偏移区间。

package main

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

func main() {
    source := strings.NewReader("0123456789abcdef")
    section := io.NewSectionReader(source, 10, 2)

    buf := make([]byte, 4)
    n, err := section.Read(buf)
    fmt.Printf("n=%d data=%q err=%v\n", n, buf[:n], err)
}

这个 section 的 off=10、n=2，因此第一次读取最多只能拿到 ef。缓冲区虽然有 4 个字节，容量不会扩大 section 的权限。这里可以把调用链记成：NewSectionReader 创建限制器，底层 ReaderAt 提供随机读取，SectionReader 负责把请求截在长度范围内。

EOF 要按“已读字节数”判断

不要把 err == io.EOF 当成“本次一个字节都没有读到”。Reader 允许一次调用同时返回数据和 EOF，调用方应先处理 n，再决定是否结束。

func readSection(section *io.SectionReader) ([]byte, error) {
    buf := make([]byte, 3)
    var out []byte
    for {
        n, err := section.Read(buf)
        out = append(out, buf[:n]...)
        if err == io.EOF {
            return out, nil
        }
        if err != nil {
            return nil, err
        }
    }
}

如果 section 还剩 2 字节而缓冲区能容纳 3 字节，某些 Reader 会先返回 2 和 nil，下一次调用再返回 0 和 io.EOF。也有 Reader 会在最后一批同时给出数据和 EOF。上面的写法两种情况都能正确保留已读内容。

Seek 和并发复用的边界

SectionReader.Seek 的位置以 section 开始处为基准。Seek(0, io.SeekStart) 会回到 section 的逻辑起点，而不是底层文件的绝对 0。需要跳到底层绝对偏移时，应重新计算并创建另一个 SectionReader，不要把两个坐标系混在一起。

并发场景下，可以让多个 SectionReader 共享同一个只读 ReaderAt，每个 section 都有自己的逻辑游标。反过来，把同一个 SectionReader 同时交给多个 goroutine 会共享游标，除非外层加锁，否则读取顺序不可控。

left := io.NewSectionReader(source, 0, 8)
right := io.NewSectionReader(source, 8, 8)

// left 和 right 的位置互不影响；它们共享只读的 source。
_ = left
_ = right

这条规则的核心不是“所有 io.Reader 都并发安全”，而是把底层随机读取能力和上层可变游标拆开。一个 section 一个游标，边界行为才容易测试。

用三个断言把边界锁住

生产代码里至少要覆盖空 section、正好读到末尾和超出末尾三种情况。测试重点是返回的字节、逻辑位置以及错误值，而不是只检查最终字符串。

func TestSectionBoundary(t *testing.T) {
    source := bytes.NewReader([]byte("abcdefghij"))
    section := io.NewSectionReader(source, 3, 4) // defg

    got, err := io.ReadAll(section)
    if err != nil || string(got) != "defg" {
        t.Fatalf("got=%q err=%v", got, err)
    }
    if pos, err := section.Seek(0, io.SeekCurrent); err != nil || pos != 4 {
        t.Fatalf("pos=%d err=%v", pos, err)
    }
}

断言通过只能说明正常区间工作了；再补一个 n=0 的 section 和一次显式的末尾读取，才能发现“把结束偏移当长度”这类错误。

常见问题

第三个参数为什么不是结束偏移？

因为它表示 section 长度。结束偏移需要自行计算为 off+n，区间仍然是左闭右开。

SectionReader 会复制底层文件内容吗？

不会。它保存的是底层 ReaderAt、起点、长度和当前位置，数据仍由底层对象按需读取。

多个 goroutine 能共享一个 SectionReader 吗？

不建议。它有共享的可变游标；更稳妥的方式是每个 goroutine 创建自己的 section，底层使用只读且具备 ReaderAt 语义的对象。

读取 section 时为什么还要处理 n？

Reader 可能在返回最后一批数据的同时返回 io.EOF。先追加 buf[:n]，再处理错误，才能避免丢掉边界数据。

把区间语义留在构造处

io.SectionReader 最有价值的地方不是少写几行读取代码，而是把“只能读这一段”的约束集中在构造处。保存 off 和 n，测试 EOF 与 Seek，并发时为每个任务分配独立游标，后续的分片读取就不会靠调用方自觉控制范围。