Go 怎样把一份输出同时写入多个目标

在 Go 里，如果调用方已经拿到一段字节，想把它同时交给文件、内存缓冲区和摘要计算器，没必要为每个目标重复写一套分发代码。io.MultiWriter 会把多个 io.Writer 组合成一个 Writer，一次 Write 按传入顺序逐个调用这些目标。

最重要的边界是：MultiWriter 是同步、顺序的多写。某个目标返回错误，或者返回的字节数少于请求长度，当前写入就停止，排在后面的目标不会再被调用；前面目标已经写入的内容也不会自动回滚。

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

本文只讨论 io.MultiWriter 的写入顺序与失败行为，不把它扩展成异步 fan-out、消息队列或带重试的分发组件。

先明确多个输出的接口边界

io.MultiWriter 接收可变数量的 io.Writer，返回值仍然是一个 io.Writer。这意味着调用方只需要面向一个写入入口，具体目标由组合层保存。

它适合“同一份字节需要同步留下多个副本”的场景，例如把日志同时写到文件和内存缓冲区，或把传输内容交给一个落盘目标和一个摘要计算器。目标本身只要实现 Write([]byte) (int, error) 即可。

最小写法：一次输出写入两个目标

下面的例子让一份文本同时写入 bytes.Buffer 和另一个缓冲区。真实项目中，第二个目标可以替换为文件、网络连接或哈希对象；示例重点是组合顺序和错误处理。

package main

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

func main() {
	var fileLike bytes.Buffer
	var memoryCopy bytes.Buffer

	// 目标顺序就是当前 Write 的调用顺序。
	writer := io.MultiWriter(&fileLike, &memoryCopy)

	// 一次 Write 会把同一段字节同步交给两个目标。
	n, err := io.WriteString(writer, "order=2026-10-17\n")
	if err != nil {
		// 错误可能来自任意一个底层 Writer。
		panic(err)
	}

	fmt.Printf("写入字节数=%d\n", n)
	fmt.Printf("目标一=%q\n", fileLike.String())
	fmt.Printf("目标二=%q\n", memoryCopy.String())
}

调用方不需要先写第一个目标，再写第二个目标。io.WriteString 最终仍然通过 Writer 接口完成一次写入，MultiWriter 负责把它按顺序转发出去。

写入顺序由参数顺序决定

MultiWriter 不会并发调用目标，也不会根据目标类型重新排序。传入 io.MultiWriter(a, b, c) 后，当前写入会先交给 a，再交给 b，最后交给 c。因此，如果目标之间存在顺序要求，应把顺序直接写在构造函数参数里。

这个顺序也影响故障范围：排在前面的目标更早收到数据，排在后面的目标可能因为前面失败而完全没有机会执行。它不是事务提交，不会在后一个目标失败时撤销前一个目标的写入。

某个目标出错后，后续目标不会继续

标准库的行为是逐个调用目标；只要某个 Writer 返回非空错误，MultiWriter 就立即返回这个错误，不再继续调用列表中的后续目标。调用方收到的 n 是发生错误的那个目标返回的字节数，不能理解成所有目标的统一提交进度。

package main

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

type failWriter struct {
	name string
}

func (w failWriter) Write(p []byte) (int, error) {
	// 模拟磁盘、网络目标或配额限制导致的写入失败。
	return 0, errors.New(w.name + " 不可写")
}

func main() {
	var first bytesBuffer
	second := failWriter{name: "目标二"}
	var third bytesBuffer

	writer := io.MultiWriter(&first, second, &third)
	_, err := writer.Write([]byte("payload"))
	if err != nil {
		// 目标一可能已经写入，目标三不会被调用。
		fmt.Println("多目标写入失败:", err)
	}
}

// bytesBuffer 只用来表达一个可写目标的占位实现。
type bytesBuffer struct{}

func (*bytesBuffer) Write(p []byte) (int, error) {
	// 这个目标完整接受输入，便于突出调用顺序。
	return len(p), nil
}

