Go流式处理：破解大数据量接口504网关超时的正确姿势

先问一句，你在生产环境里有没有被“504 Gateway Timeout”支配过？我做Go后端这几年，线上遇到最多的疑难杂症之一，就是接口在大数据量下超时。尤其是导出报表、拉全量订单、做批量计算这类的接口，数据一多，前端等不及，Nginx先断了，客户端拿回一个504，服务端却还在傻傻地算。我见过太多团队的第一反应是把超时时间从30s调到60s、再调到120s，结果治标不治本，流量一涨照样崩。其实这类问题有一个更优雅的解法：放弃“等全部跑完再一次性返回”的旧思路，改成流式处理——边算边发，让客户端第一时间拿到首字节。这篇就围绕大数据量接口的网关超时问题，把流式方案的原理、Go语言实现和真实场景下的坑一次讲透，适合正在被超时问题折磨的后端开发，也适合想优化接口响应体验的架构师参考。

1. 超时问题拆解：到底是谁杀死了你的请求

1.1 一个HTTP请求的超时，其实有三道闸门

先建立一个基本认知：一个请求从客户端发出到收到响应，要穿过三个节点。客户端、网关（Nginx、API Gateway之类）、服务端，任意一个节点先失去耐心，这次请求就失败了。我们常说的“超时”，并不是一个单一的数字。

• 客户端超时：前端fetch的AbortSignal.timeout、axios的timeout、Go的http.Client.Timeout，都算这一层。客户端等不到响应，直接抛“请求超时”。
• 网关超时：Nginx的proxy_read_timeout、proxy_send_timeout，或者云厂商SLB/API网关的超时配置。网关作为中间人，它等不到上游服务的数据，就会返回504 Gateway Timeout。
• 服务端超时：Go的http.Server里ReadTimeout、WriteTimeout，或者业务代码自己加的context.WithTimeout。服务端处理太久，自己把自己掐断。

大数据量接口最常见的死因，我复盘了这么多案例，绝大多数都出在网关这一层，但病根却在服务端。服务端花了太长的时间才送出第一个字节，网关在等待读取响应时迟迟收不到任何数据，直接判了死刑。

这里要搞清楚Nginx的proxy_read_timeout的精确定义：它是“两次连续读操作之间的超时时间”，并不是整个请求的总时限。**只要上游一直在往Nginx写数据，哪怕每次只写一点，这个计时器就会不断被重置。**这一点非常关键，后面流式方案能解决超时问题，本质上就是钻了这个空子。很多人在调超时参数时只把它当成“总时长”来理解，所以怎么调都不对。

1.2 大数据量接口为什么特别容易超时：全量缓冲的巨坑

想弄明白大数据量接口为什么容易超时，得先看看传统写法是什么样的。我见过绝大多数项目的代码都是这个模式：

code复制1. 从数据库一次性把所有数据查出来
2. 组装成一个巨大的slice或者map结构
3. json.Marshal序列化成一个大[]byte
4. 最后w.Write一次性返回给客户端

这种“全量缓冲”模式有三个非常现实的问题。

第一，数据库查询本身慢。 几百万行数据一次SELECT出来，数据库要扫描、要排序、要传输，这个过程可能就要几十秒。如果是联表聚合查询，那就更慢。

第二，序列化是CPU密集型操作。 json.Marshal一个包含百万级元素的slice，CPU占用会直接拉满。我实测过一个100万行的订单导出，json.Marshal这一步能吃掉40%以上的CPU时间。而这段耗时里，用户那边看到的是一个卡住的请求。

第三，内存占用非常夸张。 100万行数据，先是以结构体的形式存在内存里，每个字段还要有对应的字符串、数字、时间对象，再加上序列化产生的巨大[]byte，内存峰值轻松上到几百MB。在容器环境里，这很容易触发OOM。

