Go io.MultiWriter怎样把一次写入分发到多个目标怎样完成一个可复用的最小示例

我在做一个很小的命令行工具时遇到过一个看似普通的需求：一份日志既要留在内存里供当前流程读取，又要写入文件，后面还可能接到网络输出。如果每个目标都手动调用一次 Write，调用方很快就会被重复代码和错误分支包围。Go 的 io.MultiWriter 正好把这件事收拢成一个 io.Writer。

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

io.MultiWriter 接收多个 io.Writer，返回一个新的 Writer；每次写入会按传入顺序依次交给这些目标。只要某个目标返回错误，整体写入就停止并返回该错误，后面的目标不会继续收到这次写入。

下面用一个可复用的小项目把这条规则落下来：同一条内容写入 bytes.Buffer 和 os.File，调用方只保留一个写入入口。

先看清一次写入是怎样分发的

io.MultiWriter 并不是把数据复制成多份后并行发送，而是把一组 Writer 包在一个 Writer 后面。它遵循 io.Writer 的约定：写入方法返回实际写入的字节数和错误。官方文档明确说明，多个目标会逐个写入，某个目标报错后停止继续遍历。

这带来三个直接结论：

• 目标的排列顺序有意义，排在前面的 Writer 先参与这次写入。
• 所有目标共享同一次 Write 调用传入的字节内容，目标实现不能修改这块数据。
• 返回的字节数和错误只能代表这次组合写入的整体结果，不能把它当成每个目标的独立回执。

先定一个小项目的边界

为了让示例足够小，我把项目限制在两个目标：一个 bytes.Buffer 保存内存副本，一个文件保存落盘副本。以后要接入标准输出或网络连接，只要它们实现 io.Writer，就可以继续放进同一个组合中。

把多个目标封装成可复用的小项目

封装函数时，我倾向于返回组合 Writer 和一个关闭函数。这样资源所有权比较清楚：创建文件的一方也负责关闭文件，业务代码只关注写入是否成功。

package main

import (
    "bytes"
    "fmt"
    "io"
    "os"
)

// fanoutWriter 保存组合 Writer 和内存副本，便于调用方统一写入。
type fanoutWriter struct {
    writer io.Writer
    buffer *bytes.Buffer
}

// buildFanoutWriter 创建文件目标，并把它与内存目标组合起来。
func buildFanoutWriter(path string) (*fanoutWriter, func() error, error) {
    // 创建文件失败时直接返回，避免把一个不完整的 Writer 暴露给调用方。
    file, err := os.Create(path)
    if err != nil {
        return nil, nil, fmt.Errorf("创建输出文件失败: %w", err)
    }

    buffer := new(bytes.Buffer)
    // MultiWriter 按传入顺序组织目标；这里先写内存，再写文件。
    writer := io.MultiWriter(buffer, file)
    closeFile := func() error {
        // 关闭动作由创建文件的封装函数集中管理。
        return file.Close()
    }

    return &fanoutWriter{writer: writer, buffer: buffer}, closeFile, nil
}

func main() {
    target, closeFile, err := buildFanoutWriter("fanout.log")
    if err != nil {
        fmt.Println(err)
        return
    }
    defer func() {
        // 关闭失败也要显式报告，避免资源错误被静默丢弃。
        if closeErr := closeFile(); closeErr != nil {
            fmt.Println("关闭输出文件失败:", closeErr)
        }
    }()

    source := bytes.NewBufferString("一次写入，两个目标\\n")
    written, err := io.Copy(target.writer, source)
    if err != nil {
        // MultiWriter 的错误是组合写入结果，交给调用方决定是否重试。
        fmt.Println("分发写入失败:", err)
        return
    }

    fmt.Printf("写入 %d 字节，内存副本：%q\\n", written, target.buffer.String())
}

这里的关键点是 buildFanoutWriter 不把 *os.File 丢给调用方，而是返回一个关闭函数。这样即使未来把文件目标换成网络连接，资源清理的位置也不会散落在每个业务分支里。

把普通 Reader 接到多个目标

项目里如果输入来自文件、请求体或字符串 Reader，不需要先把它全部读进一个大切片。io.Copy 直接接收组合后的 Writer 即可；它会把 Reader 的内容持续写入这个统一入口。

func copyToTargets(dst io.Writer, src io.Reader) (int64, error) {
    // 让 io.Copy 负责读取循环，调用方只处理总字节数与错误。
    written, err := io.Copy(dst, src)
    if err != nil {
        // 记录来源错误，便于区分读取失败和某个 Writer 写失败。
        return written, fmt.Errorf("复制到多个目标失败: %w", err)
    }
    return written, nil
}

如果输入本身是大文件，这种写法也更容易保持流式处理。需要强调的是，流式并不意味着目标之间并行；MultiWriter 仍然按目标顺序处理每次写入。

错误停止时，哪些目标可能已经写入

第一次使用时，我最容易忽略的是“组合写入失败”不等于“所有目标都没有变化”。假设内存目标排在文件目标之前，内存写入成功、文件写入失败，那么内存副本可能已经更新，文件副本却不完整。反过来，如果文件排在前面，文件可能已写入，而后续目标尚未处理。

因此，io.MultiWriter 适合“尽量把同一份输出送到多个目标”的场景，不自动提供事务回滚，也不保证目标之间的一致提交。如果业务要求“所有目标都成功才算成功”，需要在上层设计补偿、临时文件、重试或幂等策略。

写入目标还必须遵守 io.Writer 的契约：返回的字节数少于请求长度时应返回非空错误。否则组合 Writer 只能得到一个短写结果，调用方需要把它当成失败处理，而不是假设所有内容都已完成。

验收时只看这几个结果

这个小项目的验收不需要把逻辑扩展成复杂测试，先检查四件事即可：

1. 组合 Writer 是否只暴露一个 io.Writer 写入口。
2. 内存副本是否与输入内容一致，且没有因为手动拼接而多出一份无关格式。
3. 文件创建成功后是否始终有对应的关闭动作。
4. 写入返回错误时，调用方是否保留已写入量，并明确记录这是部分结果风险。

如果只需要把一次输出同步送到几个互相独立的 Writer，io.MultiWriter 是很合适的薄封装；如果目标之间需要原子提交、独立重试或并发隔离，就应该在它外面再加一层专门的协调逻辑。

常见问题

io.MultiWriter 会并发写入多个目标吗？

不会。官方说明是按传入顺序逐个写入；它提供的是统一入口，不是并发调度器。

一个目标写失败后，后面的目标还会收到数据吗？

不会继续遍历后面的目标。已经排在前面的目标可能已经写入，因此要按部分结果来设计错误处理。

可以把同一个 Writer 重复传给 io.MultiWriter 吗？

技术上可以传入实现了 io.Writer 的对象，但同一次写入会重复调用它，通常会造成重复内容。除非这是明确需求，否则应避免重复目标。

文件关闭失败应该怎么处理？

不要完全忽略关闭错误。可以像示例那样在延迟清理函数中记录错误；对于需要严格确认落盘的场景，还应结合业务的持久化策略处理。