Go bufio.Writer Flush 失败时如何把错误传回调用方

给文件、HTTP 响应或导出流套上 bufio.Writer 后，最容易漏掉的不是写入代码，而是最后那次 Flush。前面的 WriteString 可能只是把数据放进内存缓冲区，真正写底层设备时出现的磁盘满、网络断开或短写，往往要到 Flush 才暴露。结论很简单：每次写入都检查返回值，函数结束前显式调用并返回 Flush 的错误。

为什么 Flush 才是最终写入的错误边界

bufio.NewWriter 在调用方和底层 io.Writer 之间增加了一个缓冲域。数据量较小时，Writer.Write 主要完成内存复制；只有缓冲区需要腾空间，或者主动调用 Flush，才会触发底层写入。因此“写函数返回成功”和“目标已经接收全部数据”是两个判断。

官方文档还规定了一个重要边界：底层写入发生错误后，后续写入以及 Flush 都会继续返回这个错误。这个 sticky error 设计能避免调用方把失败状态误当成新的一次成功写入。

正确的错误传递写法：每次写入和 Flush 都检查

把写入过程封装成返回 error 的函数，调用方就不会依赖日志猜测是否成功。下面的代码没有把 Flush 放进一个无返回值的清理函数，而是把它当成业务结果的一部分：

package export

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

func export(w io.Writer, rows []string) error {
    bw := bufio.NewWriter(w)
    for _, row := range rows {
        // 每次写入都检查，防止缓冲区提前落到底层时丢失错误。
        if _, err := bw.WriteString(row + "\n"); err != nil {
            return fmt.Errorf("写入导出内容: %w", err)
        }
    }

    // 最后的 Flush 才提交剩余缓冲，错误必须继续返回给调用方。
    if err := bw.Flush(); err != nil {
        return fmt.Errorf("提交导出内容: %w", err)
    }
    return nil
}

这里的两个错误分支都使用 %w 保留原始错误，调用方可以用 errors.Is 或 errors.As 继续判断。不要只打印错误后返回 nil，否则上层事务、任务状态或 HTTP 响应仍可能被标记为成功。

短写、sticky error 和 defer 的三个边界

第一，Write 或 WriteString 的返回值也要看。对字节切片而言，n 就是短写，通常应与非 nil 错误一起处理；不能只检查“有没有异常日志”。

第二，底层错误出现后，继续写同一个 bufio.Writer 不会恢复底层连接。若确实要换目标，使用 Reset 会丢弃未刷新的缓冲并清除错误，必须确认这些数据已经不再需要。

第三，defer bw.Flush() 适合做兜底清理，却不适合直接承载函数的成功语义。若采用它，至少要用命名返回值接住错误；但在复杂函数里，显式 Flush 更容易让代码审查者看到“提交失败会返回”。

常见问题

Write 返回 nil 还需要 Flush 吗？

需要。只要使用了 bufio.Writer，完成全部写入后就应调用 Flush，才能把剩余缓冲交给底层并获得最终错误。

Flush 失败后再调用一次能解决吗？

通常不能。bufio.Writer 会保存底层错误，后续 Flush 仍会返回该错误；应把它交给调用方，按底层资源类型决定重试或回滚。

什么时候可以忽略 Flush 错误？

只有调用方明确接受“尽力而为”语义时才可能忽略，例如临时诊断输出。文件、导出文件、响应体和持久化数据都不应默认忽略。

实战中可以把规则压缩成一句检查清单：写入点检查一次，提交点 Flush 再检查一次，最终错误沿调用栈返回。这样缓冲带来的性能收益不会变成数据成功性的错觉。