Go bytes.Buffer.WriteTo 怎样把缓冲内容写入目标流

在 Go 里，bytes.Buffer 已经积累了一段数据时，通常不需要再调用 Bytes() 取切片、自己循环写入。直接调用 WriteTo，就能把缓冲区的未读部分交给目标 io.Writer，并用返回的字节数与错误判断这次交接是否完整。

官方地址：https://pkg.go.dev/bytes#Buffer.WriteTo

最小可靠写法是检查 n 和 err：err == nil 表示目标 Writer 接受了全部未读内容；如果目标 Writer 只写了一部分且没有返回错误，WriteTo 会把它转换为 io.ErrShortWrite，缓冲区还会保留尚未写出的部分。

先认清 WriteTo 的输入与结果

WriteTo 的签名是 func (b *Buffer) WriteTo(w io.Writer) (n int64, err error)。它处理的是 Buffer 的“未读部分”，不是底层数组里所有曾经写入过的字节。若之前已经调用过 Read、Next 或其他会推进读取位置的方法，已经消费的前缀不会再次发送。

返回值里的 n 是实际交给 Writer 的字节数，使用 int64 是为了匹配 io.WriterTo 接口；err 直接反映写入过程遇到的错误。目标 Writer 完整接收后，Buffer 会被重置为空，但底层存储仍可能被保留以便后续复用。

用最小写法把缓冲内容交给 Writer

下面的例子把一段请求内容放进 Buffer，再写入另一个 Buffer。示例刻意保留返回值检查，这样换成文件、网络连接或压缩 Writer 时，判断方式仍然成立。

package main

import (
    "bytes"
    "fmt"
)

func main() {
    var src bytes.Buffer
    // 先积累要交给下游的内容，WriteString 的错误约定为 nil。
    _, _ = src.WriteString("event=ready&id=42")

    var dst bytes.Buffer
    // WriteTo 只处理 src 的未读部分，并返回实际写入字节数。
    n, err := src.WriteTo(&dst)
    if err != nil {
        // 目标 Writer 失败时不要把这次交接当成成功。
        panic(err)
    }
    fmt.Printf("written=%d body=%q remaining=%d\n", n, dst.String(), src.Len())
}

成功路径的重点不是输出字符串，而是三个状态同时吻合：err == nil、n 等于发送前的 Len()，以及源 Buffer 的 Len() 变成 0。把目的地替换成 *os.File、net.Conn 或 bufio.Writer 时，仍应保留同一层错误处理。

如果代码本来就采用 io.Copy，也可以把 Buffer 作为 Reader 传入。Buffer 实现了 io.WriterTo，因此 io.Copy 能识别这个能力；但当你的业务需要明确表达“把这段缓冲交给目标 Writer”时，直接写 WriteTo 更容易阅读。

把短写入和错误留在边界内

io.Writer 的约定是：返回的 n 不应大于输入长度；如果没有错误，通常应该写完输入。bytes.Buffer.WriteTo 会检查这个边界：目标 Writer 返回真实错误时，方法返回已经写出的数量和该错误；目标 Writer 返回的数量小于全部数据但错误为 nil 时，方法返回 io.ErrShortWrite。

这意味着部分写入不能被当成“下一次自动接着写”。WriteTo 已经推进了 Buffer 的读取位置，剩余未写出的内容仍在 Buffer 中。调用方要先记录错误和 n，再决定重试、转入补偿队列或丢弃当前消息，不能无条件重复调用而不考虑目标端是否已经收到前缀。

package main

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

type limitedWriter struct {
    limit int
}

func (w limitedWriter) Write(p []byte) (int, error) {
    // 用受限 Writer 模拟只接受前 limit 个字节的目标边界。
    if len(p) > w.limit {
        return w.limit, nil
    }
    return len(p), nil
}

func main() {
    var src bytes.Buffer
    // 这段数据会被部分写入，便于观察 n、err 和剩余 Len 的关系。
    _, _ = src.WriteString("abcdef")

    n, err := src.WriteTo(limitedWriter{limit: 2})
    if !errors.Is(err, io.ErrShortWrite) {
        // 生产代码应把未知错误继续交给上层，而不是静默吞掉。
        panic(fmt.Sprintf("unexpected result: n=%d err=%v", n, err))
    }
    fmt.Printf("written=%d remaining=%d\n", n, src.Len())
}

真实业务中更常见的是目标 Writer 自己返回一个非空错误，例如连接断开、磁盘写入失败或下游限流。此时优先处理这个原始错误；只有“数量不足但错误为空”这一类情况，才把 io.ErrShortWrite 作为明确的失败原因。

发布前检查缓冲区状态

把 Buffer 当作待发送消息时，建议在交接点明确“谁拥有剩余数据”。WriteTo 成功后，源 Buffer 为空；失败后，Len() 只代表尚未写出的部分，而不是整条原始消息。若重试策略需要完整消息，就要在进入 WriteTo 前保存可重建的业务数据，不能指望失败后从同一个 Buffer 恢复已经写出的前缀。

还要留意三类边界：

• 空 Buffer 调用 WriteTo 不会产生数据，返回的字节数为 0，错误为 nil；这不是一次“发送了空消息”的业务确认。
• 目标是 bufio.Writer 时，WriteTo 成功只代表数据写入了这个缓冲 Writer；是否已经到达文件或连接，还取决于后续 Flush()。
• 一个 Buffer 不应被多个 goroutine 同时读写；需要并发发送时，在业务层转移消息所有权或复制数据，并让单个发送者负责 WriteTo。

可以把下面这张表作为交接点速查：

常见问题

WriteTo 和 Bytes 加 Write 有什么区别？

两者都能把数据交给 Writer，但 WriteTo 直接围绕 Buffer 的未读区间和 WriterTo 接口工作，调用方无需暴露内部字节切片；如果只是一次性把 Buffer 交给目标流，WriteTo 语义更直接。

WriteTo 成功后还能读取原来的内容吗？

不能从同一个 Buffer 的未读区间再次读取，因为成功写入会把它清空。需要审计、重试或签名时，应在发送前保存独立副本或可重建的业务字段。

为什么要检查 n？

因为目标 Writer 可能只接受部分数据。即使错误值没有提供足够信息，n 也能告诉你已经跨过了多少字节的交接边界，是决定重试和补偿范围的重要依据。