Go encoding/csv Writer.Error 怎么发现导出文件写入失败

CSV 导出最容易漏掉的一类错误，不是在调用 Write 的那一刻出现，而是在缓冲内容真正交给文件、网络响应或其他 io.Writer 时才暴露。Go 的 encoding/csv 会先缓存记录，因此“每次 Write 都返回 nil”不等于最终文件一定写成功。

官方文档：https://pkg.go.dev/encoding/csv#Writer.Error

这篇文章只解决一个问题：怎样把 Write 的即时错误、Flush 的延迟错误和 Writer.Error 的收尾检查放在正确位置。核心做法是：逐条写入时检查 Write，全部写完后调用 Flush，最后再调用 Error。

先分清 Write、Flush 与 Error 的职责

csv.Writer 内部包着一个缓冲写入器。Write 负责把一条记录编码成 CSV 并写入内部缓冲；只有 Flush 才会尝试把缓冲内容交给底层 io.Writer。因此，错误可能分成两段：记录编码或缓冲写入阶段的错误，以及真正写文件或写响应阶段的错误。

官方源码明确说明，单条记录写入是有缓冲的，完成全部数据后应调用 Flush，然后通过 Writer.Error 检查此前 Write 或 Flush 发生的错误。也就是说，Error 不是“再写一遍”，而是读取 Writer 保存的错误状态。

把 Writer.Error 放在导出收尾

一个可复用的导出函数应该把成功条件写完整：没有一条 Write 失败，Flush 已经执行，且 Error 返回 nil。下面的代码让错误在正确的层级返回给调用方。

package report

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

// WriteCSV 负责把记录写入目标，并把缓冲刷新错误返回给调用方。
func WriteCSV(dst io.Writer, records [][]string) error {
    w := csv.NewWriter(dst)

    for index, record := range records {
        // Write 失败表示编码或写入内部缓冲阶段已经出错。
        if err := w.Write(record); err != nil {
            return fmt.Errorf("write record %d: %w", index, err)
        }
    }

    // Flush 把内部缓冲交给底层 Writer，但它本身没有返回 error。
    w.Flush()
    // Error 负责读取 Write 或 Flush 保存下来的错误状态。
    if err := w.Error(); err != nil {
        return fmt.Errorf("flush csv output: %w", err)
    }
    return nil
}

这里的收尾顺序不能交换：如果先读 Error 再 Flush，就可能在底层写入尚未发生时提前得到 nil。对于文件、压缩层、HTTP 响应封装或测试用的故障 Writer，这个区别都成立。

处理 Write 即时失败和批量写入

逐条调用 Write 时，返回错误就应该停止继续写入，并带上记录下标。否则后续代码可能继续修改业务状态，最后只看到一个模糊的 Flush 失败。

如果本来就要一次写完所有记录，也可以使用 WriteAll：

// WriteAll 会逐条调用 Write，最后自动 Flush，并返回 Flush 错误。
if err := csv.NewWriter(dst).WriteAll(records); err != nil {
    return fmt.Errorf("write all csv records: %w", err)
}

WriteAll 适合记录数量已经在内存中、且调用方只关心最终错误的场景。需要定位第几条记录、控制批次或在写入中途更新进度时，使用显式循环更容易保留上下文。无论选择哪种写法，都要确认错误已经返回到导出任务的日志、重试或事务处理层。

按输出目标设计错误边界

同一套写法可以复用到不同目标，但错误含义会略有不同：

命令行导出时，建议让错误带上记录编号和输出目标；服务端导出时，则要把请求标识、响应是否已经开始和底层错误一起记录。Writer.Error 能告诉你 CSV 写入链路曾经失败，但不能撤销已经发给客户端的字节，也不能替代文件 Close 的错误处理。

常见问题

Write 返回 nil 后为什么还要检查 Error？

因为 Write 可能只写入内部缓冲，底层输出失败要到 Flush 时才出现；Error 会汇总此前 Write 或 Flush 记录的错误。

Flush 为什么没有返回值？

这是 csv.Writer 的接口设计，调用方通过 Writer.Error 读取 Flush 产生的错误。

WriteAll 后还要调用 Flush 吗？

不需要，WriteAll 已经会在写完记录后刷新；但仍要检查它的返回值，因为它会返回 Flush 错误。

把 CSV 导出的成功条件固定为“Write 无错、Flush 已调用、Error 为 nil”，就能覆盖最容易被缓冲隐藏的失败路径。遇到自定义输出层时，再把底层 Writer 的关闭错误和请求取消补进同一条错误链。