最关键的问题是：在“全量缓冲”模式下，服务端在完成上面所有步骤之前，不会写出任何一个字节给客户端。 TTFB（首字节时间）就等于“数据库查询耗时 + 序列化耗时 + 其他业务耗时”。当TTFB超过网关超时时间，504就来了。

打个比方，全量缓冲就好比饭店把所有人的菜都做完，再一起端上桌。客人等得饥肠辘辘，干脆起身走人。流式处理则是炒好一盘上一盘，客人边吃边等，体验完全不同。

2. 流式处理：把“一次性返回”改成“边算边发”

2.1 流式的底层协议：Chunked Transfer

流式处理能实现，依赖的是HTTP/1.1协议里一个很早就存在、但很多开发者一直没注意的特性：分块传输编码（Transfer-Encoding: chunked）。

HTTP/1.1的响应如果没有Content-Length，服务端就可以用chunked编码告诉对端“我不知道总长度，但我会一块一块地发给你的”。它的数据格式是：每块数据前面是十六进制表示的长度，后面跟着回车换行，然后是数据本身，最后以一个长度为0的块结束。举一个最简单的响应示例：

code复制HTTP/1.1 200 OK
Transfer-Encoding: chunked

5\r\n
hello\r\n
6\r\n
 world\r\n
0\r\n
\r\n

客户端收到这种响应，会持续读取直到看到终止块。这正是流式接口和网关超时能够共存的基础：网关知道“这个响应还没结束”，所以不会因为没等到Content-Length而判定异常；同时因为数据持续在送，网关的read timeout也会不断被重置。

Go的net/http包对chunked编码做了完整的封装。用ResponseWriter写入数据并调用Flush时，Go会自动把数据组装成chunked格式发给对端。我们开发者并不需要手动去拼那些十六进制长度字段。HTTP/2下就更简单了，协议层本来就是流式的帧传输，Go的http2 ResponseWriter同样实现了Flusher接口，所以流式代码在不同协议版本下都能正常工作。

让我再强调一次：流式并不只是“把一个大JSON拆开分批发”，它依赖的是HTTP协议层面的持续发送能力。 搞懂了这一点，你再看后面的代码就容易理解了。

2.2 流式的三种主流响应格式

并不是所有接口都适合流式，具体还得看响应内容的格式。我实际用下来，主流的有三种。

CSV/TSV流式。这是大数据量导出的首选。CSV本身就是逐行文本格式，天然适合边查边写边发送。用户拿到的直接就是一个可下载的csv文件，浏览器还能根据Content-Length或者进度条显示下载进度。百万行的导出，用CSV流式最稳。

JSON数组流式。适合API调用场景，比如移动端分页拉大列表、前端表格组件加载数据。实现上需要手动控制开头的方括号、每两条数据之间的逗号、以及结尾的方括号。对于数据量在几万级别的接口，效果很好。

SSE（text/event-stream）。服务端向客户端持续推送事件流的格式，适合做实时通知、任务进度推送、AI流式对话。浏览器原生支持EventSource，前端对接起来非常舒服。

3. Go语言实现：一个可落地的流式接口

3.1 最小可用版：Flusher接口的断言与刷新

先上一个Go语言流式接口的最简实现。这段代码把核心逻辑说清楚：逐行输出，每输出一行就Flush一次。

go复制func streamHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.Header().Set("X-Content-Type-Options", "nosniff")
    w.WriteHeader(http.StatusOK)

    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming unsupported", http.StatusInternalServerError)
        return
    }

    for i := 1; i <= 10; i++ {
        fmt.Fprintf(w, "line %d\n", i)
        flusher.Flush()
        time.Sleep(500 * time.Millisecond)
    }
}

这里有三个细节要重点说。

第一，Header的顺序。必须先设置Header，再调用WriteHeader(200)，最后写body。如果先写body再设置Header，Header就失效了。这个顺序问题我刚写流式接口时踩过坑，总是先Write再Set Header，结果Content-Type没生效，客户端拿到的响应乱码。

