Go io.Copy返回部分字节时怎样处理错误

在 Go 中，io.Copy 返回的两个值必须一起判断：written 表示已经写入目标的字节数，err 表示复制过程中遇到的第一个错误。出现 written > 0 && err != nil 时，正确结论不是“复制成功”，而是“目标可能只收到部分内容，需要按业务决定保留、覆盖或终止”。

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

下面只讨论部分写入和错误判断，不把这个问题扩展成完整的断点续传协议。

先看 io.Copy 的两个返回值

io.Copy(dst, src) 从 src 读数据并写入 dst，返回已写入字节数和错误。可以先把组合关系记成一张速查表：

如果目标是文件或对象存储，业务通常还需要知道“预期长度”。仅凭 err == nil 能说明复制过程正常结束，但不能替你判断目标文件是否还需要校验长度、摘要或协议元数据。

为什么正常读完不是 io.EOF

底层 Reader 的接口允许在读到末尾时返回 EOF，但 io.Copy 把“读到源末尾”视为正常结束，所以一次成功复制会返回 err == nil。调用方不应该写出把 EOF 统一当失败的判断：

package main

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

func main() {
	var dst strings.Builder
	written, err := io.Copy(&dst, strings.NewReader("hello"))
	// 正常读到源末尾时，io.Copy 返回 nil，而不是把 EOF 透传给调用方。
	if err != nil {
		fmt.Printf("复制失败：written=%d err=%v\n", written, err)
		return
	}
	// 这里再按业务检查长度或内容摘要，避免只依赖错误值。
	fmt.Printf("复制完成：written=%d content=%q\n", written, dst.String())
}

所以，判断 io.Copy 是否成功时，通常只把非 nil 的真实错误当作复制失败；如果业务有明确长度，则再比较 written 与预期值。

错误发生后不要把部分结果当完整结果

目标端写入失败时，io.Copy 可能已经返回大于零的 written。此时目标里存在一段前缀数据，但它可能没有完整格式、校验和或结尾标记。最稳妥的处理是记录数量和错误，关闭或清理临时目标，再由上层决定是否重试。

package main

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

func copyToTemporary(dst io.Writer, src io.Reader, expected int64) error {
	written, err := io.Copy(dst, src)
	// written 要保留在日志或结果对象中，便于判断是否只写入了前缀。
	if err != nil {
		return fmt.Errorf("复制中断：已写入 %d/%d 字节：%w", written, expected, err)
	}
	// 长度是业务约束时，成功返回也要检查预期大小。
	if expected >= 0 && written != expected {
		return fmt.Errorf("长度不完整：已写入 %d/%d 字节", written, expected)
	}
	return nil
}

func main() {
	// 这里只演示正常源；真实业务应把目标写入临时文件或可回滚对象。
	var dst strings.Builder
	if err := copyToTemporary(&dst, strings.NewReader("payload"), int64(len("payload"))); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("临时目标可以进入提交阶段")
}

临时目标的价值在于把“写入”和“提交”分开：复制失败时删除临时文件；复制成功且长度、摘要等条件满足时，再通过重命名或对象提交让读者看到完整结果。

重试必须先回答目标是否幂等

对一个会追加数据的目标直接重试，可能得到“前缀 + 完整内容”的重复结果。重试前至少区分下面三种情况：

• 临时文件可删除：丢弃不完整文件，从头复制，最后原子替换目标。
• 目标支持覆盖写：确认覆盖从固定起点开始，并清理旧尾部，不能只覆盖前缀。
• 目标支持断点协议：必须使用协议提供的偏移、版本或校验信息，不能把 written 直接当成远端已确认偏移。

如果目标是不可回滚的流，失败后的部分数据通常只能被消费方丢弃，或者由协议层增加消息边界与序号。io.Copy 只负责复制，不会替你定义重试语义。

用可控 Reader 理解 n 大于零与错误同时出现

Go 的 Reader 允许一次返回已经读到的字节和一个错误。下面的 Reader 在交出一小段数据后返回自定义错误，用来说明调用方为什么必须同时保存两个返回值：

package main

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

type failAfterReader struct {
	data []byte
	done bool
}

func (r *failAfterReader) Read(p []byte) (int, error) {
	if r.done {
		// 第二次读取返回稳定错误，避免把失败误判成正常 EOF。
		return 0, errors.New("源读取失败")
	}
	r.done = true
	n := copy(p, r.data)
	// 同一次 Read 交出数据并报告错误，调用方必须先处理 n。
	return n, errors.New("数据源在交付这段数据后中断")
}

func main() {
	var dst strings.Builder
	written, err := io.Copy(&dst, &failAfterReader{data: []byte("prefix")})
	// 这里的 written 可能大于零，同时 err 也非 nil。
	fmt.Printf("written=%d err=%v content=%q\n", written, err, dst.String())
}

这类结果说明“已经写入一部分”和“复制没有完整结束”可以同时成立。生产代码应把错误传给上层，并把目标状态标为未提交，而不是只看目标里已经出现了内容。

常见误区与速查

可以把最终判断压缩成一句话：err == nil 表示复制循环正常结束，written 表示已经写了多少；当错误非 nil 时，已有字节只能作为部分结果，后续动作必须由目标的幂等性和回滚能力决定。

相关问题

io.Copy 返回的 err 可以直接判断为 io.EOF 吗？

正常读到源末尾时，io.Copy 不把 EOF 作为失败返回。调用方应关注非 nil 的实际 I/O 错误。

为什么 written 大于零仍然需要重试？

因为它只代表已经写入的数量，不代表目标内容已经完整、可提交或通过校验。

CopyBuffer 能避免部分写入吗？

不能。CopyBuffer 只允许提供复用缓冲区；源或目标出错时，部分写入仍然可能发生。