Go io.CopyN 源数据不足时怎么区分 EOF 和写入错误

处理文件切片、限长响应或协议前缀时，io.CopyN 最容易被误用的地方是：调用者只看返回的字节数，忽略了第二个返回值。判断复制是否完整，应该同时满足 written == n 和 err == nil。源数据不足时，通常得到小于 n 的字节数与 io.EOF；目标写入失败时，则应保留 Writer 返回的实际错误。

先把 CopyN 的返回值当成一个整体

io.CopyN(dst, src, n) 的目标是从 src 向 dst 复制恰好 n 字节，返回已复制数量和复制过程中最早遇到的错误。官方契约可以浓缩成下面这张表：

因此不要写成“只要 written > 0 就算成功”，也不要把所有非空错误都替换成 io.EOF。在限长导出中，长度不足可能意味着上游文件损坏；在普通流式转发中，才可能有不同的容错策略。

源数据不足时如何确认是 EOF

源 Reader 正常读到末尾时，io.CopyN 会把这个事实转换为“没有完成 n 字节”的结果。可以使用 errors.Is 判断错误链，但不能仅凭错误类型忽略长度检查：

package main

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

func main() {
    src := bytes.NewBufferString("short")
    var dst bytes.Buffer

    // n=8 要求完整复制 8 字节，源只有 5 字节。
    written, err := io.CopyN(&dst, src, 8)
    switch {
    case err == nil && written == 8:
        fmt.Println("完整复制", dst.String())
    case errors.Is(err, io.EOF):
        // EOF 表示源已结束，written 可用于记录已得到的部分数据。
        fmt.Printf("源数据不足：written=%d，内容=%q\n", written, dst.String())
    default:
        // 其他错误不能被当成普通短源吞掉，应交给上层处理。
        fmt.Printf("复制失败：written=%d，err=%v\n", written, err)
    }
}

这个例子里 written 是 5，目标缓冲区也保留了这 5 个字节。是否允许继续使用部分数据，要由业务协议决定；如果数据块必须定长，就应直接返回错误或标记该块无效。

写入错误不能被 EOF 掩盖

复制过程同时受读端和写端影响。比如目标磁盘空间不足、网络响应已关闭，Writer 可能在写入一部分之后返回自定义错误。此时关键是先区分 io.EOF、io.ErrShortWrite 和 Writer 自己的错误，再结合 written 做日志或补偿。

type failWriter struct {
    limit int
    count int
}

func (w *failWriter) Write(p []byte) (int, error) {
    // 只接受 limit 以内的字节，模拟目标介质在中途失败。
    remain := w.limit - w.count
    if remain  remain {
        w.count += remain
        // 返回实际写入量和明确错误，调用者不能把它当成完整成功。
        return remain, fmt.Errorf("目标空间不足")
    }
    w.count += len(p)
    return len(p), nil
}

实际项目中可以把错误用 %w 包装后向上返回，保留根因；不要为了统一日志格式把写入错误改成 EOF。还要注意，某些 Writer 如果返回“写入数量小于请求数量但错误为 nil”，复制逻辑会把它视为短写并返回 io.ErrShortWrite，这同样不是成功。

测试时同时断言数量、错误和内容

只断言错误不够，因为某些错误发生前已经写入了一部分；只断言内容也不够，因为内容可能恰好看起来合理。测试建议覆盖三类结果：

• 完整源：断言 written == n、err == nil 和目标内容。
• 短源：断言 written ，并用 errors.Is(err, io.EOF) 判断结束原因。
• 失败 Writer：断言保留实际错误，同时记录已经写入的字节数。

如果业务只是“尽可能复制直到源结束”，应使用 io.Copy，它把正常 EOF 视为成功；如果业务要求固定长度，继续使用 io.CopyN，并把 written == n && err == nil 作为提交、发送或落盘前的门槛。

常见问题

CopyN 返回的 EOF 是不是一定代表程序出错？

不一定。它表示在要求的 n 字节完成前，源已经结束。对定长数据是失败，对允许部分读取的业务则是需要被记录的边界结果。

为什么不能只判断 written == n？

数量相等说明目标收到了 n 字节，但调用契约仍要求 err == nil。只有两个条件同时成立，才能把这次复制当成完整成功。

什么时候应该换成 io.Copy？

当目标是复制全部可用数据，正常到达源末尾不需要报错时，用 io.Copy 更符合语义；固定长度读取则继续用 io.CopyN。