node stream流

stream 模块可以通过以下方式使用：

const stream = require('stream');

Node.js 中有四种基本的流类型：

Writable - 可写入数据的流（例如 fs.createWriteStream()）。
Readable - 可读取数据的流（例如 fs.createReadStream()）。
Duplex - 可读又可写的流（例如 net.Socket）。
Transform - 在读写过程中可以修改或转换数据的 Duplex 流（例如 zlib.createDeflate()）

缓冲

可写流和可读流都会在一个内部的缓冲器中存储数据，可以分别使用的 writable.writableBuffer 或 readable.readableBuffer 来获取。

可缓冲的数据的数量取决于传入流构造函数的 highWaterMark 选项。对于普通的流，highWaterMark 选项指定了字节的总数量。对于以对象模式运作的流，highWaterMark 指定了对象的总数量。

当调用 stream.push(chunk) 时，数据会被缓冲在可读流中。如果流的消费程序没有调用 stream.read()，则这些数据会停留在内部队列中，直到被消费。

一旦内部的可读缓冲的总大小达到 highWaterMark 指定的阈值时，流会暂时停止从底层资源读取数据，直到当前缓冲的数据被消费（也就是说，流会停止调用内部的用于填充可读缓冲的 readable._read() 方法）。

当反复地调用 writable.write(chunk) 方法时，数据会被缓冲在可写流中。当内部的可写缓冲的总大小小于 highWaterMark 设置的阈值时，调用 writable.write() 会返回 true。一旦内部缓冲的大小达到或超过 highWaterMark 时，则会返回 false。

stream API 的主要目标，特别是 stream.pipe() 方法，是为了限制数据的缓冲到可接受的程度，也就是读写速度不一致的源头与目的地不会压垮可用的内存。

因为 Duplex 和 Transform 都是可读又可写的，所以它们各自维护着两个相互独立的内部缓冲器用于读取和写入，这使得它们在维护数据流时，读取和写入两边可以各自独立地运作。例如，net.Socket 实例是 Duplex 流，它的可读端可以消费从 socket 接收的数据，而可写端则可以将数据写入到 socket。因为数据写入到 socket 的速度可能比接收数据的速度快或者慢，所以在读写两端独立地进行操作（或缓冲）就显得很重要了。

Stream是Node.js中非常重要的一个模块，应用广泛。一个流是一个具备了可读、可写或既可读又可写能力的接口，通过这些接口，我们可以和磁盘文件、套接字、HTTP请求来交互，实现数据从一个地方流动到另一个地方的功能。

所有的流都实现了EventEmitter的接口，具备事件能力，通过发射事件来反馈流的状态。比如有错误发生时会发射“error”事件，有数据可被读取时发射“data”事件。这样我们就可以注册监听器来处理某个事件，达到我们的目的。

Node.js定义了Readable、Writable、Duplex、Transform四种流，Node.js有各种各样的模块，分别实现了这些流，我们挑出来一一看一看他们的用法。当然，我们也可以实现自己的流，可以参考Stream的文档或我们即将提到的这些Node.js里的实现。

Readable
Readable流提供了一种将外部来源（比如文件、套接字等）的数据读入到应用程序的机制。

可读的流有两种模式：流动模式和暂停模式。流动模式下，数据会自动从来源流出，跟不老泉似的，直到来源的数据耗尽。暂停模式下，你得通过stream.read()主动去要数据，你要了它才从来源读，你不要它就在那儿耗着等你。

可读流在创建时都是暂停模式。暂停模式和流动模式可以互相转换。

要从暂停模式切换到流动模式，有下面三种办法：

给“data”事件关联了一个处理器
显式调用resume()
调用pipe()将可读流桥接到一个可写流上
要从流动模式切换到暂停模式，有两种途径：

如果这个可读的流没有桥接可写流组成管道，直接调用pause()
如果这个可读的流与若干可写流组成了管道，需要移除与“data”事件关联的所有处理器，并且调用unpipe()方法断开所有管道。
需要注意的是，出于向后兼容的原因，移除“data”事件的处理器，可读流并不会自动从流动模式转换到暂停模式；还有，对于已组成管道的可读流，调用pause也不能保证这个流会转换到暂停模式。

Readable流的一些常见实例如下：

客户端的HTTP响应
服务端的HTTP请求
fs读取流
zlib流
crypto（加密）流
TCP套接字
子进程的stdout和stderr
process.stdin
Readable流提供了以下事件：

readable：在数据块可以从流中读取的时候发出。它对应的处理器没有参数，可以在处理器里调用read([size])方法读取数据。
data：有数据可读时发出。它对应的处理器有一个参数，代表数据。如果你只想快快地读取一个流的数据，给data关联一个处理器是最方便的办法。处理器的参数是Buffer对象，如果你调用了Readable的setEncoding(encoding)方法，处理器的参数就是String对象。
end：当数据被读完时发出。对应的处理器没有参数。
close：当底层的资源，如文件，已关闭时发出。不是所有的Readable流都会发出这个事件。对应的处理器没有参数。
error：当在接收数据中出现错误时发出。对应的处理器参数是Error的实例，它的message属性描述了错误原因，stack属性保存了发生错误时的堆栈信息。
Readable还提供了一些函数，我们可以用它们读取或操作流：

