穩(wěn)定性: 3 - 文檔

本節(jié)介紹Node.js中ZLIB模塊的使用，你可以通過以下方式訪問這個模塊：

var zlib = require('zlib');

這個模塊提供了對Gzip/Gunzip, Deflate/Inflate, 和 DeflateRaw/InflateRaw類的綁定。每個類都有相同的參數和可讀/寫的流。

例子

壓縮/解壓縮一個文件，可以通過倒流（piping）一個fs.ReadStream到zlib流里來，再到一個fs.fs.WriteStream：

var gzip = zlib.createGzip();
var fs = require('fs');
var inp = fs.createReadStream('input.txt');
var out = fs.createWriteStream('input.txt.gz');

inp.pipe(gzip).pipe(out);

一步壓縮/解壓縮數據可以通過一個簡便方法來實現(xiàn)。

var input = '.................................';
zlib.deflate(input, function(err, buffer) {
  if (!err) {
    console.log(buffer.toString('base64'));
  }
});

var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
zlib.unzip(buffer, function(err, buffer) {
  if (!err) {
    console.log(buffer.toString());
  }
});

要在一個HTTP客戶端或服務器中使用這個模塊，可以在請求時使用accept-encoding，響應時使用content-encoding頭。

注意: 這些例子只是簡單展示了基本概念。Zlib編碼可能消耗非常大，并且結果可能要被緩存。更多使用 zlib 相關的速度/內存/壓縮的權衡選擇細節(jié)參見后面的Memory Usage Tuning。

// client request example
var zlib = require('zlib');
var http = require('http');
var fs = require('fs');
var request = http.get({ host: 'izs.me',
                         path: '/',
                         port: 80,
                         headers: { 'accept-encoding': 'gzip,deflate' } });
request.on('response', function(response) {
  var output = fs.createWriteStream('izs.me_index.html');

  switch (response.headers['content-encoding']) {
    // or, just use zlib.createUnzip() to handle both cases
    case 'gzip':
      response.pipe(zlib.createGunzip()).pipe(output);
      break;
    case 'deflate':
      response.pipe(zlib.createInflate()).pipe(output);
      break;
    默認：
      response.pipe(output);
      break;
  }
});

// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
var zlib = require('zlib');
var http = require('http');
var fs = require('fs');
http.createServer(function(request, response) {
  var raw = fs.createReadStream('index.html');
  var acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  // Note: this is not a conformant accept-encoding parser.
  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (acceptEncoding.match(/\bdeflate\b/)) {
    response.writeHead(200, { 'content-encoding': 'deflate' });
    raw.pipe(zlib.createDeflate()).pipe(response);
  } else if (acceptEncoding.match(/\bgzip\b/)) {
    response.writeHead(200, { 'content-encoding': 'gzip' });
    raw.pipe(zlib.createGzip()).pipe(response);
  } else {
    response.writeHead(200, {});
    raw.pipe(response);
  }
}).listen(1337);

zlib.createGzip([options])

根據參數options返回一個新的Gzip對象。

zlib.createGunzip([options])

根據參數options返回一個新的Gunzip對象。

zlib.createDeflate([options])

根據參數options返回一個新的Deflate對象。

zlib.createInflate([options])

根據參數options返回一個新的Inflate對象。

zlib.createDeflateRaw([options])

根據參數options返回一個新的DeflateRaw對象。

zlib.createInflateRaw([options])

根據參數options返回一個新的InflateRaw對象。

zlib.createUnzip([options])

根據參數options返回一個新的Unzip對象。

Class: zlib.Zlib

這個類未被zlib模塊導出。之所以寫在這，是因為這是壓縮/解壓縮類的基類。

zlib.flush([kind], callback)

參數kind默認為zlib.Z_FULL_FLUSH。

刷入緩沖數據。不要輕易調用這個方法，過早的刷會對壓縮算法產生負面影響。

zlib.params(level, strategy, callback)

動態(tài)更新壓縮基本和壓縮策略。僅對deflate算法有效。

zlib.reset()

重置壓縮/解壓縮為默認值。僅適用于inflate和deflate算法。

Class: zlib.Gzip

使用gzip壓縮數據。

Class: zlib.Gunzip

使用gzip解壓縮數據。

Class: zlib.Deflate

使用deflate壓縮數據。

Class: zlib.Inflate

解壓縮deflate流。

Class: zlib.DeflateRaw

使用deflate壓縮數據，不需要拼接zlib頭。

Class: zlib.InflateRaw

解壓縮一個原始deflate流。

Class: zlib.Unzip

通過自動檢測頭解壓縮一個Gzip-或Deflate-compressed流。

簡便方法

