Go encoding/csv 写入成功后为什么还要检查 Writer.Error

csv.Writer 写入成功后仍要检查 Writer.Error()，因为 Write 默认只把 CSV 记录写进内部缓冲区，真正向底层 io.Writer 发送数据通常发生在 Flush。稳妥顺序是：逐条检查 Write，全部记录完成后调用 Flush，最后检查 Error。如果漏掉最后一步，导出函数可能把只写出一部分的 CSV 当成成功结果。

先还原现场：为什么 Flush 返回了却不能说明成功

很多 CSV 导出代码最后只有两行：调用 Flush，然后直接返回 nil。问题在于 Flush 的签名没有返回 error，它把错误留在 Writer 内部，调用方必须再读取 Error。

可以把一次导出拆成三个阶段：记录编码、缓冲刷新、结果确认。前两个阶段都可能遇到错误，最后的确认阶段才负责把它们汇总到调用方。下面这张结构说明图展示的是 API 职责关系，不是运行截图。

Write 成功只说明记录处理到了某个阶段

Writer.Write(record) 会按 CSV 规则处理字段和必要的引号，并将结果写入内部缓冲。它返回的 error 仍然要检查，因为分隔符配置非法或当前底层写入动作已经失败时，调用方需要立刻停止继续写入。

但即使每次 Write 都返回 nil，也不能把它理解成“文件已经完整写好”。缓冲区里还有数据时，目标 io.Writer 可能根本没有收到最后一批字节。

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

    for rowIndex, record := range records {
        // 每条记录单独检查，避免错误后继续制造更多无效输出。
        if err := w.Write(record); err != nil {
            return fmt.Errorf("写入第 %d 条记录失败: %w", rowIndex+1, err)
        }
    }

    // Write 只保证数据进入 Writer 的处理流程，最后必须主动刷新缓冲。
    w.Flush()

    // Flush 没有 error 返回值，刷新阶段的错误从 Writer.Error 读取。
    if err := w.Error(); err != nil {
        return fmt.Errorf("刷新 CSV 缓冲失败: %w", err)
    }
    return nil
}

这段写法的关键不在于把 Flush 放到末尾，而在于把 Flush 与 Error 看成一个不可拆开的收尾动作。只调用前者，相当于只发起了最后一次写入尝试，却没有读取结果。

Writer.Error 负责收集 Write 和 Flush 的错误

官方文档对 Error 的定义很直接：它报告此前 Writer.Write 或 Writer.Flush 期间发生的错误。它不是对目标文件重新读取，也不是对 CSV 内容做语义校验，而是读取 csv.Writer 已经保存的写入错误。

因此，错误处理应该遵循两个边界：能从 Write 直接拿到的错误立即返回；没有返回值的 Flush 则必须紧跟 Error。如果第一处错误已经确定，后续不应继续把更多记录写到同一个失败的 Writer 上。

用 WriteAll 时，最后仍然要检查 Error

如果不需要逐条统计行号，可以使用 WriteAll 简化流程。官方实现会先写入所有记录，然后调用 Flush，并把刷新错误作为返回值交给调用方。不过在实际使用中，仍建议检查 Writer.Error，这样代码的成功条件始终统一，也能覆盖 Writer 内部记录的错误状态。

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

    // WriteAll 会写入全部记录并在内部调用 Flush。
    w.WriteAll(records)

    // 统一从 Writer.Error 确认整个导出流程是否完成。
    if err := w.Error(); err != nil {
        return fmt.Errorf("导出 CSV 失败: %w", err)
    }
    return nil
}

这里没有把 WriteAll 的返回值写成单独变量，是因为该方法本身没有返回值；最终判断点仍然是 w.Error()。如果需要知道哪一行出错，就改用逐条 Write 的版本。

把导出函数的成功条件写完整

一个 CSV 导出函数真正可以返回成功，至少要同时满足三件事：所有记录都被接受、缓冲数据已经向底层 Writer 刷新、Writer 没有记录错误。可以用下面的清单做代码审查：

• 是否检查了每次 Write 的返回值，或者明确使用了 WriteAll？
• 逐条写入时是否调用了 Flush，并紧跟 Error？
• 使用 WriteAll 时是否仍然检查了 w.Error()？
• 发生错误后，调用方是否把目标文件或响应标记为失败，而不是继续宣称导出成功？

这套边界只讨论 csv.Writer 能报告的写入错误。文件权限、磁盘空间、网络对象存储等具体原因仍由底层 io.Writer 决定；本文的重点是不要在错误已经被 Writer 保存后把它静默丢掉。

常见问题

Flush 为什么没有返回 error？

csv.Writer 的 API 把刷新错误保存在 Writer 内部，通过 Error() 读取。调用者要把 Flush 和紧随其后的 Error 当作一个完整动作。

每次 Write 都成功，还能不调用 Flush 吗？

不能。单条写入是缓冲的，不调用 Flush 就不能保证数据已经转发到底层 io.Writer。

WriteAll 后还需要自己调用 Flush 吗？

通常不需要，WriteAll 会在内部调用 Flush；但仍要检查 w.Error()，并根据需要把错误返回给上层。