Go csv.Writer Flush 后为什么还要检查 Error

Go 的 encoding/csv.Writer 会先把记录写入内部缓冲区，所以 Write 返回 nil，并不等于所有字节已经抵达文件、HTTP 响应或网络连接。Flush 负责把缓冲内容交给底层 io.Writer，但它本身没有 error 返回值；正确做法是紧接着调用 Writer.Error()。如果只写 Flush() 就返回成功，底层磁盘满、连接断开或响应写入失败都可能被漏掉。

Flush 之后检查 Error，检查的到底是哪一步

csv.Writer 内部使用带缓冲的 Writer。每次 Write(record) 会完成 CSV 转义、分隔符和换行符的组织，并尽量写进缓冲区；缓冲区装满时，也可能提前向底层 Writer 刷一部分数据。因此，Write 的 error 需要检查，但它只代表当前调用已经观察到的错误。

Flush 会把尚未下发的尾部数据继续写给底层 io.Writer。这个 API 没有返回值，标准库把刷新的错误保存在内部状态里，再由 Error() 取出。也就是说，下面三行是一个整体，不能省略最后一行：

writer.Flush()
if err := writer.Error(); err != nil {
    return err
}

生产代码怎样把 Flush 错误传回调用方

导出函数应把行号、输出阶段和原始错误一起返回，调用方才能区分“第几行编码失败”和“全部记录已经编码但最终刷新失败”。下面的写法不依赖文件同步，也不会把 CSV 刷新误认为持久化完成：

package export

import (
    "encoding/csv"
    "fmt"
    "io"
)

func writeCSV(dst io.Writer, rows [][]string) error {
    w := csv.NewWriter(dst)
    for rowIndex, row := range rows {
        // Write 负责当前记录的转义与缓冲，先保留行号便于排障。
        if err := w.Write(row); err != nil {
            return fmt.Errorf("写入 CSV 第 %d 行失败: %w", rowIndex+1, err)
        }
    }

    // Flush 没有返回值，底层写失败要从 Writer.Error 读取。
    w.Flush()
    if err := w.Error(); err != nil {
        return fmt.Errorf("刷新 CSV 输出失败: %w", err)
    }
    return nil
}

如果目标是 *os.File，这里的成功只说明 csv.Writer 已把数据交给文件 Writer；是否需要 File.Sync、临时文件改名或目录级替换，要由更外层的交付策略决定。对于 HTTP 响应和网络流，也应把下游 Writer 的失败作为导出失败处理，而不是仅凭内存中已经生成了记录就返回成功。

Write、Flush 和 Error 的排查清单

遇到“CSV 文件看起来生成了，但内容少了几行”时，先按调用边界排查。不要先改分隔符或字符编码，因为这些设置解决的是格式问题，不会替代错误传播。

批量导出时可以直接使用 WriteAll

当记录已经在内存中，WriteAll 会依次调用 Write，最后执行刷新，并把刷新错误作为返回值返回。它适合短小的批量导出，但仍建议保留带业务上下文的包装：

func writeAllCSV(dst io.Writer, rows [][]string) error {
    w := csv.NewWriter(dst)

    // WriteAll 内部会 Flush，返回值包含记录写入或最终刷新的错误。
    if err := w.WriteAll(rows); err != nil {
        return fmt.Errorf("批量导出 CSV 失败: %w", err)
    }
    return nil
}

如果需要边读数据库边导出，不要为了使用 WriteAll 把所有记录先堆进内存；逐行 Write、结束时 Flush 加 Error 更适合流式场景。无论哪种写法，都不要吞掉错误后继续宣称文件可下载。

常见问题

只调用 Writer.Write，不调用 Flush 会怎样？

记录可能仍停留在内部缓冲区，底层输出不完整。除非使用会替你收尾的封装，否则应在最后一条记录后显式刷新并检查错误。

Flush 返回不了 error，为什么 Error 能拿到？

csv.Writer 把底层缓冲 Writer 的错误保存在内部状态中，Error 负责读取这个状态。因此 Flush 和 Error 是配套 API。

WriteAll 后还要再调用 Flush 吗？

通常不需要。WriteAll 已经执行最终刷新并返回错误；重复刷新不能修复已经发生的底层写入失败，应该优先处理返回值。

把 Flush 和 Error 看成同一个收尾动作，能让 CSV 导出在文件、HTTP 和网络流之间保持一致的错误语义。至于同步和原子替换，则继续由输出层的交付策略负责。