Go io.MultiWriter 某个目标短写后为什么立即停止

io.MultiWriter 遇到某个目标短写后会立即停止，因为它必须保证“本次写入的整段数据已被当前目标完整接收”这一最低契约。只要某个 Writer 返回 n ，即使错误是 nil，MultiWriter 也会把它升级为 io.ErrShortWrite，直接返回，并且不再调用排在后面的目标。

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

这里的“停止”不等于回滚：排在前面的目标可能已经收到全部数据，发生短写的目标只收到前缀，后面的目标则完全没有被调用。

短写现场：为什么第三个目标没有收到数据

先把问题压缩成一个最小配方。下面的 shortWriter 故意违反 io.Writer 契约：它只接收前三个字节，却返回 nil 错误。真实项目里，类似行为可能来自自定义缓冲器、适配层或封装不完整的第三方 Writer。

package main

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

type shortWriter struct {
    limit int
}

func (w shortWriter) Write(p []byte) (int, error) {
    if len(p) 

按接口语义，对应结果是：n=3、err=short write，第一个缓冲区已经是 abcdef，第三个缓冲区仍为空。这个现象看似“写了一半”，实际是三个目标处于三种不同状态。

最小配方：短写为何被升级成 ErrShortWrite

io.Writer 的约定是：如果 Write 返回的字节数少于输入长度，就必须同时返回一个非空错误。MultiWriter 不能假装这种异常不存在，否则调用方会误以为所有目标都成功接收了同一份数据。

MultiWriter 的核心判断可以概括为下面三步：

1. 按传入顺序调用每个目标的 Write(p)。
2. 目标返回非空错误时，立即把该错误返回。
3. 目标返回 n != len(p) 且错误为空时，构造 io.ErrShortWrite 并立即返回。

n, err := w.Write(p)
if err != nil {
    // 目标明确失败，停止调用后续 Writer
    return n, err
}
if n != len(p) {
    // 短写却没有错误，转成标准短写错误
    return n, io.ErrShortWrite
}

这也是为什么问题通常不在 MultiWriter 本身，而在发生短写的那个 Writer。正确修复应优先落在底层实现：要么完整消费 p，要么在无法完整写入时返回清楚的错误。

内部为什么必须立即停

MultiWriter 提供的是“按顺序复制同一次写入”的语义，不是多目标事务。当前目标已经没有完整接收 p，如果继续写后面的目标，调用方看到的返回值就更难解释：到底哪些目标完整、哪些目标部分、哪些目标失败？立即停止至少把故障边界限制在当前位置。

目标顺序如何改变副作用范围

目标顺序会影响“谁已经被写入”，却无法制造原子性。把关键持久化目标放在前面，意味着后面的可选目标失败时，关键数据可能已经落盘，但整体仍返回错误；把关键目标放在后面，则可能因为前面的目标短写而永远到不了关键目标。

因此顺序要按失败优先级、幂等性和可补偿能力来定，而不是寻找一个所谓绝对安全的位置。凡是要求“要么全部成功，要么全部不写”的场景，都不应只靠 MultiWriter。

兼容坑：不要直接重试 p[n:]

最危险的补救方式，是拿 MultiWriter 返回的 n，再把 p[n:] 交给同一个 MultiWriter。这个 n 是失败目标的写入数，不代表所有目标都只提交了同样的前缀。

在前面的示例里，第一个目标已经收到完整的 abcdef，而短写目标只收到 abc。如果重试 def，第一个目标会变成 abcdefdef；数据不仅没有对齐，反而产生重复。后续目标是否收到数据，还取决于短写目标在第二次调用时的表现。

变体一：优先修复发生短写的 Writer

如果底层资源支持循环写入，应在该 Writer 内部把短写补齐，并保留“无进展”保护，避免永久循环。这里的关键是：对外暴露的 Writer 必须遵守统一契约，而不是把不完整状态泄漏给 MultiWriter。

func writeFull(w io.Writer, p []byte) error {
    for len(p) > 0 {
        n, err := w.Write(p)
        if err != nil {
            return err
        }
        if n == 0 {
            // 没有写入任何字节，避免无休止循环
            return io.ErrNoProgress
        }
        p = p[n:]
    }
    return nil
}

注意，这个循环适合封装单个可继续写入的目标；不要把它机械地套在整个 MultiWriter 外层，否则仍会让先前成功的目标重复接收数据。

变体二：需要独立容错时改用自定义广播

日志镜像、指标旁路或多个彼此独立的输出，有时要求“一个失败，其他仍然尝试”。这种需求与 MultiWriter 的立即停止语义不同，可以显式遍历所有目标，并为每个目标保存结果。

type Result struct {
    Index int
    N     int
    Err   error
}

func writeAll(writers []io.Writer, p []byte) []Result {
    results := make([]Result, 0, len(writers))
    for i, w := range writers {
        n, err := w.Write(p)
        if n != len(p) && err == nil {
            // 仍然把无错误短写标准化，便于统一处理
            err = io.ErrShortWrite
        }
        results = append(results, Result{Index: i, N: n, Err: err})
    }
    return results
}

这段实现会继续尝试后续目标，但它不提供原子性，也不会自动补写或回滚。调用方必须明确决定：哪些失败只记录告警，哪些失败要进入重试队列，哪些目标支持幂等补偿。

排查清单

• 先记录每个目标的索引、类型、返回 n 和错误，不只记录 MultiWriter 的总结果。
• 检查自定义 Writer 是否存在 n 却返回 nil 的路径。
• 确认是否有人把返回的 n 当作所有目标一致提交的位置。
• 根据业务选择“立即停止”还是“继续尝试”，不要混用两种失败语义。
• 如果必须全成全败，先写临时介质并在全部成功后提交，或使用业务层事务/补偿机制。

常见问题

WriteString 会绕过短写检查吗？

不会。MultiWriter 的字符串写入路径仍会检查返回长度；底层目标支持 io.StringWriter 时会优先调用 WriteString，但短写仍会变成 io.ErrShortWrite。

把最可靠的 Writer 放第一位就安全吗？

只能改变副作用顺序，不能保证一致性。第一个目标成功后，后续目标仍可能失败，整体调用仍然返回错误。

什么时候继续使用 MultiWriter？

当所有目标都遵守 Writer 契约，并且你接受“任一目标失败就停止后续目标”的语义时，MultiWriter 简洁且合适。需要逐目标容错、重试或事务时，应把这些策略写在更高一层。