Go io.ReaderFrom 怎样让目标复用源端的高效复制

写大文件、响应体或对象流时，很多人会直接调用 io.Copy，但不清楚目标端为什么有机会“自己读”。答案是 io.ReaderFrom：它给目标 Writer 增加一个 ReadFrom(io.Reader) 入口，让目标类型可以按自己的方式接收输入。

官方地址：https://pkg.go.dev/io#ReaderFrom

ReaderFrom 的方法契约是什么

io.ReaderFrom 只有一个方法：

type ReaderFrom interface {
    ReadFrom(r Reader) (n int64, err error)
}

它的语义不是“读取一次”，而是持续从输入读到 EOF 或遇到错误。返回值 n 表示已经处理的字节数；正常读完时应返回 err == nil，真正的读取或写入错误才向上返回。

这个契约决定了实现时要先处理 n > 0，再处理 err。一次 Read 可能同时返回数据和 EOF，不能因为看见 EOF 就丢掉这批数据。

目标 Writer 怎样实现 ReadFrom

下面的包装类型把数据写入内部的 io.Writer。它没有调用 io.Copy 实现自身的 ReadFrom，避免再次触发同一个接口；示例中的缓冲区只是一个明确的普通实现，不代表所有目标都应使用同样大小。

package main

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

type directSink struct {
    dst io.Writer
}

// Write 让 directSink 满足 io.Writer，真正的存储仍由 dst 负责。
func (s *directSink) Write(p []byte) (int, error) {
    return s.dst.Write(p)
}

// ReadFrom 按目标端的策略读取输入，并返回累计字节数。
func (s *directSink) ReadFrom(r io.Reader) (int64, error) {
    buf := make([]byte, 32*1024) // 缓冲区只服务于这个普通实现。
    var total int64

    for {
        n, readErr := r.Read(buf)
        if n > 0 {
            written, writeErr := s.dst.Write(buf[:n])
            total += int64(written)
            if writeErr != nil {
                return total, writeErr // 写端错误优先返回。
            }
            if written != n {
                return total, io.ErrShortWrite // 短写必须显式报告。
            }
        }
        if readErr == io.EOF {
            return total, nil // EOF 表示正常结束，不向上冒泡。
        }
        if readErr != nil {
            return total, readErr // 保留真实读取错误。
        }
    }
}

func main() {
    var out strings.Builder
    sink := &directSink{dst: &out}
    src := io.LimitReader(strings.NewReader("stream-data"), 11)

    n, err := io.Copy(sink, src) // src 没有 WriterTo 时可走 ReaderFrom。
    if err != nil {
        fmt.Println("copy failed:", err)
        return
    }
    fmt.Println(n, out.String())
}

生产代码里还要关注底层目标是否允许并发、是否需要关闭资源，以及 Write 返回短写但没有错误的情况。ReadFrom 只负责定义目标端的接收策略，不会替调用方决定文件落盘、网络发送或事务提交。

io.Copy 为什么可能调用 ReaderFrom

io.Copy(dst, src) 的选择顺序容易被忽略。官方实现先检查源端是否实现 io.WriterTo；只有源端没有这项能力时，才检查目标端是否实现 io.ReaderFrom。两者都没有，才退回普通的 Read/Write 循环。

这也解释了一个常见误判：给目标类型增加了 ReadFrom，但实际复制仍然没有进入它，可能是源端已经提供了 WriterTo。不要只看目标类型的代码来判断路径。

CopyBuffer 和性能判断要看清边界

io.CopyBuffer 允许调用方提供复用缓冲区，但官方文档明确指出：如果源端实现 WriterTo 或目标端实现 ReaderFrom，这个 buf 不会用于执行复制。因此，调整 buf 大小不一定能影响当前路径。

buf := make([]byte, 64*1024) // 只在普通 Read/Write 路径中可能发挥作用。
written, err := io.CopyBuffer(dst, src, buf)
if err != nil {
    // 保留 written，便于调用方处理部分写入或记录进度。
    return written, fmt.Errorf("copy stream: %w", err)
}
return written, nil

判断收益时，先确认源端和目标端的接口能力，再比较分配次数、系统调用、吞吐和延迟。不要把“调用了 ReaderFrom”直接写成“已经零拷贝”；ReaderFrom 是 Go 层的扩展接口，具体实现仍可能使用普通缓冲区。

常见问题

实现了 ReaderFrom 就一定比普通 io.Copy 快吗？

不一定。它只是给目标端一个自定义接收入口，是否更快取决于目标实现、输入类型、缓冲区和实际工作负载。

为什么实现了 ReadFrom 却没有被调用？

优先检查源端是否实现了 WriterTo。io.Copy 会优先使用源端能力，其次才回退到目标端的 ReaderFrom。

ReadFrom 读到 EOF 要返回 io.EOF 吗？

正常结束应返回累计字节数和 nil；EOF 是“读完”的信号，不是复制失败。

把 ReaderFrom 当作目标端的接口契约来实现，再结合 io.Copy 的选择顺序检查实际路径，通常比盲目调大缓冲区更可靠。