Go MultiWriter 怎样理解多目标写入错误

把同一段日志同时写入文件、标准输出和审计流时，很多人会把 io.MultiWriter 想成“所有目标都尝试一次”的广播器。实际语义更严格：它按传入顺序逐个调用目标；某个目标返回错误后，本次 Write 立即停止，后面的目标不会被调用。因此它适合“前置写入成功后再继续复制”的链路，不适合直接承担全目标尽力写入或事务回滚。

先看 MultiWriter 的实际写入边界

标准库把每次写入拆成一个很清楚的边界：对每个目标调用一次 Write(p)，如果返回错误就原样返回；如果返回的字节数不是 len(p)，则返回 io.ErrShortWrite。只有当前目标完整接收数据，才会进入下一个目标。

这个顺序意味着“前面已成功、后面未执行”是正常状态。例如文件目标已经写入，网络目标报错，那么文件不会自动回滚，后面的审计目标也不会得到这份数据。调用方需要把它当成部分成功来处理，而不是把一次返回值解读成全有或全无。

用一个失败 Writer 还原返回值

下面的示例让第二个目标只接受部分字节并返回自定义错误。它没有调用第三个目标，返回的 n 是第二个目标报告的字节数，而不是前两个目标写入字节数的总和。

package main

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

var errArchiveDown = errors.New("archive is unavailable")

type partialWriter struct {
	name string
}

func (w partialWriter) Write(p []byte) (int, error) {
	// 模拟目标只接收前半段；真实实现应返回已经接收的字节数和具体错误。
	return len(p) / 2, errArchiveDown
}

func main() {
	var primary, audit strings.Builder
	fanout := io.MultiWriter(&primary, partialWriter{name: "archive"}, &audit)

	n, err := fanout.Write([]byte("event-001"))
	fmt.Printf("n=%d err=%v primary=%q audit=%q\n", n, err, primary.String(), audit.String())
	if errors.Is(err, errArchiveDown) {
		// 记录部分成功；不要把未调用的 audit 当成已经写入。
		fmt.Println("archive failed; audit was not called")
	}
}

这个例子中，primary 已经得到完整内容，partialWriter 返回一半字节和错误，audit 保持为空。若目标返回 n 但 err == nil，MultiWriter 会把错误改成 io.ErrShortWrite；调用方仍然应该把这次写入视为失败。

生产场景怎样安排目标顺序与补偿

如果文件是主要落盘结果，通常把它放在前面；但顺序不是可靠性保证，只决定谁先尝试。更重要的是在调用处明确记录目标状态：主文件成功、归档失败时，记录待补偿任务；归档成功后再写审计，也要接受审计目标可能失败。

如果业务要求“每个目标都尽力写入”，就不要只包一层 MultiWriter。可以逐个调用目标，保存每个目标的独立结果，并对失败目标执行带幂等键的重试。多目标写入没有通用回滚协议，文件、网络连接和日志流也往往不能一起回滚。

type result struct {
	name string
	err  error
}

func writeAll(p []byte, targets map[string]io.Writer) []result {
	results := make([]result, 0, len(targets))
	for name, target := range targets {
		// 每个目标单独记录结果；是否重试由上层按目标类型决定。
		_, err := target.Write(p)
		results = append(results, result{name: name, err: err})
	}
	return results
}

这个替代方案不再提供固定顺序，也不保证并发安全；它换来的是“后面的目标仍会尝试”。实际项目应使用稳定的切片而不是 map，并根据目标重要性决定串行、并行、重试和告警方式。

常见误区与速查

最后可以记住一句话：io.MultiWriter 的“多目标”描述的是复制对象，不是失败隔离。只要把每个目标的顺序、部分成功和补偿责任写进调用方，返回值就不会再被误读。

延伸问题

MultiWriter 会并发写多个目标吗？

不会。标准实现按参数顺序串行调用；需要并发时要自行设计同步、错误汇总和资源生命周期。

目标返回短写但没有错误怎么办？

MultiWriter 会返回 io.ErrShortWrite。这不是成功状态，应该按目标未完整接收处理。