Go SectionReader ReadAt 为什么可能同时返回数据和 EOF

第一次看到 SectionReader.ReadAt 返回 n=2, err=io.EOF 时，我也下意识把整次读取当成失败。其实这两个返回值表达的是两件事：n 告诉调用方缓冲区里已有多少字节有效，err 说明本次请求为什么没能继续满足。只要 n > 0，p[:n] 就应该先被消费；io.EOF 只是同时告诉你，这次读取已经碰到该 section 的边界。

官方入口：https://pkg.go.dev/io#SectionReader.ReadAt。Go 的 ReaderAt 契约明确规定，当返回的字节数小于 len(p) 时，必须同时返回非空错误；而 NewSectionReader 创建的读取器只允许访问指定区间，越过这段区间就以 EOF 表示结束。

n 和 err 本来就是两条信息

ReadAt 的目标是从指定偏移开始填满整个 p。如果请求 4 个字节，但边界内只剩 2 个字节，那么“读到了 2 个字节”和“无法再提供剩余 2 个字节”会在同一次调用中同时成立。前者由 n=2 表示，后者由 err=io.EOF 表示。

这也是 ReadAt 比普通 Read 更严格的地方：只要 n ，就必须给出非空错误。即使 n == len(p)，如果数据刚好位于输入源末尾，底层 ReaderAt 仍被允许返回 io.EOF 或 nil。因此，不能把“有 error”直接等同于“没有数据”。

SectionReader 先把底层数据切出一段

io.NewSectionReader(r, off, n) 不会复制底层数据，它只是建立一段访问边界：底层起点是 base，终点是 limit，对外暴露的偏移从 0 重新开始。调用 sr.ReadAt(p, relativeOff) 时，真正交给底层 ReaderAt 的位置是 base + relativeOff。

关键发生在请求跨过 limit 时。实现会先把要读取的切片缩短到 section 剩余长度，再调用底层 ReadAt。如果底层成功读完这段被缩短后的切片且没有报错，SectionReader 仍会把错误改为 io.EOF，因为调用方原本请求的长度没有被完全满足。

package main

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

func main() {
    // 底层数据为 0 到 9，section 只暴露下标 2 到 6，即 "23456"。
    sr := io.NewSectionReader(strings.NewReader("0123456789"), 2, 5)

    buf := make([]byte, 4)
    // section 内相对偏移 3 只剩 "56" 两个字节。
    n, err := sr.ReadAt(buf, 3)

    // 先使用已经读到的有效部分，再判断边界状态。
    if n > 0 {
        fmt.Printf("data=%q\n", buf[:n])
    }
    fmt.Printf("n=%d err=%v\n", n, err)
}

这段代码对应的返回语义是：

data="56"
n=2 err=EOF

这里的 EOF 没有否定 "56"。它只表示长度为 4 的请求在 section 内只能完成 2 个字节。

这种设计最适合按位置读取的调用方

文件分片、归档格式解析、并发读取固定区间时，调用方通常已经知道目标偏移，不希望某一次读取改变共享游标。ReaderAt 正是按这个需求设计的，而 SectionReader 再加上一层逻辑边界。它让调用方可以把大文件的一小段当成独立输入源，却仍保留“本次到底拿到了多少字节”的精确信息。

对我来说，真正值得记住的不是某个特殊 EOF 案例，而是一个稳定的判断顺序：先相信 n 所声明的有效数据范围，再解释 err 所声明的结束原因。这个顺序同样适用于不少 Go I/O API。

只先判断 err 会丢掉尾部数据

最常见的错误写法，是一看到 err != nil 就立即返回。这样遇到 n > 0, err == io.EOF 时，尾部已经写入缓冲区的数据不会被处理。

n, err := sr.ReadAt(buf, off)
if err != nil {
    // 错误：这里提前返回，会忽略 buf[:n] 中已经读到的数据。
    return err
}
consume(buf[:n])

另一个误区是默认 err == nil 才代表完整读取。对于一般 ReaderAt，官方契约允许“恰好读满且位于输入末尾”时返回 EOF。判断是否填满缓冲区，应该比较 n 与 len(p)；判断为什么停止，再看 err。

稳妥写法是先消费数据，再分类错误

如果业务允许读取到 section 尾部，那么可以把 EOF 视为正常边界，但仍应把其他错误返回给上层：

func readPartAt(r io.ReaderAt, buf []byte, off int64) ([]byte, error) {
    n, err := r.ReadAt(buf, off)

    // n 决定真正有效的数据范围。
    data := buf[:n]

    // EOF 表示到达边界；data 仍然有效。
    if err == io.EOF {
        return data, io.EOF
    }
    if err != nil {
        return data, err
    }
    return data, nil
}

调用方再根据任务语义决定：如果“读到有多少就处理多少”，先处理 data，EOF 后结束；如果协议要求固定长度，就在 len(data) != len(buf) 时把它升级为长度不足错误。不要在通用读取层擅自把 EOF 全部吞掉，因为上层可能需要区分“完整块”和“尾部短块”。

四个边界结果足够定位大多数问题

排查时我会同时记录请求长度、相对偏移、sr.Size()、返回的 n 和 err。只看一条 “EOF” 日志，很难区分是正常读到 section 尾部，还是一开始就把偏移算到了边界外。

最终判断只看三个条件

• n > 0：先处理 p[:n]，不要因为同时有 EOF 就丢弃它。
• n ：本次固定长度请求没有完全满足，非空错误符合 ReaderAt 契约。
• err == io.EOF：已经触及 SectionReader 的逻辑边界，是否算业务失败取决于上层是否要求固定长度。

所以，SectionReader.ReadAt 同时返回数据和 EOF 并不矛盾。数据回答“这次拿到了什么”，EOF 回答“为什么只能拿到这些”。把这两个问题分开处理，就不会遗漏 section 尾部的有效字节。