io CopyN 读不到指定长度时如何判断原因

我在处理分段文件和流式导出时，最容易把 io.CopyN 的短读原因看错：看到返回了错误，就直接把它归到“源数据不完整”。实际上，判断结果必须同时看 written 和 err。

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

最短判断规则是：written == n && err == nil 才表示指定的 n 个字节已经成功写入目标；如果 written ，再看错误来自源读取还是目标写入。标准库的 CopyN 在源数据提前结束时通常返回 io.EOF，而 io.ErrUnexpectedEOF 更常见于 io.ReadFull 这类固定长度读取。

先把 CopyN 的成功条件写成一个布尔判断

CopyN(dst, src, n) 的目标是从 src 向 dst 复制最多指定的 n 个字节。官方语义给了一个很有用的等价关系：返回时 written == n 当且仅当 err == nil。

这意味着，生产代码不要只写成“判断 err 是否为空”，也不要只比较 written。下面这个最小例子把三类结果拆开：

package main

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

func main() {
    const want int64 = 8
    var dst strings.Builder

    // 源字符串只有 5 个字节，故意制造不足 want 的输入。
    written, err := io.CopyN(&dst, strings.NewReader("hello"), want)

    switch {
    case err == nil && written == want:
        // 只有写满目标长度且没有错误，才算 CopyN 完成。
        fmt.Println("complete", written)
    case err == io.EOF && written 

这个例子中，written 是 5，错误是 io.EOF。它不是“CopyN 复制成功后正常遇到 EOF”，因为 CopyN 要求的是固定长度；只有 n 个字节全部写到目标，EOF 才不会成为失败结果。

源数据提前结束时，EOF 表示什么

从实现上看，CopyN 会把源包装成 io.LimitReader(src, n)，再交给复制逻辑。源在限制范围内正常结束时，Copy 会把 EOF 当作“读完了”；但如果累计写入量小于 n，CopyN 会把这个提前结束的状态返回为 io.EOF。

因此，下面两种情况要分开：

还有一个容易忽略的边界：CopyN 只保证复制前 n 个字节，它不会为了确认“源是否还有更多数据”而继续读取。对于带长度前缀的消息，这正是它适合读取 payload 的原因；如果你还需要判断后面是否存在额外数据，应该在上层另行定义协议边界。

ErrUnexpectedEOF 应该在哪一层判断

io.ErrUnexpectedEOF 的语义是：固定大小的数据结构只读到一部分就遇到了 EOF。标准库的 io.ReadFull 和 io.ReadAtLeast 会把“已经读到一部分但没有满足长度”的普通 EOF 转换为 ErrUnexpectedEOF。

package main

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

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

    // ReadFull 负责把固定长度读满；部分 EOF 会变成 ErrUnexpectedEOF。
    n, err := io.ReadFull(r, buf)
    if err != nil {
        if errors.Is(err, io.ErrUnexpectedEOF) {
            return nil, fmt.Errorf("header truncated after %d bytes: %w", n, err)
        }
        return nil, err
    }
    return buf[:n], nil
}

func main() {
    // 这里只提供 3 个字节，要求读取 4 字节固定头部。
    _, err := readHeader(strings.NewReader("abc"), 4)
    fmt.Println(err)
}

所以不要看到“读不满”就统一判断 ErrUnexpectedEOF。如果调用的是 CopyN，首先按它的返回契约判断 written 和 err；如果调用的是 ReadFull，再按固定块语义识别 ErrUnexpectedEOF。错误名称要和产生它的 API 对齐。

目标 Writer 失败时，不要把锅甩给源 Reader

CopyN 的返回错误也可能来自目标端。例如文件写入失败、管道关闭，或者自定义 Writer 接受了部分字节后返回错误。这时 written 只能说明“目标长度没有完成”，不能单独证明源输入不够。

package main

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

type failWriter struct {
    limit int
    count int
}

func (w *failWriter) Write(p []byte) (int, error) {
    if w.count >= w.limit {
        // 模拟目标已经不可继续写入的情况。
        return 0, fmt.Errorf("destination stopped at %d bytes", w.count)
    }
    remain := w.limit - w.count
    if len(p) > remain {
        w.count += remain
        // 返回短写错误，明确告诉调用方目标只接受了部分数据。
        return remain, io.ErrShortWrite
    }
    w.count += len(p)
    return len(p), nil
}

func main() {
    dst := &failWriter{limit: 3}
    written, err := io.CopyN(dst, strings.NewReader("abcdefgh"), 6)
    fmt.Println("written:", written, "err:", err)
}

在真实工程中，我会把源端 EOF、固定块截断和目标端错误分别打上不同的日志字段。这样排查时能回答三个不同问题：输入是否真的短了、协议块是否被截断、还是输出设备/连接先失败。

一张表记住 CopyN 的处理顺序

1. 先判断 err == nil 且 written == n，这才是成功。
2. 如果 written 且错误是 io.EOF，把它归为源数据提前结束。
3. 如果错误是 io.ErrUnexpectedEOF，确认它是否来自 ReadFull、ReadAtLeast 或其它固定块读取层。
4. 如果是其它错误，保留错误原值，结合目标 Writer 和源 Reader 的上下文判断来源。
5. 不要用一次 CopyN 的结果推断源流是否还有第 n+1 个字节。

我最后会把判断收敛成一句代码契约：CopyN 的长度是否满足看 written，失败原因看 err，错误属于哪一层看调用 API。这样处理短输入时，EOF、ErrUnexpectedEOF 和目标写入错误就不会再被混成同一类问题。

常见追问

CopyN 返回 EOF 一定是源文件损坏吗？

不一定。它只说明在达到 n 字节前源结束了，可能是文件本来就短，也可能是上游流提前关闭。是否损坏要结合协议声明的长度和业务上下文判断。

已经返回 written == n，还需要继续处理 err 吗？

按 CopyN 的契约，写满 n 字节时返回成功。业务代码仍应保留函数返回值的统一处理方式，但不要再把成功结果当成“源已经完全读完”。

什么时候优先用 ReadFull 而不是 CopyN？

需要把固定长度读入内存并检查头部或数据块是否被截断时，用 ReadFull 更直观；需要直接把数据流写入文件、连接或其它 Writer 时，CopyN 更合适。