Go io.Copy 为什么复制不完整：EOF 语义、短写入与自定义 Reader 检查

线上导出接口偶尔少几百字节时，最容易被怀疑的是 io.Copy 本身。实际上，io.Copy 通常只是把 Reader 返回的字节和错误如实传给 Writer；所谓“复制不完整”，往往是输入提前返回了 io.EOF、自定义 Reader 报错，或者调用方只看了返回长度却漏掉了错误。

先用字节数和错误把现象钉住

不要先改成手写循环。第一步记录源数据长度、io.Copy 的返回值，以及目标缓冲区最终长度。下面的检查能把“少了内容”和“正常到达末尾”分开。

var dst bytes.Buffer
n, err := io.Copy(&dst, src)
fmt.Printf("copied=%d dst=%d err=%v\n", n, dst.Len(), err)
if err != nil {
    return fmt.Errorf("copy payload: %w", err)
}
if n != int64(expected) {
    return fmt.Errorf("short copy: want=%d got=%d", expected, n)
}

这里的 expected 必须来自可靠的边界，例如文件大小、协议头中的长度，不能拿一次不稳定的 Len() 作为真值。若没有已知长度，就应该用校验和或业务记录数做复核。

EOF 为什么是正常结束信号

Reader.Read 的契约允许一次调用同时返回最后一段数据和 io.EOF。调用方必须先处理本次返回的 n 个字节，再处理错误。标准库中的复制逻辑正是按这个顺序工作的，因此最后一小段数据不会因为伴随 EOF 就被自动丢弃。

type oneShotReader struct {
    done bool
}

func (r *oneShotReader) Read(p []byte) (int, error) {
    if r.done {
        return 0, io.EOF
    }
    r.done = true
    copy(p, []byte("last-chunk"))
    return len("last-chunk"), io.EOF
}

如果你在业务层看到返回长度正确、错误为 nil，说明 io.Copy 已经把 EOF 转换成了正常完成。只有 Reader 返回了别的错误，或者 Writer 报告了错误，复制才需要进入失败处理。

短写入通常不是 io.Copy 的静默丢失

Writer 的 Write 也有约束：返回的写入数量小于输入长度时，应同时返回一个非 nil 错误。若自定义 Writer 只返回短数量却给出 nil，调用方就可能得到不完整结果；这属于 Writer 契约被破坏，不是 io.Copy 可以安全猜测的情况。

type countingWriter struct {
    n int
}

func (w *countingWriter) Write(p []byte) (int, error) {
    accepted := len(p) / 2
    w.n += accepted
    return accepted, io.ErrShortWrite
}

真实代码中更应该检查日志里是否出现 short write、磁盘空间错误、连接关闭或上下文取消。不要只打印 n；同一个数字在“正常结束”和“写入失败”两种场景里含义完全不同。

自定义 Reader 的三个检查点

不要把暂时没有数据写成 EOF

网络流或异步生产者暂时没有数据时，不能把“现在没有”误写成“永远结束”。EOF 表示流的末尾已经确定；如果数据还会到达，应等待、返回暂时性错误，或换用适合流式场景的同步方式。

n 大于零时先消费数据

处理 Reader 时要先处理 p[:n]，再根据错误决定是否退出。即使返回的是 n > 0, err == io.EOF，这批数据也属于有效内容。

错误要保留上下文

自定义 Reader 发生校验失败时，返回原始错误并在上层用 %w 包装。这样既能看到复制阶段，又能用 errors.Is 判断根因，避免把所有异常都归为“文件不完整”。

一个可复现的最小核对程序

下面的程序同时覆盖正常 EOF 和目标长度校验。运行后，copied、目标长度和原始字符串应一致。

package main

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

func main() {
    source := "go-copy-check"
    var dst bytes.Buffer
    n, err := io.Copy(&dst, strings.NewReader(source))
    if err != nil {
        panic(err)
    }
    if n != int64(len(source)) || dst.String() != source {
        panic("copy result mismatch")
    }
    fmt.Printf("copied=%d result=%q\n", n, dst.String())
}

这段程序验证的是结果，不是某个实现细节。换成文件、压缩流或网络连接后，仍然保留“返回值、错误、业务校验”三层检查，定位会快很多。

常见误区与边界判断

• 把 io.EOF 记录成失败：对普通 Reader 来说，复制完成后通常不会把 EOF 作为错误返回给调用方。
• 只比较目标长度：长度相同也可能内容错误，重要数据应增加哈希或协议校验。
• 为了绕过问题改成无限重试：如果源 Reader 已返回确定错误，重试只会掩盖根因，还可能重复写入。
• 把网络连接当成文件：连接没有天然的末尾，必须由协议边界、关闭动作或长度字段决定读取结束。

相关问题

io.Copy 和 io.CopyBuffer 该怎么选？

没有复用缓冲区或特殊内存约束时，优先用 io.Copy；需要控制缓冲区生命周期、减少重复分配时，再使用 io.CopyBuffer。两者都不能修复违反 Reader/Writer 契约的实现。

为什么返回的 n 比预期小却没有 error？

可能是 Reader 正常结束但源内容本来就短，也可能是调用方的预期长度不可靠。先确认源头长度，再检查 Reader 是否提前返回 EOF，最后才看 Writer 和传输过程。

把复制结果变成可验证的事实

遇到“io.Copy 少数据”，先记录 n、err、源端边界和目标端校验值。EOF 是结束信号，短写入是契约问题，业务校验失败则是内容问题。把这三类现象分开后，通常不需要盲目替换复制实现，就能找到真正丢失的位置。