Stream

背景与问题界定 在 Node.js 服务端开发中，文件上传、日志解析、数据 ETL 和实时转码等场景均涉及流式数据处理。一个典型事故：某日志处理服务在处理 500MB 文件时直接 OOM，原因是用 fs.readFile 加载到内存再逐行处理。改用 Stream 后，虽然内存稳定在 50MB 以内，但又出现了新问题——下游消费者处理速度跟不上上游生产速度时，数据在内部缓冲区不断累积，最终仍会导致内存膨胀甚至进程崩溃。这就是背压（Back Pressure）控制缺失的典型表现。许多开发者认知中的 pipe 只是语法糖，而对其背后的暂停/恢复（pause/resume）机制、highWaterMark 配置、以及 Transform 流的速率匹配策略缺乏系统理解。 目标拆解与工程约束 内存上限可控：任意单条数据管道在全生命周期内的驻留内存不得超过配置的 highWaterMark 的 3 倍，超出时生产端自动暂停。 管道中断与错误传播：管道中任意节点出错时，错误应沿管道逆向传播并触发合理的清理逻辑，避免文件句柄泄漏或 socket 挂起。 管道可监控与可观测：每个 Stream 节点的吞吐量（bytes/s）、缓冲区水位和 pause/resume 事件次数应对外暴露，供监控系统采集。 支持管道拓扑重组：业务逻辑变化时（如新增一个数据脱敏步骤），无需重写整个管道，只需插入一个 Transform Stream。 方案设计 Node.js Stream 的背压机制本质上是一个生产-消费队列模型。Readable 流的内部缓冲区默认 highWaterMark 为 16KB（Object Mode 为 16 个对象）。当消费者调用 read() 时，数据从缓冲区取出；当缓冲区空时触发 readable 事件。关键在 Writable 端：write() 返回 false 表示缓冲区已满，此时 Readable 端应暂停 data 事件的发射，等待 Writable 的 drain 事件后再恢复。 pipe 方法自动实现了上述逻辑，但许多自定义场景无法直接使用 pipe。例如需要同时写入多个下游（多播模式），或上下游之间存在速率不匹配的转换逻辑。我们通过一个 through2 风格的 Transform 流来说明： ...