bufio.Writer Flush 返回错误时怎么保留写入状态

使用 bufio.Writer 写文件、网络响应或导出流时，真正把缓冲区交给底层 io.Writer 的动作发生在 Flush。如果它返回错误，正确做法不是继续调用 Write 试试看，而是同时保存错误、底层已经接收的字节数和原始数据偏移，再用新的 Writer 重建未完成部分。

官方地址：https://pkg.go.dev/bufio#Writer.Flush

Flush 失败后，当前 bufio.Writer 会记住错误；Buffered() 只能告诉你内部还剩多少字节，不能替代业务侧的重试数据。因此要把原始 payload 保留在 Writer 外部，把“已交给底层 Writer 的偏移”作为可恢复状态。

先把 Flush 错误看成一次状态变化

Flush 会把当前缓冲区写给底层 Writer。Go 标准库的实现会处理三种结果：全部写完时把缓冲长度归零；只写出一部分时移动剩余字节并减少缓冲长度；底层返回错误时把错误保存到 Writer 内部。即使底层返回短写但没有错误，bufio.Writer 也会转换成 io.ErrShortWrite。

这个错误状态是粘性的：后续 Write 和 Flush 会继续返回同一个错误，不应该把同一个实例当作健康 Writer 继续使用。Reset 可以清除错误，但它会丢弃尚未写出的缓冲数据，所以不能拿它当成“重试按钮”。

记录底层 Writer 已接收的字节数

要保留可重试状态，不能只记录 err != nil。下面的包装器把底层 Writer 返回的 n 累加起来。这个数字表示底层 Writer 接收了多少字节，不等同于文件已经完成 fsync，也不代表远端服务已经提交事务。

package main

import (
    "bufio"
    "io"
)

// countingWriter 记录底层 Writer 实际接收的字节数，不改变原始错误。
type countingWriter struct {
    dst      io.Writer
    accepted int64
}

func (w *countingWriter) Write(p []byte) (int, error) {
    // n 由底层 Writer 决定，短写时不能自行把它补成 len(p)。
    n, err := w.dst.Write(p)
    w.accepted += int64(n)
    return n, err
}

type flushState struct {
    accepted int64
    buffered int
    err      error
}

func writeOnce(payload []byte, dst io.Writer) (flushState, error) {
    cw := &countingWriter{dst: dst}
    bw := bufio.NewWriterSize(cw, 8)

    // 保留原始 payload，后续失败时按 accepted 计算重试起点。
    if _, err := bw.Write(payload); err != nil {
        return flushState{accepted: cw.accepted, buffered: bw.Buffered(), err: err}, err
    }
    // Flush 的返回值才代表当前缓冲是否成功交给底层 Writer。
    if err := bw.Flush(); err != nil {
        return flushState{accepted: cw.accepted, buffered: bw.Buffered(), err: err}, err
    }
    return flushState{accepted: cw.accepted}, nil
}

调用方应把 payload、flushState.accepted 和错误一起写入自己的任务状态。buffered 适合诊断当前 bufio 缓冲中还剩多少数据，但它不是完整的重试内容，应用层不能从 bufio.Writer 读取这段私有缓冲区。

重试时要从原始数据重建

如果业务允许换一个目标 Writer，最稳妥的恢复方式是保留原始 payload，并从底层已接收偏移开始切片。失败的那个 bufio.Writer 不再复用；这样既不会触发粘性错误，也不会因为 Reset 丢掉缓冲区中尚未写出的内容。

func retryFromOffset(payload []byte, accepted int64, dst io.Writer) (int64, error) {
    // 偏移必须来自同一份 payload，不能把 Buffered() 当成全局偏移。
    if accepted  int64(len(payload)) {
        return accepted, io.ErrUnexpectedEOF
    }

    cw := &countingWriter{dst: dst}
    bw := bufio.NewWriter(cw)
    // 只把尚未交给新目标的原始字节写入新的缓冲器。
    if _, err := bw.Write(payload[accepted:]); err != nil {
        return accepted + cw.accepted, err
    }
    // 最后的 Flush 仍然必须单独检查，Write 成功不代表已完成输出。
    if err := bw.Flush(); err != nil {
        return accepted + cw.accepted, err
    }
    return accepted + cw.accepted, nil
}

这里的重试前提是：新目标的起点与 accepted 对应，或者业务已经明确按偏移追加。若目标是网络服务，还要把请求幂等键、服务端确认号等信息放进状态；单纯知道本地 Writer 写了多少字节，不能推断服务端是否完成业务提交。

小项目中的验收清单

把上述逻辑放进文件导出或响应生成器时，可以按下面的最小顺序收口：

• 所有 Write 的返回值都被接住，短写和错误不会被忽略。
• 最终显式调用一次 Flush，并把它的错误写入任务状态。
• 失败状态保存原始 payload 或可重新读取的源数据，以及底层接收偏移。
• 重试创建新的 bufio.Writer，不对旧实例调用 Reset 来猜测数据是否还在。
• 把“底层接收”“操作系统写入”“远端业务提交”分开命名，避免把字节数误报成最终成功。

一句话总结：Flush 返回错误后要保留的是业务数据和进度，而不是试图继续拯救已经进入错误状态的 bufio.Writer。Buffered() 用于观察，原始 payload 和偏移量才是恢复依据。

相关问题

Flush 返回 io.ErrShortWrite 时要不要继续 Flush？

同一个 Writer 已经记录错误，继续调用通常只会得到同一错误。先保存状态；是否重试应由应用层使用原始数据和新的目标决定。

Reset 能不能清除 Flush 错误？

可以清除错误，但 Reset 会丢弃未写出的缓冲数据。除非数据已经在业务侧另有副本，否则不要用它代替恢复流程。