Go bufio.Writer.Flush 遇到短写怎么办：缓冲区状态与错误恢复边界

日志导出时，bufio.Writer 往往把多次小写入合成一次底层写入。真正麻烦的是底层 io.Writer 只接收了一部分字节：Flush 返回错误后，缓冲区里还可能留着未发送的数据，继续调用 Write 也不会自动恢复。

遇到短写时先保存 Flush 的错误并停止继续写；只有换到一个明确可用的新底层 Writer，再用 Reset 丢弃旧缓冲区并重新生成数据，才是清晰的恢复边界。

先把短写现场固定下来

下面的 shortWriter 故意只接受前 5 个字节，并且返回 nil 错误，模拟一些实现不规范但真实存在的短写情况。缓冲器使用 8 字节容量，方便让状态变化可见。

package main

import (
    "bufio"
    "fmt"
    "io"
)

type shortWriter struct {
    accepted int
}

func (w *shortWriter) Write(p []byte) (int, error) {
    n := len(p)
    if w.accepted+n > 5 {
        n = 5 - w.accepted
    }
    if n 

运行结果的关键不是具体打印格式，而是三个事实：底层只接收 5 字节，Flush 返回 io.ErrShortWrite，Buffered 仍然大于 0。这就是第一张图要表达的真实因果链。

Flush 为什么会记住错误

Go 官方 bufio.Writer.Flush 的实现先调用底层 io.Writer.Write。如果返回的字节数小于缓冲长度而错误仍为空，代码会补成 io.ErrShortWrite；若确实只写了一部分，剩余内容会前移到缓冲区开头，然后把错误写入 b.err。

因此，短写不是“再 Flush 一次就能续传”的信号。后续调用首先命中 b.err，直接返回同一个错误。这样做是为了避免调用方误以为数据已经完整落到底层目标。

把错误传播写进调用边界

func writeRecord(dst io.Writer, record string) error {
    bw := bufio.NewWriterSize(dst, 64)
    if _, err := bw.WriteString(record); err != nil {
        return err
    }
    if err := bw.Flush(); err != nil {
        return fmt.Errorf("flush record: %w", err)
    }
    return nil
}

这里把 Flush 当成提交点：写入缓冲区成功，只代表数据进入内存；Flush 成功，才代表这批数据已经交给底层 Writer。图中的 b.err 一旦进入错误状态，调用链就应该向上返回，而不是继续制造新记录。

新写法：区分重试与重新生成

如果底层目标只是临时不可用，不能对原来的 bufio.Writer 盲目重试。先判断底层 Writer 是否已经明确失效，再决定是否创建新的 Writer。对旧实例调用 Reset 会清空未刷出的数据，所以它适合“旧批次可以丢弃、准备重新生成”的场景。

func retryWithNewWriter(open func() (io.Writer, error), record string) error {
    next, err := open()
    if err != nil {
        return err
    }
    bw := bufio.NewWriterSize(next, 64)
    if _, err = bw.WriteString(record); err != nil {
        return err
    }
    return bw.Flush()
}

若业务要求“一个字节都不能丢”，应把 record 或可重放的原始事件保存在调用方，再用新的底层 Writer 重新生成；不要把旧缓冲区当成可靠的重试队列。若数据允许丢弃，才可以明确记录丢弃原因后调用 Reset 回收对象。

第二张图把这个边界画成两条路径：Flush 返回 io.ErrShortWrite 后停止旧链路；可重放数据进入新 bufio.Writer，成功后再提交。

迁移检查：把隐藏的丢数风险找出来

• 搜索所有 bufio.NewWriter 和 NewWriterSize，确认每条正常路径都检查 Flush 返回值。
• 检查 defer bw.Flush() 是否吞掉错误；文件导出和网络响应尤其不应只依赖无返回值的清理函数。
• 给底层 Writer 写一个可控短写替身，验证 Buffered、io.ErrShortWrite 和上层错误包装。
• 决定失败后是重放原始记录，还是明确丢弃；不要把 Reset 当成自动续传。

相关问题

Flush 没有错误是不是已经写入磁盘？

不是。它只把数据交给底层 io.Writer；如果底层是文件，还要按文件系统语义决定是否需要额外的同步操作。

短写但底层返回 nil 为什么会得到 io.ErrShortWrite？

这是 bufio.Writer 对不完整写入的保护：请求长度没有全部完成时，空错误会被补成 io.ErrShortWrite。

可以继续调用原来的 Write 吗？

不应把它当成可恢复写入。错误已经记录在 b.err 中，后续写入仍会返回该错误；先保存可重放数据并更换底层目标。

最后的验收标准

一段可靠的缓冲写入代码，至少能回答三件事：谁负责检查 Flush，短写后哪些字节仍未发送，以及失败时原始数据从哪里重放。把这三点写进测试和错误日志，远比在末尾补一个忽略返回值的 defer 更稳妥。