Node.js中stream pipeline失败后无法向express响应返回数据如何解决

问题根因 #

你遇到的问题核心来自两个原因：

1. stream/promises的pipeline方法在检测到管道中任意流报错时，会自动销毁所有参与管道的流，包括你传入的express响应对象res。res被销毁后，你在catch块中调用的res.status().json()方法自然无法生效，浏览器就会收到被中断的空响应，触发ERR_EMPTY_RESPONSE报错。
2. 你在代码最开头就设置了下载相关的响应头，虽然此时头还没有真正发送给客户端，但如果查询错误发生时已经有部分数据写入res导致响应头被发送，你也不可能再把已经开始传输的csv响应替换为json格式的错误响应。

解决方案 #

通过延迟设置下载响应头+判断响应头发送状态的方式解决，修改后的代码如下：

const { pipeline } = require('stream/promises')
const { Transform } = require('stream')

// 注意：开头不要设置下载响应头，等确认SQL查询有数据返回后再设置
let headersSet = false
const sqlStream = connection.query('SELECT * FROM whatever_table').stream({highWaterMark: 5}) // 使用mysql2适配器
const formatCsvStream = formatCsv({delimiter: ';'}) // 使用@fast-csv/format

// 新增转换流，第一次收到查询数据时再设置下载响应头
const headerSetTransform = new Transform({
  writableObjectMode: true, // mysql2返回的流是对象模式，需要开启配置
  transform(chunk, encoding, callback) {
    if (!headersSet) {
      res.set('Content-Type', 'text/csv')
      res.set('Content-Disposition', `attachment; filename="${req.query?.filename || 'export'}.csv"`)
      headersSet = true
    }
    this.push(chunk)
    callback()
  }
})

try {
  await pipeline(
    sqlStream,
    headerSetTransform,
    formatCsvStream,
    res
  )
} catch (err) {
  console.error(err)
  // 如果响应头还没发送，说明还没有任何数据返回给浏览器，可以正常返回JSON错误
  if (!res.headersSent) {
    return res.status(500).json({message: 'Please check the application logs for more details.'})
  }
  // 如果已经发送了响应头，说明已经有部分CSV数据传输给浏览器，无法再修改响应格式，直接终止即可
  res.end()
}

注意事项 #

如果错误发生在文件下载的过程中（比如已经传输了一半CSV数据时数据库连接中断），此时已经无法修改响应格式返回JSON错误，这种场景下用户只会看到下载失败的提示，属于正常情况。

内容的提问来源于stack exchange，提问作者hlozancic