Go csv.Writer.WriteAll 大批量导出如何控制内存与写入收尾

Go 导出 CSV 时，csv.Writer.WriteAll 很方便，但它接收的是已经准备好的 [][]string。因此，大批量导出要控制内存，关键不是给 WriteAll 再加一个参数，而是避免把所有记录一次性组装出来：小批量直接用 WriteAll，数据持续产生或规模较大时改成逐条 Write，最后统一检查 Flush 和 Error。

WriteAll 适合已经准备好的记录集合

WriteAll 的签名是 WriteAll(records [][]string) error。官方实现语义是使用 Writer.Write 写出多条记录，然后调用 Writer.Flush，并返回收尾阶段的错误。它不会替调用方读取数据库游标，也不会把一个数据源自动变成流式迭代器。

所以，下面这种写法的内存成本主要来自 records 本身：外层切片保存所有行，内层切片保存每个字段字符串；csv.Writer 只负责编码和缓冲。记录数不大、需要在写出前统一排序或重试时，批量 API 反而更直观。

package main

import (
    "encoding/csv"
    "log"
    "os"
)

func main() {
    // 适合记录集合已经准备好、规模可控的导出任务。
    records := [][]string{
        {"id", "name"},
        {"1", "Ada"},
        {"2", "Grace"},
    }

    file, err := os.Create("users.csv")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close() // 关闭文件，释放操作系统资源。

    writer := csv.NewWriter(file)
    if err := writer.WriteAll(records); err != nil {
        // WriteAll 会把底层 Flush 的错误返回出来。
        log.Fatal(err)
    }
    // 读取 Writer 的最终错误状态，便于统一处理写入失败。
    if err := writer.Error(); err != nil {
        log.Fatal(err)
    }
}

大批量导出改用逐条 Write

如果记录来自数据库游标、分页接口或计算管道，不要为了调用 WriteAll 把结果重新堆成一个巨大的二维切片。逐条写入只保留当前记录和 Writer 的缓冲区，真正的内存上限由上游批次和单行大小决定。

这个方案还有一个实际好处：可以在生成下一条记录之前释放上一条记录的临时数据。不过，逐条 Write 并不等于每行都立刻落盘；写入仍可能被缓冲，所以收尾时必须调用 Flush，并通过 Error 判断底层 io.Writer 是否接受了全部缓冲内容。

package main

import (
    "encoding/csv"
    "io"
    "log"
    "os"
)

// exportCSV 让 next 按需生成当前记录，避免一次性保存整个 [][]string。
func exportCSV(dst io.Writer, next func() ([]string, bool)) error {
    writer := csv.NewWriter(dst)

    for {
        record, ok := next()
        if !ok {
            break
        }
        // Write 可能提前发现格式或目标 Writer 的错误，先处理返回值。
        if err := writer.Write(record); err != nil {
            return err
        }
    }

    writer.Flush() // 把最后仍在缓冲区里的 CSV 字节交给底层 Writer。
    if err := writer.Error(); err != nil {
        return err // Flush 阶段的错误只能在这里可靠发现。
    }
    return nil
}

func main() {
    file, err := os.Create("large-users.csv")
    if err != nil {
        log.Fatal(err)
    }
    defer file.Close() // 即使导出失败也要关闭文件。

    rows := [][]string{{"id", "name"}, {"1", "Ada"}, {"2", "Grace"}}
    index := 0
    next := func() ([]string, bool) {
        // 示例用切片模拟游标；生产代码可替换为数据库或分页读取。
        if index == len(rows) {
            return nil, false
        }
        record := rows[index]
        index++
        return record, true
    }
    if err := exportCSV(file, next); err != nil {
        log.Fatal(err)
    }
}

把 WriteAll、Write、Flush 和 Error 分开判断

选择 API 时可以按下面的边界判断。这里的“内存控制”指是否需要调用方长期持有全部记录；它不是对 CSV 编码速度或磁盘吞吐的承诺。

一个容易忽略的区别是：WriteAll 自己会调用 Flush，但逐条 Write 不会替你完成最后收尾。相反，不能因为 Write 循环中的每次调用都返回 nil，就认为文件已经完整；缓冲写出可能在后面才暴露错误。

常见问题

WriteAll 会把 CSV 文件一次性读进内存吗？

不会。它接收调用方已经准备好的 [][]string，再逐条交给 Writer；需要重点控制的是调用方保存记录集合的方式。

改成逐条 Write 后还需要 Flush 吗？

需要。Write 是带缓冲的，循环结束后调用 Flush，再调用 Error 检查底层写出结果。

WriteAll 返回 nil 就可以不看 Error 吗？

文章中的稳妥做法是保留统一的 writer.Error() 收尾检查，尤其是代码之后还会复用同一个 Writer 或需要把错误记录到统一日志时。

实践上可以把选择压缩成一句话：已经有一份规模可控的 [][]string 就用 WriteAll；数据还在产生，就逐条 Write，最后固定执行 Flush + Error。这样既不会把批量 API 误当成流式读取器，也不会漏掉缓冲阶段的写入失败。