第二，http.Flusher是运行时断言。并不是所有ResponseWriter都支持Flush。在标准net/http下，正常的ResponseWriter都实现了Flusher。但如果你用了某些第三方中间件包装了ResponseWriter，包装器可能没实现这个接口。所以代码里先断言一下，不支持就返回500，这是最基本的防护。

第三，Flush的语义。Flush做的事情是把Go应用层缓冲的数据立刻发送给TCP对端。它不等于“数据立刻到达客户端浏览器”，因为中间还有内核的TCP缓冲区、Nginx的转发缓冲。但它是流式响应的基础——没有Flush，Go会尽量攒数据，网络包迟迟不发出，流式就名存实亡。

我在本地测试这段代码时，用curl观察到的效果是：大约每500毫秒收到一行数据。用浏览器访问，页面也会逐行渲染内容，而不是全部等齐了才显示。

3.2 生产可用版：超时控制与客户端断连感知

最小可用版只是打通了链路，真上生产还有两个绕不开的问题：客户端中途断开怎么办？业务处理时间太长谁来兜底？

很多开发者忽略了这一点：HTTP响应写到一半时，客户端突然关闭连接，如果服务端还在继续循环处理数据，那就是白算。 在大数据量场景，白白浪费的可能是几秒钟的数据库查询和整个序列化过程。

正确的做法是监听请求的context。当客户端断开连接时，Go的net/http会cancel这个请求的context，r.Context()的Done通道会被关闭。我们在每轮循环里都检查一下这个信号，一旦发现客户端已经走了，立刻退出，不要再做无谓的计算。

go复制func streamWithCtx(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming unsupported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/plain; charset=utf-8")
    w.WriteHeader(http.StatusOK)

    for i := 0; i < 1000000; i++ {
        select {
        case <-ctx.Done():
            log.Printf("client closed connection: %v", ctx.Err())
            return
        default:
        }

        if _, err := fmt.Fprintf(w, "data %d\n", i); err != nil {
            log.Printf("write failed: %v", err)
            return
        }
        flusher.Flush()
    }
}

特别注意，响应一旦开始写，就不能再用http.Error这类函数返回错误状态码了，因为HTTP状态码和响应头已经发送出去了，这时候再去写500，客户端拿到的是body中间的垃圾数据，反而引起解析错误。正确的做法是直接return结束handler，连接由框架关闭。如果你希望结束得更干脆一点，也可以panic(http.ErrAbortHandler)，net/http会特殊处理这个panic，不会打出堆栈，而是直接终止连接。我在日志导出接口遇到客户端频繁断连的场景，就是用panic(http.ErrAbortHandler)把半截响应切断的。

另外，context的超时控制在事务型的流式接口里同样重要。可以给这个流式handler单独包一层context.WithTimeout，比如限制整个导出最长60秒。这样即使客户端没有断开、网关也没掐断，服务端也不会无限跑下去。

3.3 实战案例：百万行CSV流式导出

现在把上面这些技巧综合起来，写一个贴近真实业务的CSV导出接口。场景是：从数据库导出订单表，可能上百万行，需要快速响应、低内存占用，并且不能因为数据量导致504。

在这个场景里，除了响应端要流式发送，数据库读取端也必须要分批。常见做法有两种：OFFSET分页和键集分页（Keyset Pagination）。OFFSET在深度分页时性能会断崖式下跌，因为数据库需要跳过前面所有行；键集分页利用有序主键或业务键，在一次索引扫描中持续向后取数，性能稳定很多。下面示例用的是“WHERE id > ? ORDER BY id LIMIT ?”的键集分页模式。