上面的占位 Writer 省略了实际存储，只用于说明调用边界。生产代码应保留每个目标的真实错误上下文，必要时记录目标名称、返回字节数和是否需要人工补偿。

短写会被转换成 io.ErrShortWrite

按照 io.Writer 约定，目标返回的字节数少于输入长度时应同时返回错误。如果目标错误地返回“少写但没有错误”，MultiWriter 会把它视为短写，并返回 io.ErrShortWrite，随后停止后续目标。

package main

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

type shortWriter struct{}

func (shortWriter) Write(p []byte) (int, error) {
	// 故意模拟违反 Writer 约定的短写，用于观察 MultiWriter 的保护行为。
	return len(p) / 2, nil
}

func main() {
	writer := io.MultiWriter(shortWriter{}, io.Discard)
	n, err := writer.Write([]byte("abcdef"))
	if errors.Is(err, io.ErrShortWrite) {
		// 短写不是成功写入，后续目标也不会继续执行。
		fmt.Printf("短写: n=%d, err=%v\n", n, err)
	}
}

这里的 io.Discard 位于失败目标之后，因此不会收到这次写入。遇到短写时，不要只判断 n > 0 就把整次操作当成成功；应优先处理错误，再决定是否重新组织数据或补写。

把同一份输出写到文件和摘要目标

一个常见组合是“正文落盘 + 同步计算摘要”。文件目标和哈希目标都实现了 io.Writer，所以可以放进同一个 MultiWriter。需要注意，摘要对象通常只接受字节并更新内部状态，它不是第二份可读取正文。

package main

import (
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"strings"
)

func main() {
	var stored strings.Builder
	hasher := sha256.New()
	writer := io.MultiWriter(&stored, hasher)

	// 一次写入同时更新正文目标和摘要目标。
	count, err := io.WriteString(writer, "stream payload")
	if err != nil {
		// 任意目标失败都必须由调用方决定是否放弃这次输出。
		panic(err)
	}

	// 摘要只从 hasher 读取，正文仍在 stored 中。
	digest := hex.EncodeToString(hasher.Sum(nil))
	fmt.Printf("写入字节数=%d\n正文=%s\n摘要=%s\n", count, stored.String(), digest)
}

如果文件写成功但摘要目标失败，文件中可能已经留下内容；反过来也一样。因此需要完整一致性时，不能把 MultiWriter 当作事务层，应在上层设计临时文件、补偿记录或重新生成策略。

哪些场景适合，哪些场景应该拆开

选择它的前提是：同步等待多个目标是可以接受的，而且调用方能够处理“前面的目标已写、后面的目标未写”的部分成功状态。

常见问题

MultiWriter 会并发写多个目标吗？

不会。它按参数顺序逐个调用目标，调用方会等待当前 Write 返回。需要异步解耦时，应单独设计队列、缓冲容量和失败处理。

第二个目标失败后，第一个目标会自动回滚吗？

不会。MultiWriter 只负责转发和返回错误，不知道目标如何撤销内容。需要一致性时，要在调用方使用临时文件、事务接口或补偿动作。

为什么返回的 n 不能代表所有目标都写了 n 个字节？

因为写入可能在某个目标处停止。返回值描述的是本次停止点的结果，不是对所有目标做出的提交证明；后续目标甚至可能没有被调用。

目标列表为空时会怎样？

空列表没有可调用的底层目标。若业务逻辑要求至少一个输出，应在构造 MultiWriter 前由调用方明确检查，而不要把空组合误当成成功落盘。

小结

io.MultiWriter 把一个 Writer 入口连接到多个输出目标，核心语义可以记成三句话：按传入顺序写入；任一错误或短写都会停止后续目标；已经写入的目标不会自动回滚。理解这三个边界后，它就适合用于同步日志镜像、正文与摘要并写等简单组合，也能避免把它误用成事务、异步队列或独立重试系统。