Go bufio.Writer 如何用分层写入定位最终 Flush 错误

排查 Go 文件导出、日志落盘或响应写入时，最容易误判的一种现象是：前面的 Write 都返回成功，最后调用 Flush 却突然失败。这个结果并不矛盾，bufio.Writer 可能只是把数据放进了内存缓冲区，真正的底层写入发生在缓冲区填满或最终刷新时。定位这类问题的关键，是把业务写入层、缓冲层和底层 io.Writer 分开记录。

先把三层写入边界画清楚

一个典型链路是“业务编码器 → bufio.Writer → 底层 io.Writer”。业务层调用的 WriteString、Write 或格式化输出，先进入缓冲区；只有缓冲区空间不够、显式调用 Flush，或者某个写入路径主动触发刷新时，数据才会交给底层 writer。

因此，n == len(p) 只能说明这次数据被 bufio.Writer 接收了。它不能证明文件已经落盘、网络已经发送，甚至不能证明底层 writer 已经被调用。官方文档也明确要求：所有数据写完后调用 Flush，才能保证缓冲数据被转发。

用两处日志区分 Write 错误和 Flush 错误

排障时至少记录四个字段：调用位置、请求字节数、返回字节数、错误值；在 Flush 前再记录一次 Buffered()。这样能看出错误出现前是否还有数据停留在缓冲层。

package main

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

// failWriter 在写到 limit 字节后返回固定错误，用来模拟磁盘或网络失败。
type failWriter struct {
	limit int
	used  int
	err   error
}

func (w *failWriter) Write(p []byte) (int, error) {
	// 第一次失败后保持错误，便于调用方识别根因而不是被后续错误覆盖。
	if w.err != nil {
		return 0, w.err
	}
	left := w.limit - w.used
	if left  left {
		w.used += left
		w.err = io.ErrShortWrite
		return left, w.err
	}
	w.used += len(p)
	return len(p), nil
}

func writeReport(dst io.Writer, text string) error {
	// 缓冲层只负责聚合写入，最终交付必须检查 Flush 返回值。
	bw := bufio.NewWriterSize(dst, 16)
	if n, err := bw.WriteString(text); err != nil {
		return fmt.Errorf("业务 Write 失败，n=%d: %w", n, err)
	} else {
		fmt.Printf("业务 Write: n=%d buffered=%d\n", n, bw.Buffered())
	}
	if err := bw.Flush(); err != nil {
		return fmt.Errorf("最终 Flush 失败，buffered=%d: %w", bw.Buffered(), err)
	}
	return nil
}

当字符串长度小于 16 字节时，底层 failWriter 可能直到 Flush 才收到数据，因此错误会出现在“最终 Flush”。如果一次写入超过缓冲区，bufio.Writer 会尝试把部分数据交给底层，错误也可能在业务 WriteString 返回。

用 Buffered 和返回字节数缩小故障范围

日志不要只写“Flush failed”。在每个业务块之后记录 Buffered()：数值持续增加，说明数据仍停留在内存；数值突然下降，说明发生过一次向底层的刷新。若同时看到 n ，优先检查底层 writer 的短写契约、磁盘空间、连接关闭和超时。

注意：Flush 返回成功也只代表底层 io.Writer 接受了数据。若底层是带独立提交语义的对象，还要按它自己的接口检查提交或关闭结果，不能把 bufio 的成功扩大解释成业务事务成功。

收口第一次错误，别用 Reset 掩盖失败

一旦某次写入或 Flush 出错，先停止追加数据并保留原始错误。官方文档说明，bufio.Writer 在底层写入出错后不再接受新数据，后续写入和 Flush 会继续返回该错误。此时直接调用 Reset 只会清理缓冲状态和错误标记，不会让已经失败的磁盘写入或网络发送重新成功。

实践中可以把“写临时文件、Flush、关闭、原子改名”作为一条明确的成功链：任一步失败就删除临时文件并返回第一次错误；网络响应则在 Flush 成功前不要写入“已完成”状态。对于可重试场景，重新创建底层 writer 和缓冲层，再从可靠的业务边界重放，而不是复用已经记录错误的 bufio.Writer。

相关问题

为什么每次 Write 都成功但文件内容不完整？

最常见原因是遗漏了最终 Flush，或者只检查了格式化函数的返回值。把 Flush 放进明确的收尾路径，并记录它的错误。

Flush 失败后还能继续 Write 吗？

不建议继续写。底层错误会被缓冲 writer 保留，后续操作通常只会重复返回同一错误；应停止当前任务，保留根因并按业务边界重新开始。

参考：Go bufio 官方包文档，其中定义了 Writer.Write、Writer.Flush、Writer.Buffered 以及底层错误传播规则。