go复制func exportCSVHandler(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming unsupported", http.StatusInternalServerError)
        return
    }

    // 强制浏览器下载文件
    w.Header().Set("Content-Type", "text/csv; charset=utf-8")
    w.Header().Set("Content-Disposition", "attachment; filename=orders.csv")
    // 处理Excel打开UTF-8 CSV的乱码问题
    w.WriteHeader(http.StatusOK)

    if _, err := w.Write([]byte("\xEF\xBB\xBF")); err != nil {
        return
    }
    csvWriter := csv.NewWriter(w)

    const batchSize = 1000
    var lastID int64 = 0

    for {
        select {
        case <-ctx.Done():
            log.Printf("client closed: %v", ctx.Err())
            return
        default:
        }

        rows, err := db.QueryContext(ctx,
            "SELECT id, order_no, amount, created_at FROM orders WHERE id > ? ORDER BY id LIMIT ?",
            lastID, batchSize)
        if err != nil {
            log.Printf("query failed: %v", err)
            return
        }

        batchCount := 0
        for rows.Next() {
            var (
                id        int64
                orderNo   string
                amount    float64
                createdAt time.Time
            )
            if err := rows.Scan(&id, &orderNo, &amount, &createdAt); err != nil {
                rows.Close()
                log.Printf("scan failed: %v", err)
                return
            }
            csvWriter.Write([]string{
                strconv.FormatInt(id, 10),
                orderNo,
                strconv.FormatFloat(amount, 'f', 2, 64),
                createdAt.Format("2006-01-02 15:04:05"),
            })
            lastID = id
            batchCount++
        }
        rows.Close()
        if err := rows.Err(); err != nil {
            log.Printf("rows error: %v", err)
            return
        }

        // 关键：先Flush csv.Writer自己的缓冲，再Flush http.Flusher
        csvWriter.Flush()
        if err := csvWriter.Error(); err != nil {
            log.Printf("csv flush error: %v", err)
            return
        }
        flusher.Flush()

        if batchCount < batchSize {
            break
        }
    }
}

这段代码里有几个容易踩的坑。第一个是csv.Writer自带的缓冲。csv.Writer内部有自己的bufio缓冲，只有调用csvWriter.Flush()才会真正把数据写到http.ResponseWriter。少了这一步，数据会一直积在缓冲里，http.Flusher也无能为力。所以要先Flush csvWriter，再Flush http.Flusher，顺序不能反。第二个是要检查csvWriter.Error()，因为CSV写入过程中field数量不一致会返回错误，忽略的话可能生成脏数据。第三个是rows.Err()检查，很多数据库驱动在迭代过程中遇到网络错误，并不会在Next返回时立刻暴露，而是在迭代结束后通过rows.Err()返回，必须检查。

内存方面的收益是实实在在的。我用一组对比测试数据说明：同样是100万行、每行10个字段的订单数据，全量缓冲方案内存峰值大约在300MB左右（结构体加序列化缓冲）；而上面这个分批流式方案，内存峰值只在几MB级别浮动，因为每一批1000行处理完就释放了。数据库连接也不会被长时间占用，查询是短平快的。

3.4 流式JSON数组的正确姿势

CSV适合导出下载，但很多API场景前端要的是JSON。流式JSON数组的原理和CSV流式类似，但因为JSON数组是“一个完整的语法结构”，实现细节上要格外注意括号和逗号。

go复制func streamJSONArray(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "streaming unsupported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(http.StatusOK)

    w.Write([]byte("["))

    encoder := json.NewEncoder(w)
    for i := 0; i < 100; i++ {
        select {
        case <-ctx.Done():
            return
        default:
        }

        item := map[string]interface{}{
            "id":   i,
            "name": fmt.Sprintf("item-%d", i),
        }
        if i > 0 {
            w.Write([]byte(","))
        }
        if err := encoder.Encode(item); err != nil {
            return
        }
        flusher.Flush()
    }

    w.Write([]byte("]"))
}

用json.Encoder.Encode会带一个换行符，在JSON标准里数组元素之间的空白字符是允许的，所以生成的JSON是合法的。需要注意，流式JSON数组有一个天然缺陷：如果中途出错直接return，客户端收到的就是一个不完整的非法JSON。前端fetch解析时会报SyntaxError，跟整包响应失败的表现还不一样。

