Go io.MultiWriter 遇到一个 Writer 写失败后会怎样

我第一次把日志同时写到文件和标准输出时，以为 io.MultiWriter 的行为就是“把这一行交给所有目标，哪个目标失败就单独记下来”。实际更需要记住的一点是：它按传入顺序逐个调用 Writer，某个 Writer 返回错误后，本次写入立即停止，排在后面的 Writer 不会再收到这份数据。

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

MultiWriter 复制的是同一份输入，不负责回滚

io.MultiWriter(w1, w2, w3) 返回一个新的 io.Writer。调用它的 Write(p) 时，标准库会把同一份 p 依次交给列表中的 Writer。它的价值在于把“写文件”和“写控制台”这类复制动作组合起来，但组合后仍然保留每个目标自己的失败边界。

这里有一个容易被忽略的词：逐个。MultiWriter 不会为每个目标启动 goroutine，也不会等所有目标都完成后再统一决定成功与否。先写入的目标一旦成功，后面发生错误时，前面的结果不会自动撤销。

Writer 返回 error 时，失败点后面的目标会跳过

标准库源码中的核心逻辑可以概括为：对每个 Writer 调用 Write(p)；如果返回了非 nil 错误，立即把这个错误返回；如果没有错误但写入数量不等于 len(p)，则返回 io.ErrShortWrite。

因此下面的三个 Writer 如果排列为“文件、审计流、控制台”，审计流返回错误时，文件可能已经写入成功，控制台则不会在这一次调用中收到数据。这个结果不是异常的附带现象，而是 MultiWriter 的设计契约。

package main

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

type failingWriter struct{}

func (failingWriter) Write(p []byte) (int, error) {
    // 模拟只写入一部分后返回底层错误，便于观察失败边界。
    return len(p) / 2, errors.New("审计流不可用")
}

func main() {
    target := io.MultiWriter(io.Discard, failingWriter{}, io.Discard)

    n, err := target.Write([]byte("一条需要复制的日志"))
    // n 和 err 属于这次组合写入的结果，不代表每个目标的独立状态。
    fmt.Printf("n=%d err=%v\n", n, err)
}

上面的示例只用于说明接口关系：当中间 Writer 返回自己的错误时，调用者应该保留这个错误，而不是把它改写成“所有输出都失败”。如果业务需要精确知道哪个目标失败，应让每个目标带有可识别名称，并在进入 MultiWriter 前后记录映射关系。

短写为什么变成 io.ErrShortWrite

io.Writer 的约定是：如果返回的 n 小于输入长度，就必须同时返回非 nil 错误。MultiWriter 会检查每个 Writer 的 n；当 n != len(p) 且底层错误仍为 nil 时，它使用 io.ErrShortWrite 表示“没有完整写完”。

这两个情况需要分开处理：

不要把 io.ErrShortWrite 当成“网络错误”的同义词。它只表达写入没有达到输入长度；真正的根因可能来自自定义 Writer、设备空间、协议封装或某个下层实现。

如何设计失败后的补偿

如果多个输出目标必须保持一致，MultiWriter 不是事务工具。比较稳妥的做法是先确定业务能接受哪种一致性：日志场景通常允许“文件成功、控制台失败”；审计场景可能要求失败即报警；导出场景则可能需要写临时文件，全部完成后再替换正式文件。

我在实际排查时会至少记录四项信息：本次写入的逻辑批次或请求 ID、目标 Writer 名称、返回的 n、以及原始错误。只有拿到这些信息，后续才能判断是重试单个目标、重新生成完整数据，还是放弃这一次复制。

func writeCopies(data []byte, name string, writers map[string]io.Writer) error {
    for target, writer := range writers {
        n, err := writer.Write(data)
        if err != nil {
            // 先保留目标名称和原始错误，避免补偿时丢失失败位置。
            return fmt.Errorf("写入 %s 失败，已写 %d/%d 字节: %w", target, n, len(data), err)
        }
        if n != len(data) {
            // 短写不是成功；将不完整输出交给上层决定是否重建。
            return fmt.Errorf("写入 %s 短写 %d/%d 字节: %w", target, n, len(data), io.ErrShortWrite)
        }
    }
    return nil
}

这段代码故意没有伪装成事务：前一个目标已经成功时，后一个目标仍可能失败。若必须保证“全部目标同时可见”，应改变整体写入方案，例如先分别写入临时对象，再用业务层的提交标记或原子替换完成发布。

几个容易误用的边界

• 不要把 MultiWriter 当成并行 fan-out。目标很多且某个目标可能阻塞时，应该设计独立队列或并行复制策略，并明确背压和失败重试。
• 不要只判断 err 是否为 nil。自定义 Writer 如果违反 Writer 契约返回短写 nil，MultiWriter 会返回 io.ErrShortWrite；调用方仍然要处理。
• 不要盲目重试完整数据。失败点之前的目标可能已经落盘，再次写入可能造成重复日志或重复记录。重试策略要能识别目标和幂等键。

相关问题

一个 Writer 报错后，后面的 Writer 还会写吗？

不会。本次 Write 会在第一个返回错误的 Writer 处停止，后面的目标不会继续收到这份输入。

MultiWriter 是并发写入吗？

不是。标准库按传入列表逐个调用 Writer；如果业务需要并发，需要自行设计并发模型。

为什么会收到 io.ErrShortWrite？

当某个 Writer 返回的写入量小于输入长度且没有提供底层错误时，MultiWriter 用 io.ErrShortWrite 表示不完整写入。

前面的目标成功、后面的目标失败怎么办？

把它当作部分成功处理：保存目标名称、写入量和错误，按业务决定补写、重建临时输出或报警，不能期待 MultiWriter 自动回滚。