Go bufio.Writer Flush 为什么只返回第一次写入错误

很多做Go开发的朋友在用bufio.Writer做带缓冲写入时，常会碰到Flush返回的错误只会对应第一次写入异常的情况，哪怕后续还出现了其他写入错误，调用Flush也只会返回最早的那一次错误，这不是bug，是标准库特意做的状态设计。

bufio.Writer 并不是每次 Flush 都重新向底层尝试写入。它一旦遇到底层 io.Writer 返回错误，就会把该错误保存在内部；后续 Write 或 Flush 会直接返回这项错误。因此看到的“第一次错误”是有意保留的故障状态，不是新错误被吞掉。

先处理第一次写入错误，再决定是否更换目标并重建完整数据。不要在同一个 Writer 上反复 Flush，期待它自动恢复。

第一次错误为什么会被记住

Writer 内部同时维护缓冲区、已缓冲字节数、底层目标和错误字段。只要错误字段非空，Flush 会直接返回它；写入方法也会停止正常推进。这样能保留最接近故障源的原因，避免后续调用用次生错误覆盖它。

这也解释了一个常见错觉：前几次 WriteString 可能返回成功，因为数据只是进入内存缓冲区；真正访问底层目标的时刻，可能是缓冲区装满，也可能是显式调用 Flush。

部分写入后，缓冲区里还剩什么

执行 Flush 时，底层 Write 可能只接收一部分字节。如果返回数量小于待写数量且错误为空，bufio 会把它转换为 io.ErrShortWrite；如果同时返回错误，已经写出的前缀不能撤回，未写尾部会被移到缓冲区前部，并保存该错误。

// 底层 Writer 允许返回 n 

这段代码用于说明接口边界，并不是 bufio 的完整实现。关键判断是：目标中可能已经存在前缀，而 Writer 中还保留尾部；此时直接重放完整消息，可能产生重复内容。

写入和 Flush 应该怎样检查

把写入错误与最终刷新错误都返回给调用方，不要只写一个 defer w.Flush() 后忽略结果。若底层对象还需要关闭，也要单独处理 Close；Flush 只负责把缓冲数据交给底层 io.Writer。

func writeReport(dst io.Writer) error {
    w := bufio.NewWriter(dst)

    if _, err := w.WriteString("name,total\n"); err != nil {
        return fmt.Errorf("写入表头: %w", err)
    }
    if _, err := w.WriteString("demo,42\n"); err != nil {
        return fmt.Errorf("写入数据: %w", err)
    }
    if err := w.Flush(); err != nil {
        return fmt.Errorf("刷新缓冲区: %w", err)
    }
    return nil
}

如果多次写入中途已经返回错误，就立即停止组织后续内容；最终 Flush 仍要检查，因为最后一批数据可能到这里才真正触达目标。

Reset 能清错，但不能撤回已写数据

Reset(newDst) 会丢弃未刷新的缓冲数据、清空错误，并让 Writer 指向新目标。它适合对象池复用或明确切换到全新的输出目标，不适合把未知状态的原目标当作“接着写”的重试入口。

常见问题

连续调用两次 Flush 会再次写未完成的尾部吗？

不会自动恢复。第一次失败后错误已被保存，第二次 Flush 会直接返回同一错误。需要由上层决定放弃、重建或按协议重试。

Flush 成功后还要检查 Close 吗？

要。文件、压缩器或网络对象的 Close 可能执行额外提交并返回自己的错误；bufio.Writer.Flush 不会替你关闭底层目标。