read([size])：如果你给read方法传递了一个大小作为参数，那它会返回指定数量的数据，如果数据不足，就会返回null。如果你不给read方法传参，它会返回内部缓冲区里的所有数据，如果没有数据，会返回null，此时有可能说明遇到了文件末尾。read返回的数据可能是Buffer对象，也可能是String对象。
setEncoding(encoding)：给流设置一个编码格式，用于解码读到的数据。调用此方法后，read([size])方法返回String对象。
pause()：暂停可读流，不再发出data事件
resume()：恢复可读流，继续发出data事件
pipe(destination,[options])：把这个可读流的输出传递给destination指定的Writable流，两个流组成一个管道。options是一个JS对象，这个对象有一个布尔类型的end属性，默认值为true，当end为true时，Readable结束时自动结束Writable。注意，我们可以把一个Readable与若干Writable连在一起，组成多个管道，每一个Writable都能得到同样的数据。这个方法返回destination，如果destination本身又是Readable流，就可以级联调用pipe（比如我们在使用gzip压缩、解压缩时就会这样，马上会讲到）。
unpipe([destination])：端口与指定destination的管道。不传递destination时，断开与这个可读流连在一起的所有管道。
好吧，大概就这些了，我们来举一个简单的使用Readable的例子。以fs模块为例吧。

fs.ReadStream实现了stream.Readable，另外还提供了一个“open”事件，你可以给这个事件关联处理器，处理器的参数是文件描述符（一个整型数）。

fs.createReadStream(path[, options])用来打开一个可读的文件流，它返回一个fs.ReadStream对象。path参数指定文件的路径，可选的options是一个JS对象，可以指定一些选项，类似下面这样：

{ flags: 'r',
encoding: 'utf8',
fd: null,
mode: 0666,
autoClose: true }

options的flags属性指定用什么模式打开文件，’w’代表写，’r’代表读，类似的还有’r+’、’w+’、’a’等，与Linux下的open函数接受的读写模式类似。encoding指定打开文件时使用编码格式，默认就是“utf8”，你还可以为它指定”ascii”或”base64”。fd属性默认为null，当你指定了这个属性时，createReadableStream会根据传入的fd创建一个流，忽略path。另外你要是想读取一个文件的特定区域，可以配置start、end属性，指定起始和结束（包含在内）的字节偏移。autoClose属性为true（默认行为）时，当发生错误或文件读取结束时会自动关闭文件描述符。

OK，背景差不多了，可以上代码了，readable.js文件内容如下：

var fs = require('fs');
var readable = fs.createReadStream('readable.js',{
flags: 'r',
encoding: 'utf8',
autoClose: true,
mode: 0666,
});
readable.on('open', function(fd){
console.log('file was opened, fd - ', fd);
});
readable.on('readable', function(){
console.log('received readable');
});
readable.on('data', function(chunk){
console.log('read %d bytes: %s', chunk.length, chunk);
});
readable.on('end', function(){
console.log('read end');
});
readable.on('close', function(){
console.log('file was closed.');
});
readable.on('error', function(err){
console.log('error occured: %s', err.message);
});

示例代码把readable.js的内容读取出来，关联了各种事件，演示了读取文件的一般用法。

Writable
Writable流提供了一个接口，用来把数据写入到目的设备（或内存）中。Writable流的一些常见实例：

客户端的HTTP请求
服务器的HTTP响应
fs写入流
zlib流
crypto（加密）流
TCP套结字
子进程的stdin
process.stdout和process.stderr
Writable流的write(chunk[,encoding] [,callback])方法可以把数据写入流中。其中，chunk是待写入的数据，是Buffer或String对象。这个参数是必须的，其它参数都是可选的。如果chunk是String对象，encoding可以用来指定字符串的编码格式，write会根据编码格式将chunk解码成字节流再来写入。callback是数据完全刷新到流中时会执行的回调函数。write方法返回布尔值，当数据被完全处理后返回true（不一定是完全写入设备哦）。

Writable流的end([chunk] [,encoding] [,callback])方法可以用来结束一个可写流。它的三个参数都是可选的。chunk和encoding的含义与write方法类似。callback是一个可选的回调，当你提供它时，它会被关联到Writable的finish事件上，这样当finish事件发射时它就会被调用。

Writable还有setDefaultEncoding等方法，具体可以参考在线文档。

现在我们来看看Writable公开的事件：

finish：在end()被调用、所有数据都已被写入底层设备后发射。对应的处理器函数没有参数。
pipe：当你在Readable流上调用pipe()方法时，Writable流会发射这个事件，对应的处理器函数有一个参数，类型是Readable，指向与它连接的那个Readable流。
unpipe：当你在Readable流上调用unpipe()方法时，Writable流会发射这个事件，对应的处理器函数有一个参数，类型是Readable，指向与刚与它断开连接的那个Readable流。
error：出错时发射，对应的处理器函数的参数是Error对象。
OK，让我们来举两个小例子。一个是fs的，一个是socket的。

