Go 大文件 CSV 导出怎么做稳：从全量查询到流式写出架构

订单后台一到月底就有人导出 CSV，最开始几万行还能扛住，等数据量涨到几百万行，问题就全出来了：接口半天没响应，Go 进程内存占用一路飙升，浏览器下载进度条卡着不动，最后直接触发网关超时。这时候单纯把网关超时时间调长根本解决不了问题，真正要优化的是整个导出链路：不要先把完整文件攒在内存里，改成按批次从数据库读数据，边读边往响应流里写。

旧导出链路为什么撑不住几百万行

很多导出接口一开始都写得很随意：先查出符合筛选条件的所有订单，再把结果转成二维数组，最后一次性生成完整CSV。数据量小的时候这种写法逻辑简单好维护，但数据量上来以后，内存里会同时堆着数据库查询结果、业务结构体、字符串拼接缓冲和最终的完整文件内容，内存峰值会被层层叠加推得很高。

更麻烦的是，用户看到的只是“下载慢”，服务端侧却要同时扛查询延迟、内存暴涨、长连接占满的连锁问题。如果只给网关加超时阈值，导出任务还是会在后台拖着数据库和Go进程的资源不放。规模上来之后，导出接口就该从同步在内存里生成完整文件的模式，改成稳定输出数据流的模式。

新链路：分批读取，流式写出，及时刷新

流式导出的核心是让数据在整个链路里正常流动起来，而不是堵在内存里堆成大块。HTTP处理函数设置好对应的响应头之后，`csv.Writer`可以直接包装`http.ResponseWriter`，每批从数据库读取一段订单数据，写完一批就立刻刷新缓冲。哪怕最终生成的总文件很大，Go进程里也只会保留当前批次的数据和少量写入缓冲。

