Node.js / 系统课时

认识可写流

认识可写流

可写流负责把数据按顺序送到文件、网络连接或其他目标。它看起来只是连续调用 write(),但真正要掌握的是内部缓冲、背压、end() 与 finish 的关系;否则数据量一大,就可能出现内存持续增长或过早退出。

学习目标

  • 能正确调用 write()、end() 并监听 finish。
  • 能根据 write() 的布尔返回值处理背压和 drain。
  • 能区分“写入流程完成”和“数据已经持久化到磁盘”。

write 返回值决定要不要继续塞数据

writable.write(chunk) 会把数据交给可写流,并返回布尔值。返回 true 表示内部缓冲还低于阈值,可以继续写;返回 false 表示缓冲已达到或超过 highWaterMark,此时应暂停上游,等待 drain 后再继续。

可写流写入、缓冲、背压与结束流程

highWaterMark 是背压阈值,不是“最大可写容量”。即使 write() 返回 false,当前 chunk 仍已被 Node.js 接收并排队;错误做法是继续无上限调用 write(),正确做法是把 false 当作暂停信号。

用一个小缓冲观察 drain

下面示例把 highWaterMark 设为 8 字节,并故意让底层写入延迟 20 ms。第一次写入 4 字节仍低于阈值;第二次累计到 8 字节,write() 返回 false,程序等待 drain 后再调用 end()。

js
const { Writable } = require('node:stream');
const { once } = require('node:events');

const sink = new Writable({
  highWaterMark: 8,
  write(chunk, _encoding, callback) {
    setTimeout(() => {
      console.log(`written:${chunk.toString()}`);
      callback();
    }, 20);
  }
});

async function main() {
  sink.on('finish', () => {
    console.log('finish');
  });

  console.log('write1', sink.write('1234'));

  const canContinue = sink.write('5678');
  console.log('write2', canContinue);

  if (!canContinue) {
    await once(sink, 'drain');
    console.log('drain');
  }

  sink.end('END');
}

main().catch(console.error);

预期输出

text
write1 true
write2 false
written:1234
written:5678
drain
written:END
finish

这里的顺序很关键:false 不是写入失败;它只是告诉生产者“先别继续”。当缓冲降下来时触发 drain,再恢复生产即可。真实文件复制和网络转发通常直接用 pipeline(),它会替你协调上下游背压。

end 与 finish 分别表示什么

end([chunk]) 表示“不会再写新数据”,它可以顺便提交最后一块数据。调用后再执行 write() 属于错误用法,可能触发 ERR_STREAM_WRITE_AFTER_END。finish 则在 end() 已调用且所有数据都交给底层写入逻辑后触发。

动作或事件 含义 后续能否继续 write()
write(chunk) 提交一块数据 可以,除非已经 end()
end(chunk) 提交可选最后一块并关闭写入口 不可以
drain 内部缓冲下降,可恢复生产 可以
finish 可写流已处理完全部待写数据 不可以

对文件流来说,finish 不等于数据已经通过 fsync 强制落到物理介质。多数业务只需要知道 Node.js 已完成写入流程;如果场景要求崩溃后仍保证持久化,则还需要显式的文件同步策略。

完成状态要和错误状态一起监听

finish 只代表正常完成路径。真实项目还要处理 error,否则磁盘写满、权限不足、连接断开等情况会被误判成正常结束。对于由多个流组成的链路,优先使用 stream.pipeline(),它会统一处理错误传播和资源关闭。

验收一个可写流时,至少检查:发生背压时生产者会停、end() 后不会再写、正常路径只触发一次 finish、错误路径能被捕获。满足这四点后,写入逻辑才适合进入持续数据量更大的场景。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

认识可写流

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通