Go io.MultiWriter 遇到短写为什么会返回 ErrShortWrite：多路写入与错误核对

把一份响应同时写进文件和审计流时，io.MultiWriter 很方便：调用方只写一次，数据会按顺序交给多个 io.Writer。但它不是“所有目标都成功才返回”的事务组件。只要某个 Writer 写少了字节，或者直接返回错误，外层就必须同时检查 n 和 err，否则日志看似落盘，第二个目标可能只收到半段内容。

io.MultiWriter 遇到短写时会把问题暴露为 io.ErrShortWrite；处理结果时先确认返回字节数是否等于输入长度，再根据错误决定记录失败、停止重试还是走补偿写入。

先准备一个能稳定复现的短写 Writer

这个问题不适合只拿普通文件做演示，因为文件 Writer 通常一次返回完整长度。先写一个受控的测试 Writer，每次只接受输入的前 5 个字节，并故意返回 nil 错误：

type shortWriter struct {
    limit int
    data  []byte
}

func (w *shortWriter) Write(p []byte) (int, error) {
    n := w.limit
    if n > len(p) {
        n = len(p)
    }
    w.data = append(w.data, p[:n]...)
    return n, nil
}

上面只展示了实验对象，正式运行时用标准库的 bytes.Buffer 作为第二个完整 Writer。这里别急着把短写 Writer 修成自动循环写入；我们正是要观察组合器如何处理不符合完整写入约定的目标。

最小调用：同时核对 n 和 err

把实验代码补全后，输入 10 个字节，短写目标只接受前 5 个字节：

package main

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

type shortWriter struct {
    limit int
    data  []byte
}

func (w *shortWriter) Write(p []byte) (int, error) {
    n := w.limit
    if n > len(p) {
        n = len(p)
    }
    w.data = append(w.data, p[:n]...)
    return n, nil
}

func main() {
    partial := &shortWriter{limit: 5}
    complete := new(bytes.Buffer)
    mw := io.MultiWriter(partial, complete)

    n, err := mw.Write([]byte("0123456789"))
    fmt.Printf("n=%d err=%v partial=%q complete=%q\n",
        n, err, partial.data, complete.Bytes())
}

运行结果应当显示 n=5、错误为 short write，而 complete 仍为空。原因很具体：MultiWriter 已经按顺序调用了第一个 Writer，第一个目标没有完整写完且没有报错，组合器立即停止，不会把剩余数据转交给第二个目标。

为什么 nil 错误也会变成 io.ErrShortWrite

io.Writer 的约定是：当 n 时，应返回一个非 nil 错误。自定义 Writer 违反这个约定时，io.MultiWriter 不会把它当成成功，而是把短写转换成 io.ErrShortWrite，让调用方仍然有机会进入失败分支。

这也是检查条件不能只写成 if err != nil 的原因。对组合写入来说，下面的判断更可靠：

payload := []byte("0123456789")
n, err := io.MultiWriter(dstA, dstB).Write(payload)
if err != nil || n != len(payload) {
    // 记录 n、err 和已经确认写入的目标，避免盲目追加重试
    return fmt.Errorf("fan-out write incomplete: n=%d: %w", n, err)
}

如果 err 已经是 io.ErrShortWrite，用 errors.Is 判断更稳妥；有些中间层会在外面再包一层上下文错误。

扩展实验：第二个 Writer 失败时会发生什么

把第一个 Writer 换回 bytes.Buffer，再让第二个 Writer 返回一个明确错误，就能观察另一种边界。第一目标会先完整收到数据，第二目标失败后 MultiWriter 返回失败；这不是回滚，第一目标已经产生了副作用。

type failWriter struct{}

func (failWriter) Write([]byte) (int, error) {
    return 0, errors.New("audit sink unavailable")
}

primary := new(bytes.Buffer)
n, err := io.MultiWriter(primary, failWriter{}).Write(payload)
fmt.Printf("n=%d err=%v primary=%q\n", n, err, primary.Bytes())

可见状态应是主目标有完整内容，而返回值表示组合写入没有完成。若业务要求“主记录和审计记录必须同时成功”，就不能把 MultiWriter 当事务；应为每个目标设计幂等标识、失败补偿或后续对账。

重试前要先处理已经写入的部分

最危险的代码通常不是第一次写，而是拿到错误后直接再次调用 Write。如果第一个目标已经追加了 5 个字节，原样重试可能形成重复前缀；如果第一个目标完整成功、第二个目标失败，再次写入又会让第一个目标重复一整条记录。

更实用的做法是给每条记录带一个业务唯一号，先把各目标的写入结果记下来，再按目标做幂等补偿。对于不可回滚的 Writer，宁可把“主目标已成功、审计目标待补偿”记录成明确状态，也不要用一个无条件重试掩盖部分成功。

常见问题与边界

MultiWriter 会并发写多个目标吗？

不会。它按传入顺序串行调用每个 Writer，因此适合简单扇出，不适合把并行调度、超时和独立重试一起塞进一次 Write。

返回 n 是所有 Writer 实际写入字节数吗？

不要这样理解。它是组合写调用在失败边界上的返回数量，业务仍需结合具体 Writer 的副作用和错误记录判断哪些目标已经收到数据。

所有 Writer 都完整返回，err 还会是 nil 吗？

正常情况下是。只要某个 Writer 返回错误，或返回短写触发 io.ErrShortWrite，组合调用就不会被当作完整成功。

把验收规则留在调用点

这类问题的最小清单只有三项：写入后同时检查 n == len(payload) 和 err == nil；记录 Writer 的顺序与已产生副作用；重试前确认是否需要去重或补偿。io.MultiWriter 解决的是“按顺序转发一次写入”，并没有替调用方提供事务、回滚或重复提交保护。