fs.createWriteStream(path[,options])用来创建一个可写的文件流，它返回fs.WriteStream对象。第一个参数path是路径，第二个参数options是JS对象，是可选的，指定创建文件时的选项，类似：

{
    flags: 'w',
    defaultEncoding: 'utf8',
    fd: null,
    mode: 0666
 }

defaultEncoding指定默认的文本编码。前面讲fs.createReadStream时提到了。

writeFile.js内容如下：

var fs = require('fs');
var writable = fs.createWriteStream('example.txt',{
flags: 'w',
defaultEncoding: 'utf8',
mode: 0666,
});
writable.on('finish', function(){
console.log('write finished');
process.exit(0);
});
writable.on('error', function(err){
console.log('write error - %s', err.message);
});
writable.write('My name is 火云邪神', 'utf8');
writable.end();

很简单的一个示例，注意writeFile.js的文件编码格式要是UTF8哦。

下面看一个使用TCP套接字的示例，echoServer2.js内容如下：

var net = require("net");
var server = net.createServer(function(sock){
    sock.setEncoding('utf8');
    sock.on('pipe', function(src){
    console.log('piped');
});
    sock.on('error', function(err){
        console.log('error - %s', err.message);
    });
    sock.pipe(sock);
});
server.maxConnections = 10;
server.listen(7, function(){
    console.log('echo server bound at port - 7');
});

上面的echoServer功能和我们之前在Node.js开发入门——套接字(socket)编程中的echoServer一样。不同的是，这里使用了pipe方法，而那个版本监听data事件，调用write方法将收到的数据回写给客户端。

sock.Socket是Duplex流，既实现了Readable又实现了Writable，所以，sock.pipe(sock)是正确的调用。

常见的Duplex流有：

TCP socket
zlib
crypto
Duplex是Readable和Writable的合体。

Transform
Transform扩展了Duplex流，它会修改你使用Writable接口写入的数据，当你用Readable接口来读时，数据已经发生了变化。

比较常见的Transform流有：

zlib
crypto
好啦，我们举一个简单的示例，使用zlib模块来压缩和解压缩。示例文件是zlibFile.js，内容如下：

var zlib = require("zlib");
var gzip = zlib.createGzip();
var fs = require('fs');
var inFile = fs.createReadStream('readable.js');
var outGzip = fs.createWriteStream('readable.gz');
//inFile - Readable
//gzip - Transform(Readable && Writable)
//outFile - Writable
inFile.pipe(gzip).pipe(outGzip);
setTimeout(function(){
    var gunzip = zlib.createUnzip({flush: zlib.Z_FULL_FLUSH});
    var inGzip = fs.createReadStream('readable.gz');
    var outFile = fs.createWriteStream('readable.unzipped');
    inGzip.pipe(gunzip).pipe(outFile);
}, 5000);

上面的示例比较简单，使用了zlib模块，文档在这里：https://nodejs.org/api/zlib.html。

接下来我们来实现一个Transform流，把输入数据中的小写字母转换为大写字母。我们代码在upperTransform.js里，内容如下：

var fs = require('fs');
var util = require('util');
var stream = require('stream');
util.inherits(UpperTransform, stream.Transform);
function UpperTransform(opt){
stream.Transform.call(this, opt);
}
UpperTransform.prototype._transform = function(chunk, encoding, callback){
var data = new Buffer(chunk.length);
var str = chunk.toString('utf8');
for(var i = 0, offset=0; i < str.length; i++){
if(/^[a-z]+$/.test(str[i])){
offset += data.write(str[i].toUpperCase(), offset);
}else{
offset += data.write(str[i], offset);
}
}
this.push(data);
callback();
}
UpperTransform.prototype._flush = function(cb){
cb();
}
var upper = new UpperTransform();
var inFile = fs.createReadStream('example.txt');
inFile.setEncoding('utf8');
var outFile = fs.createWriteStream('exampleUpper.txt',{defaultEncoding: 'utf8'});
inFile.pipe(upper).pipe(outFile);

为了实现自定义的Transform，需要先继承Transform流的功能。实现这一点最简单的办法就是使用util模块的inherits()方法，然后在你的构造器里调用使用call方法把父对象应用到当前对象上。代码就是下面这部分：

util.inherits(UpperTransform, stream.Transform);
function UpperTransform(opt){
stream.Transform.call(this, opt);
}

继承了stream.Transform之后，实现_transform和_flush即可。在_transform里，我们先创建了一个缓冲区，然后把传入的数据（chunk）转换成字符串（写死为utf8了），接着遍历字符串，遇见小写字母就转换一下，写入创建的缓冲区里，完成转换后，调用push方法，把转换后的数据加到内部的数据队列中。

其它的就比较简单了。注意，作为示例，我们只转换utf8编码的文本文件。