所以流式JSON数组适合“数据本身很可靠、不太可能在过程中出错”的场景。如果业务上有可能会中断，我一般建议前端用两种方式处理：一种是约定“截断也算成功”，前端自己判断最后一个字符是不是]；另一种更稳妥，直接改用NDJSON（每行一个JSON对象）或者SSE，这两种格式天然支持“边发边解析”，不存在“半截非法JSON”的问题。

4. 网关侧配置与真实世界的坑

4.1 Nginx的proxy_buffering：最容易被忽略的“假流式”

流式方案在后端已经实现了，但如果你发现接口还是“假流式”——客户端仍然是等好久才一次性收到所有数据，那问题很可能出在网关的缓冲层。

Nginx默认开启了proxy_buffering，它会先把上游服务的响应整个接收并缓存到自己的缓冲区，等缓冲区满了或者上游响应结束了，再一次性发给客户端。这就等于把流式效果完全抹掉了。你的Go服务辛辛苦苦边算边发，Nginx却在这头默默攒货。对用户来说，看到的依然是长久的等待和最后的一次性输出。

解决办法是在对应的location里关闭代理缓冲：

code复制location /api/export/ {
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding on;
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
    proxy_http_version 1.1;
}

proxy_buffering off的作用是让Nginx收到上游数据就立即转发，不做二次缓存。proxy_cache off是为了防止缓存层干扰。chunked_transfer_encoding on确保Nginx到客户端这一段也保持分块传输模式。proxy_read_timeout和proxy_send_timeout这里可以保持默认60s，因为流式请求一直在传输数据，超时计时器会被持续重置，理论上不会触发。

我还遇到过一些更隐蔽的情况：有的团队用的是云负载均衡或者API网关，它们默认也开了缓冲。所以在排查“为什么Go端已经Flush了，客户端还是卡顿”的问题时，要沿着整条链路看每一层是不是都有缓冲。我习惯用一个命令直接验证：

bash复制curl -N -v http://your-service/export > /dev/null

加-N参数告诉curl不要缓冲输出，然后观察响应头和数据到达的节奏。如果数据是一下子涌出来的，而不是稳定流入，说明中间某层还是在缓冲。

4.2 Go的http.Server WriteTimeout会掐死流式响应

这是流式接口最常见的另一个“隐形杀手”。很多Go项目的http.Server配置是这样的：

go复制srv := &http.Server{
    Addr:         ":8080",
    ReadTimeout:  10 * time.Second,
    WriteTimeout: 30 * time.Second,
}

正常情况下这配置没问题，但在流式接口下，WriteTimeout会成为一个大坑。WriteTimeout的语义是“从请求头读取结束到响应写完之间的最大允许时间”。流式接口因为整个过程持续很长时间，如果总时长超过WriteTimeout，Go会直接把这个连接杀掉，表现就是客户端收到“EOF”或者连接被重置。

我刚开始做流式导出时就踩过这个坑：本地测试没问题，部署到测试环境发现导出超过30秒就断了，查了半天才发现是WriteTimeout的锅。

流式接口下的正确处理方式是：要么把WriteTimeout设为0禁用，或者设一个非常大的值；要么用ReadHeaderTimeout限制请求头读取的时间，把业务上的超时控制交给请求的context和自己写的超时逻辑，而不是靠WriteTimeout一刀切。

go复制srv := &http.Server{
    Addr:              ":8080",
    ReadHeaderTimeout: 10 * time.Second,
    // WriteTimeout 不设置，或者设置很大的值
    IdleTimeout: 120 * time.Second,
}

如果你确实想限制单个写操作的耗时，Go 1.20之后引入了http.ResponseController，可以给每次写操作设置独立的deadline，实现“单个写操作超过2秒就断开”的精细控制，而不是限制整个流的总时长。这个API对流式接口的慢客户端防护非常有用，推荐大家去读官方文档。

4.3 gzip中间件与流式的爱恨情仇

很多Go Web项目会全局挂一个gzip压缩中间件来减小响应体积。但在流式接口下，gzip表现得非常不友好。