func exportOrders(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()

    w.Header().Set("Content-Type", "text/csv; charset=utf-8")
    w.Header().Set("Content-Disposition", `attachment; filename="orders.csv"`)

    writer := csv.NewWriter(w)
    defer writer.Flush()

    _ = writer.Write([]string{"id", "user_id", "amount", "created_at"})

    var lastID int64
    const batchSize = 1000

    for {
        rows, err := queryOrderBatch(ctx, lastID, batchSize)
        if err != nil {
            log.Printf("query order batch failed: %v", err)
            return
        }

        count := 0
        maxID := lastID
        for rows.Next() {
            var row OrderRow
            if err := rows.Scan(&row.ID, &row.UserID, &row.Amount, &row.CreatedAt); err != nil {
                rows.Close()
                log.Printf("scan order row failed: %v", err)
                return
            }

            _ = writer.Write([]string{
                strconv.FormatInt(row.ID, 10),
                strconv.FormatInt(row.UserID, 10),
                row.Amount.String(),
                row.CreatedAt.Format(time.RFC3339),
            })

            count++
            maxID = row.ID
        }
        rows.Close()

        writer.Flush()
        if err := writer.Error(); err != nil {
            log.Printf("write csv failed: %v", err)
            return
        }

        lastID = maxID
        if count 

这段代码里有两个细节很容易被忽略。第一，`rows.Close()`要在每一批数据处理完之后就执行，不能把多个批次的结果集句柄一直拖到整个大循环结束才释放。第二，每次调用`writer.Flush()`之后要主动检查`writer.Error()`的返回值，客户端主动断开、代理层提前中断、网络写失败这些异常场景，都可能在这里抛出错误。

分批查询别用大 offset 拖慢数据库

很多导出接口会直接写`LIMIT 1000 OFFSET 2000000`的分页逻辑，行数越靠后查询速度越慢。更适合导出场景的分页方式，是用稳定递增的主键或者创建时间做游标。比如订单表按id顺序导出，就用上一批返回的最大id作为下一批的查询起点。

func queryOrderBatch(ctx context.Context, lastID int64, limit int) (*sql.Rows, error) {
    return db.QueryContext(ctx, `
        SELECT id, user_id, amount, created_at
        FROM orders
        WHERE id > ?
        ORDER BY id ASC
        LIMIT ?
    `, lastID, limit)
}

如果业务要求按时间维度筛选数据，也可以把`created_at`放进查询条件里，但排序字段要和数据库已有的索引匹配。真实生产环境里建议给导出接口准备专门的联合索引，比如`(created_at, id)`，或者多租户场景下再加`tenant_id`前缀，避免一次导出就扫完整张业务表。

关键取舍：流式响应不是万能解法

流式写出能压住应用侧的内存峰值，但它也会带来新的边界问题。HTTP连接会被占用更久，下载中途失败之后没法从半截文件位置继续，反向代理层可能自带大小缓冲策略，浏览器也不一定能展示精确的下载进度。所以大文件导出要按照实际数据规模分层处理。

• 几十万行以内：同步流式下载通常完全够用，重点控制导出字段和单批读取的大小。
• 几百万行以上：更推荐跑后台异步任务，文件生成完成之后再给用户返回下载链接。
• 频繁导出的同类固定报表：可以直接做生成好的文件缓存和过期清理逻辑，减少重复查询计算。
• 敏感业务数据导出：必须做字段白名单校验、权限检查和完整的操作审计日志。

这里的取舍从来不是“流式一定比后台任务模式更高级”。如果单次导出就要跑十几分钟，用户侧浏览器、网关、负载均衡每一层都可能成为不稳定因素。同步流式的价值是把内存峰值压下来，后台任务模式的价值是把长耗时、重计算的逻辑从实时请求链路里完全拆出去。

上线后要看这些运行信号

改完导出链路之后，不要只验证“文件能正常下载成功”就完事。真正要确认的是服务整体运行是否稳定：进程内存占用能不能保持平稳，数据库侧的慢查询有没有新增，下载失败率有没有下降，客户端主动中断的请求数有没有异常上涨，单次导出的字节数和行数是不是符合业务预期。

export_rows_total{status="ok"} 1240000
export_bytes_total{file="orders.csv"} 93500122
export_duration_seconds_bucket{le="30"} 18
export_client_abort_total 3
export_batch_query_seconds_p95 0.12

如果内存占用没涨，但数据库慢查询变多，说明之前的内存压力被转移到了查询层；如果客户端中断请求变多，大概率是整体下载耗时还是太长，或者代理层的超时阈值没有同步调整。架构改动的效果好坏，要靠这些运行指标一起交叉判断。

常见问题

Go CSV 导出一定要用 `io.Pipe` 吗？

不一定。直接用`csv.NewWriter(w)`包装响应流就能覆盖绝大多数常规场景。只有当生成CSV之后还要做上传云存储、压缩、加密等需要跨goroutine传递数据流的步骤时，才更适合考虑用`io.Pipe`实现流式传递。

每批读取多少行比较合适？

可以从500到2000行这个区间起步做压测，再根据单行列数、数据库响应时间和内存占用曲线调整。如果单条数据字段很多、字符串很长，批大小要设置得更保守一些。

为什么流式写出后浏览器还是超时？

有可能是反向代理层自带缓冲或者设置了较短的超时限制，也可能是总文件体积太大、用户侧网络条件差。服务端内存保持稳定不代表下载体验就完全稳定，超大体积的导出场景还是更适合走后台异步任务模式。

导出接口能不能支持重试续传？

同步流式接口很难优雅实现续传，因为文件内容是跟着查询结果实时生成的。需要支持续传的场景，一般会先生成完整文件存到对象存储，再让下载接口支持HTTP范围请求。

导出时怎样避免字段泄露？

不要直接把结构体所有可导出字段直接往外写。导出层必须维护明确的字段白名单，同时把导出触发人的权限信息、筛选条件、导出总条数和生成文件名都写入审计日志。

先把内存峰值降下来，再决定是否升级为任务化

Go 大文件 CSV 导出的第一步，就是从“全量查询后攒完整文件”改成“分批读取、流式写出、及时刷新”的模式。这个改动可以明显压低Go进程的内存峰值，也能让浏览器尽早收到响应头开始下载。等后续业务数据规模继续变大，再把同步导出升级成后台任务、文件持久化存储和下载链接分发的完整链路，整套方案会比单纯加机器扩容要稳得多。