所有的這些方法第一個參數為字符串或緩存，第二個可選參數可以供zlib類使用，回調函數為callback(error, result)。

每個方法都有一個*Sync伴隨方法，它接收相同參數，不過沒有回調。

zlib.deflate(buf[, options], callback)

zlib.deflateSync(buf[, options])

使用Deflate壓縮一個字符串。

zlib.deflateRaw(buf[, options], callback)

zlib.deflateRawSync(buf[, options])

使用DeflateRaw壓縮一個字符串。

zlib.gzip(buf[, options], callback)

zlib.gzipSync(buf[, options])

使用Gzip壓縮一個字符串。

zlib.gunzip(buf[, options], callback)

zlib.gunzipSync(buf[, options])

使用Gunzip解壓縮一個原始的Buffer。

zlib.inflate(buf[, options], callback)

zlib.inflateSync(buf[, options])

使用Inflate解壓縮一個原始的Buffer。

zlib.inflateRaw(buf[, options], callback)

zlib.inflateRawSync(buf[, options])

使用InflateRaw解壓縮一個原始的Buffer。

zlib.unzip(buf[, options], callback)

zlib.unzipSync(buf[, options])

使用Unzip解壓縮一個原始的Buffer。

Options

每個類都有一個選項對象。所有選項都是可選的。

注意：某些選項僅在壓縮時有用，解壓縮時會被忽略。

• flush (默認：zlib.Z_NO_FLUSH)
• chunkSize (默認：16*1024)
• windowBits
• level (僅壓縮有效)
• memLevel (僅壓縮有效)
• strategy (僅壓縮有效)
• dictionary (僅 deflate/inflate 有效, 默認為空字典)

參見deflateInit2和inflateInit2的描述，它們位于http://zlib.net/manual.html#Advanced。

使用內存調優(yōu)

來自zlib/zconf.h，修改為node's的用法:

deflate的內存需求（單位：字節(jié)）：

(1 << (windowBits+2)) +  (1 << (memLevel+9))

windowBits=15的128K加memLevel = 8的128K （缺省值），加其他對象的若干KB。

例如，如果你想減少默認的內存需求（從256K減為128k），設置選項：

{ windowBits: 14, memLevel: 7 }

當然這通常會降低壓縮等級。

inflate的內存需求（單位：字節(jié)）：

1 << windowBits

windowBits=15(默認值)32K 加其他對象的若干KB。

這是除了內部輸出緩沖外chunkSize的大小，默認為16K。

影響zlib的壓縮速度最大因素為level壓縮級別。level越大，壓縮率越高，速度越慢，level越小，壓縮率越小，速度會更快。

通常來說，使用更多的內存選項，意味著node必須減少對zlib掉喲過，因為可以在一個write操作里可以處理更多的數據。所以，這是另一個影響速度和內存使用率的因素，

常量

所有常量定義在zlib.h ，也定義在require('zlib') 。

通常的操作，基本用不到這些常量。寫到文檔里是想你不會對他們的存在感到驚訝。這個章節(jié)基本都來自zlibdocumentation。更多細節(jié)參見http://zlib.net/manual.html#Constants。

允許flush的值：

• zlib.Z_NO_FLUSH
• zlib.Z_PARTIAL_FLUSH
• zlib.Z_SYNC_FLUSH
• zlib.Z_FULL_FLUSH
• zlib.Z_FINISH
• zlib.Z_BLOCK
• zlib.Z_TREES

壓縮/解壓縮函數的返回值。負數代表錯誤，正數代表特殊但正常的事件：

• zlib.Z_OK
• zlib.Z_STREAM_END
• zlib.Z_NEED_DICT
• zlib.Z_ERRNO
• zlib.Z_STREAM_ERROR
• zlib.Z_DATA_ERROR
• zlib.Z_MEM_ERROR
• zlib.Z_BUF_ERROR
• zlib.Z_VERSION_ERROR

壓縮級別：

• zlib.Z_NO_COMPRESSION
• zlib.Z_BEST_SPEED
• zlib.Z_BEST_COMPRESSION
• zlib.Z_DEFAULT_COMPRESSION

壓縮策略：

• zlib.Z_FILTERED
• zlib.Z_HUFFMAN_ONLY
• zlib.Z_RLE
• zlib.Z_FIXED
• zlib.Z_DEFAULT_STRATEGY

data_type字段的可能值：

• zlib.Z_BINARY
• zlib.Z_TEXT
• zlib.Z_ASCII
• zlib.Z_UNKNOWN

deflate的壓縮方法：

• zlib.Z_DEFLATED

初始化zalloc, zfree, opaque：

• zlib.Z_NULL