原因在于，gzip压缩器为了压缩效率，会维护一个较大的内部缓冲。ResponseWriter被gzip中间件包装后，你调用Flush，实际触发的是压缩器的Flush，并不一定能立刻把数据推到网络层。结果就是流式效果又一次被打折扣，客户端要好一阵子才能刷出新数据。此外，在大数据量流式场景下，gzip的CPU开销会成为一个新的热点，拖慢整个导出速度。

我的建议是：流式接口不要套全局的gzip中间件，尤其是CSV这种压缩率虽然高但对实时性要求也高的场景。如果非要压缩，可以做按路由排除，或者让客户端通过Content-Encoding协商来决定，并且接受压缩带来的首字节延迟。

排查时有个小技巧：用curl加-I看响应头，如果看到Content-Encoding: gzip，说明响应被压缩中间件处理了，流式效果大概率不理想。这时候要么改配置排除，要么接受延迟。

5. 超时排查实战：从“看日志”到定位瓶颈

5.1 三个节点分别看什么日志

真正遇到超时问题，不要急着改配置，先学会看三个节点的日志，判断问题到底出在哪个环节。

这里特别想说一下499状态码。如果你用的是Nginx做网关，当客户端在Nginx转发期间断开连接时，Nginx会在access log里记录499。所以服务端或者Nginx日志里出现大量499，往往说明“客户端等得不耐烦跑了”，并不一定是服务端崩溃。这时候要区分：是响应头没回来客户端就跑了，还是响应体传输太慢客户端等不下去了。

Nginx的error.log里有两个关键日志描述，含义完全不同：

• upstream timed out (110: Connection timed out) while reading response header from upstream：响应头阶段超时，说明服务端处理逻辑太久，一个字节都没往Nginx写。
• upstream timed out while reading response body from upstream：响应体阶段超时，说明响应头已经发给Nginx了，但后续body数据间隔太久。

这两种日志指向的优化方向完全不同。第一种要优化的是服务端处理速度和首字节时间，流式处理就是针对它的；第二种可能是流式节奏太慢，可以考虑增大批次、加快flush节奏，或者重新调大proxy_read_timeout。

5.2 一次真实的504排查记录

用我之前做过的一个订单报表导出服务来复盘，这个案例比较典型。当时业务方反馈，部分客户导出一段时间内的订单明细时，经常报504，而且是偶发，小租户没事，大租户必现。

排查第一步，看Nginx error.log。果然发现了大量upstream timed out while reading response header from upstream。这说明服务端在处理阶段耗费了太长时间，一个字节都没吐出来。第二步，看服务端监控，发现出问题的时间段CPU很高，内存也涨得飞快。第三步，用pprof抓一下CPU profile，发现消耗大头是json.Marshal，占到了40%以上，其次是数据库查询和字符串拼接。

当时的服务端代码就是典型的全量缓冲：先把所有订单查出来，放到一个巨大的slice里，然后json.Marshal，再一次性写出。数据量小的时候没事，一旦碰到大租户的百万行数据，查询加序列化要花掉80秒。而Nginx的proxy_read_timeout当时是60秒。于是响应头还没发出去，Nginx就等不及掐断了。

一开始我也试图“对症下药”，把proxy_read_timeout调大到120秒，把Go的WriteTimeout也调大。结果呢？问题暂时消失，但过了几周业务数据量继续增长，120秒又不够用了，504又卷土重来。这时候我才意识到，调超时参数是治标不治本——只要接口的完成时间是不可控的，总会遇到超过超时阈值的那一刻。

最终方案就是把接口改成流式。后端先分批从数据库取数据（每次1000条），边取边生成CSV，边写边Flush。首字节时间从原来的80秒降到了不到1秒，网关那头的read timeout被数据流的持续传输不断刷新，504彻底消失。这个案例给我一个很深的教训：排查超时问题，不能只盯着最后一环的“超时”报错，要分出时间线，定位到究竟是首字节慢，还是整体响应慢，再决定是优化处理逻辑，还是改成流式方案。

