Node.js 中文手册

中文翻译:www.nodecn.org 转载请注明出处

目录


数据流

数据流是 Node 中很多对象都有实现的一个抽象接口。例如,一个到 HTTP 服务器的请求就是数据流,标准输出(stdout)也是。有些数据流可读,有些可写,有些可以同时读写。所有数据流都是 EventEmitter 的实例。

Readable Stream 可读数据流

一个 Readable Stream 有如下的方法、成员和事件。

'data' 事件

function (data) { }

触发 'data' 事件时,传进来的参数可能是一个 Buffer (默认),也可能是字符串(如果使用了 setEncoding() 的话)。

'end' 事件

function () { }

当数据流收到一个 EOF(在 TCP 的术语中叫做 FIN)时触发。意味着不会再有 'data' 事件(没数据)了。如果数据流同时可写,则它还可以继续写入。

'error' 事件

function (exception) { }

接收数据出错时触发。

'close' 事件

function () { }

底层的文件描述符被关闭时触发。不是所有数据流都会触发此事件。(例如,新进的 HTTP 请求就不会触发 'close'。)

'fd' 事件

function (fd) { }

数据流收到文件描述符信息时触发。只有 UNIX 数据流支持,其它数据流不会触发。

stream.readable

一个布尔值,默认为 true,数据流出错、到达末尾、或者调用了 destroy() 后,该值为 false

stream.setEncoding(encoding)

使 data 事件返回字符串而不是 Buffer 对象。encoding 可以是 'utf8''ascii''base64'

stream.pause()

暂停触发 'data' 事件。

stream.resume()

从暂停状态恢复触发 'data' 事件。

stream.destroy()

关闭底层的文件描述符。数据流将不再触发任何事件。

stream.destroySoon()

等写入队列处理完毕再关闭文件描述符。

stream.pipe(destination, [options])

这是 Stream.prototype 的方法,所有 Stream 都可使用。

连接到可写目标数据流 destination,本数据流传入的数据将写入 destination 。目标和源将通过必要的暂停或恢复操作来保持同步。

模拟 Unix cat 命令:

process.stdin.resume();
process.stdin.pipe(process.stdout);

源触发 end 事件时,目标默认会调用 end(),因此 destination 不再可写。传入 { end: false } 作为 options 参数以确保目标数据流不被关闭。

这将使 process.stdout 保持打开状态,标准输入关闭后还能向标准输出写入“Goodbye”:

process.stdin.resume();

process.stdin.pipe(process.stdout, { end: false });

process.stdin.on("end", function() {
  process.stdout.write("Goodbye\n");
});

注意:如果源数据流不支持 pause()resume(),此函数将给源数据流添加简单的 pause()resume() 定义:仅触发 'pause''resume' 事件。

Writable Stream 可写流

Writable Stream 有如下的方法、成员和事件:

'drain' 事件

function () { }

write() 方法被调用并返回 false 后触发,表示它可以安全地再次写入。

'error' 事件

function (exception) { }

出错时触发,生成 exception 异常。

'close' 事件

function () { }

底层文件描述符被关闭时触发。

'pipe' 事件

function (src) { }

该数据流被传入另一可读数据流的 pipe 方法时触发。

stream.writable

一个布尔值,默认为 true,出错或者调用 end() / destroy() 之后变成 false

stream.write(string, encoding='utf8', [fd])

以给定的 encoding 编码向数据流写入字符串 string。如果字符串成功写到到内核缓冲区则返回 true。返回 false 说明内核缓冲区已满,数据将延迟发送。'drain' 事件意味着内核缓冲区又为空(可写)了。encoding 默认为 'utf8'

如果指定了可选的 fd 参数,它将被当作以流的形式来发送的整形文件描述符。只支持 UNIX 数据流,否则会忽略而不作任何提示。当以这种方式发送文件描述符时,在数据流写入队列清空前关闭文件描述符会导致发送无效(已关闭)文件描述符。

stream.write(buffer)

同上,区别在于使用 Buffer 对象。

stream.end()

通过 EOF 或 FIN 来终止数据流。

stream.end(string, encoding)

以给定的 encoding 编码发送 string,并通过 FIN 或 EOF 来终止数据流。这将减少数据包的发送数量。

stream.end(buffer)

同上,区别在于使用 Buffer 对象。

stream.destroy()

关闭底层的文件描述符。数据流将不再触发任何事件。

stream.destroySoon()

等写入队列清空后再关闭文件描述符。如果写入队列中没有数据,destroySoon() 将被直接摧毁。