Go io.LimitedReader 读完限制字节后怎么区分真正 EOF

我在给输入流加长度保护时，最容易误判的一点是：读取循环返回了 io.EOF，并不自动说明底层文件或网络流已经完整结束。对 io.LimitedReader 来说，N 是“还允许读多少字节”的预算；预算耗尽时它也会返回 EOF。

更稳妥的判断方式是同时看三件事：这次读了多少字节、读取后 N 还剩多少，以及返回的 error 是 EOF 还是其他错误。

官方地址：https://pkg.go.dev/io#LimitedReader

先把 N 看成剩余预算

LimitedReader 包装一个底层 io.Reader。每次成功读取后，N 会减去本次返回的字节数；当 N 时，限制器不再向底层读取，直接返回 io.EOF。官方文档也明确说明，底层 Reader 提前返回 EOF 时，限制器同样会把这个 EOF 传给调用方。

因此，下面两种情况都可能看到 err == io.EOF：

• 限制预算先用完：读取后 N == 0，说明调用方拿到了允许拿到的最大字节数。
• 底层数据先结束：读取后仍有 N > 0，但底层 Reader 返回了 EOF，说明源数据比限制长度短。

这就是“真正 EOF”容易被说混的地方：EOF 是本次 Reader 链路的结束信号，但仅靠它不能回答“是源端结束，还是我设置的上限结束”。

按 N 与 error 分层判断

下面的辅助函数把有限输入读到内存中，并保留“达到上限”和“源数据提前结束”的区别。它不把 EOF 当作失败，也不吞掉非 EOF 错误。

package main

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

// readBounded 只负责读取最多 limit 字节，并返回来源状态。
func readBounded(src io.Reader, limit int64) ([]byte, string, error) {
    limited := &io.LimitedReader{R: src, N: limit}
    var buf bytes.Buffer

    // Copy 读到 EOF 为止；LimitedReader 会在 N 归零时停止继续读底层。
    _, err := io.Copy(&buf, limited)
    if err != nil {
        // 非 EOF 错误必须原样交给上层，不能把网络或文件错误伪装成完整结束。
        return buf.Bytes(), "source-error", err
    }

    if limited.N == 0 {
        // N 归零只证明达到上限；即使源端恰好同时结束，也不要过度推断。
        return buf.Bytes(), "limit-reached", nil
    }
    // io.Copy 把正常 EOF 转成 nil；N 仍大于零时，说明源端先结束。
    return buf.Bytes(), "source-eof", nil
}

func main() {
    data, state, err := readBounded(bytes.NewBufferString("abc"), 5)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%q %s\n", data, state)
}

上例有一个值得单独强调的细节：io.Copy 的成功语义是“读到源端 EOF 或限制器结束”，它会把正常 EOF 转换成 nil。所以用 io.Copy 时，不能再靠 err == io.EOF 判断来源，应该在调用前后记录 N，并把 N > 0 的短读作为源数据不足处理。

固定长度输入不要只看 EOF

如果业务协议要求“必须读满 1024 字节”，那目标不是“最多读 1024 字节”，而是“少一个字节也算失败”。这时直接用 LimitedReader 加普通循环，容易把达到限制和完整数据混成一种成功。更合适的做法是让 io.ReadFull 表达固定长度要求，再根据 n 和错误判断。

package main

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

func readExactly(src io.Reader, size int) error {
    buf := make([]byte, size)

    // ReadFull 会持续读取，直到填满 buf 或遇到错误。
    n, err := io.ReadFull(src, buf)
    if err != nil {
        // n 记录已经拿到的字节数；EOF 只表示一个阶段结束，不能丢掉短读信息。
        return fmt.Errorf("固定长度读取 %d/%d 字节失败: %w", n, size, err)
    }
    fmt.Printf("完整读取 %d 字节\n", n)
    return nil
}

func main() {
    // 只有 3 字节，却要求读取 5 字节，因此会得到 io.ErrUnexpectedEOF。
    if err := readExactly(strings.NewReader("abc"), 5); err != nil {
        fmt.Println(err)
    }
}

io.ReadFull 在没有读到任何字节时返回 EOF，读到一部分但没有填满目标时返回 io.ErrUnexpectedEOF。这正好适合固定头部、定长记录或协议帧；它回答的是“目标缓冲区有没有填满”，而不是“上限之后底层还有没有字节”。

需要证明源端 EOF 时保留探测能力

如果业务必须区分“源数据恰好等于上限”和“源数据超过上限”，单独使用 LimitedReader 不够，因为达到 N == 0 后，它不会替你读取上限之外的字节。此时应保留原始 Reader，在限制读取完成后做一次明确的额外探测；探测是否安全取决于你的协议是否允许消费一个字节。

常见选择可以这样记：

• 只想防止单次读取超过最大长度：使用 io.LimitedReader，把 N == 0 视为“达到上限”。
• 必须拿到固定数量的字节：使用 io.ReadFull，根据 n 和 io.ErrUnexpectedEOF 判断完整性。
• 还要判断上限后是否仍有数据：保留原始 Reader，并设计可回退或可接受消费的探测方式。

我在处理上传、分帧和配置导入时，会先写清楚这三个目标再选 API。这样不会把“限制器正常结束”误写成“文件已经完整读完”，也不会把底层网络错误隐藏在一个看似正常的 EOF 后面。

几个容易混淆的边界

限制值为零时是否还会读取底层？

不会。N 时读取直接返回 EOF，调用方可以把它理解为允许读取的预算为零。

底层一次 Read 同时返回数据和 EOF 怎么办？

先处理已经返回的 n 个字节，再根据限制器剩余预算做判断。不要因为出现 EOF 就丢弃同一次调用带回来的数据。

为什么 io.Copy 成功时不是 io.EOF？

这是 io.Copy 的约定：正常读到输入结束返回 nil，EOF 不是复制失败。需要识别上限状态时，读取前后记录 LimitedReader.N 更可靠。

总结

io.LimitedReader 的 N 是剩余预算，不是底层输入的真实长度。判断时优先看读取后 N：N == 0 表示达到上限；N > 0 且底层返回 EOF，才是源数据提前结束；其他错误则必须原样保留。固定长度读取用 io.ReadFull，需要证明上限后的源端状态时，再设计对原始 Reader 的探测。

参考：https://pkg.go.dev/io#LimitedReader；https://pkg.go.dev/io#ReadFull