5.3 超时参数速查表

把常见的超时参数整理成速查表，方便大家排查时对照：

特别提醒一下http.TimeoutHandler，它内部在超时后会写一个503响应。但它读取handler的响应时是自己动手缓冲的，所以流式接口如果包了http.TimeoutHandler，Flush会被包装器吃掉，变成假流式。流式接口不要用这个中间件。

6. 方案怎么选：流式不是万能的

6.1 什么场景适合流式，什么场景不适合

流式处理解决了大数据量接口的超时问题，但它不是银弹。我见过有团队把所有的接口都改成流式，反而引入了一堆麻烦。判断一个接口适不适合流式，我的经验是看这几点：

• 数据规模：单次响应数据量超过几千行，或者序列化后超过几MB，就值得考虑流式。小数据接口强行流式，只是增加复杂度，没有收益。
• 首字节时间要求：如果业务上要求用户快速看到“开始返回了”，流式是唯一选择。
• 客户端类型：浏览器下载文件天然支持流式，现代前端fetch也支持ReadableStream。但一些老旧的HTTP客户端库可能不支持chunked响应解析，这时候流式会有兼容性问题。
• 失败代价：流式响应的特点是“可能发一半就断”，业务上能否容忍“部分成功”？如果不容忍，就要把校验逻辑尽量前置，保证开始发数据前所有可能出错的高风险操作都已经执行完毕。

我觉得最实用的一句话判断是：如果你的接口“需要一次性处理大量数据才能开始响应”，并且这个处理时间不可控，那么无论怎么调超时都会偶发504，这时候就该考虑流式了。如果数据量小、处理时间稳定，老办法完全够用。

6.2 流式带来的新问题与补偿手段

流式方案把超时问题解决了，但它也带来了新的运维问题。最典型的是“半截失败”。全量缓冲模式下，客户端要么拿到200和完整数据，要么拿到500和错误信息，语义是干净的。流式模式下，状态码已经发出去了，数据也写了一半，如果中途数据库挂了或者业务panic了，客户端拿到的是一份残缺的数据。这在数据导出场景尤其麻烦：用户下载了一个CSV，中间少了几千行，可能还没发现。

我的应对手段有三个，分享出来：

• 前置高风险操作。需要做的校验、权限检查、复杂查询都放在写响应头之前，写完第一笔数据之后，尽量只做简单的扫描和序列化。
• 导入批次ID和审计日志。在响应头或者数据里加一个导出的批次ID，服务端记录本次导出了多少行、是否完整结束。客户端下载完成后可以上报一个校验信息，服务端用来比对有没有中途断流。
• 流式后续兜底。对于真正海量的导出场景，如果流式也扛不住，考虑“异步任务”模式：接口先创建一个导出任务，返回任务ID，客户端轮询任务状态，任务完成后提供一个文件下载链接。这种方式牺牲了实时性，换来了稳定性和可恢复性。

6.3 我个人在实际项目里的最后一点体会

做了一整圈流式改造之后，我个人的体会是：靠调大超时参数去解决问题，本质上是在和业务增长对赌。 今天数据量100万行你把超时调到120秒，明天变成500万行又得调到5分钟，这不是技术方案，这是给自己埋雷。真正稳定的做法是改变响应协议，让系统不要依赖“一次性完成”的假设。

最后再分享两个我在流式接口上常用的排查小技巧。一个是给所有流式接口的access log加上响应行数和耗时字段，配合关键词“stream_done:true/false”来监控流式中断率，中断率突然升高往往意味着数据库变慢或者代码有bug。另一个是本地压测时用curl -N加watch命令查看数据到达的字节数增长情况，能帮助你快速定位到底是服务端没有Flush，还是中间层在缓冲。不管你是刚接触流式处理还是已经在做接口优化，希望这篇对你有实实在在的帮助。