Go io.Copy遇到短写但无错误时的写入语义说明

如果自定义 io.Writer 返回的 n 小于 len(p)，同时把 err 返回成 nil，这不是“暂时少写一点但没问题”，而是违反了 io.Writer 的接口约定。调用 io.Copy 时，复制循环会把这种结果转换为 io.ErrShortWrite；返回的 written 只统计已经写出的字节，不能当成整段复制成功。

为什么短写且无错误会变成 io.ErrShortWrite

Go 的 Writer 约定很明确：一次 Write(p) 如果没有写完 p，就必须返回一个非空错误。标准库把“接收的字节少于请求，但没有明确错误”命名为 io.ErrShortWrite。因此，问题的根源通常在自定义 Writer，而不是 io.Copy 忽略了剩余数据。

下面这张图是静态说明图：左侧输入经过复制器到达 Writer，短写和 nil 错误被识别为异常关系。它不代表某次本机运行截图。

用最小示例看清 written 和 error

为了复现这个边界，可以让 Writer 故意少接收一个字节。示例中的返回方式只用于说明错误契约，生产代码不要照搬。

package main

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

type shortWriter struct{}

func (shortWriter) Write(p []byte) (int, error) {
    // 故意模拟短写；真实Writer在短写时必须同时返回非空错误。
    if len(p) == 0 {
        return 0, nil
    }
    return len(p) - 1, nil
}

func main() {
    // strings.Reader提供输入，io.Copy负责观察目标Writer的返回值。
    written, err := io.Copy(shortWriter{}, strings.NewReader("golang"))
    // 先看written，再判断err，避免把部分成功误当成完整成功。
    fmt.Printf("written=%d err=%v\\n", written, err)
}

这个场景下，调用方应关注两件事：written 是已经报告写出的数量，err 应为 io.ErrShortWrite。不要写成“只要 written 大于零就算成功”，也不要把 io.EOF 当成 io.Copy 的成功返回值。

自定义 Writer 应该怎样返回短写

如果底层资源确实只能写入一部分，Writer 应返回实际数量和具体错误；如果可以继续写，则由 Writer 自己在内部完成循环，直到处理完整的输入或遇到不可恢复错误。调用方不能根据 err == nil 擅自猜测剩余数据会被自动补写。

type limitedWriter struct {
    dst io.Writer
    max int
}

func (w limitedWriter) Write(p []byte) (int, error) {
    // max只限制本次调用，避免返回短写却隐藏原因。
    if w.max  w.max {
        // 这里明确返回错误，让上层知道本次输入没有完整写入。
        n, err := w.dst.Write(p[:w.max])
        if err != nil {
            return n, err
        }
        return n, io.ErrShortWrite
    }
    // 输入未超过限制时，透传底层的数量和错误。
    return w.dst.Write(p)
}

更重要的是，错误应该带有可定位的原因，例如底层连接关闭、文件空间不足或协议帧不完整。不要用一个静默的 nil 掩盖短写，否则上层只能看到“复制到一半停止”。

WriterTo与ReaderFrom会改变排查路径

看到 io.Copy 却没有进入自定义 Write，不一定是断点失效。标准库会优先尝试源端的 WriterTo；没有时，再尝试目标端的 ReaderFrom；最后才使用普通缓冲复制。实现了这些接口的对象可能拥有自己的循环和错误处理。

下图是调用关系的静态结构图，不是 IDE 或终端截图。排查时应沿着实际命中的接口查看返回值，而不是只盯着 copyBuffer。

生产代码的短写检查清单

处理复制、上传或转发时，可以按下面顺序检查：先记录 written 和完整错误；再确认 Writer 是否遵守短写契约；然后确认快路径接口；最后决定是否重试。重试前必须确定底层操作可重放，否则可能造成重复写入。

• 检查 n 时是否返回了非空错误。
• 区分 io.ErrShortWrite、底层 I/O 错误和源端读取错误。
• 记录已经写出的偏移，避免重试时覆盖或重复追加。
• 让调用方负责关闭文件、响应体等资源，不把关闭错误静默丢弃。

相关问题

io.Copy 返回 err == nil 时能否认为全部写完？

在遵守接口约定的实现下可以这样理解：复制直到源端 EOF 且没有其他错误时返回 nil。仍应保留 written，因为它是审计和进度记录需要的结果。

为什么不能直接忽略 io.Copy 的错误？

因为短写可能已经产生部分输出，忽略错误会让上层拿到不完整文件、响应或消息。至少要记录数量、错误类型和可重试边界。

io.CopyBuffer 能解决短写吗？

它只让调用方提供复制缓冲区，不能修复违反 io.Writer 契约的实现。短写的责任仍在实际写入路径和错误处理。