Node 有一組資料流 API,可以像處理網路串流那樣處理檔案,用起来很方便;但它只支援循序處理,無法隨機讀寫。當你需要更精細的控制,就必須往下走到檔案系統 API 這一層。
本章從基礎談起:如何開啟檔案、讀取其中某一段、寫入資料,以及收尾時把檔案關上。
Node 的檔案 API 幾乎是 UNIX(POSIX)對應 API 的翻版,連檔案描述符的概念都照搬過來。在 Node 裡,檔案描述符是一個整數,代表某個實體在進程檔案描述符表中的索引。
有三個描述符是特別的:0、1、2,分別對應標準輸入、標準輸出與標準錯誤。標準輸入是唯讀串流,進程靠它從主控台或通道讀資料;標準輸出與標準錯誤只用來輸出,前者負責一般進程輸出,後者專門負責錯誤訊息。
進程一啟動這幾個描述符就能用了,但它們背後並沒有對應的實體檔案,而且無法定位到特定位置讀寫——只能像網路串流那樣循序讀寫,寫出去的資料也無法回頭修改。
實體檔案沒有這個限制。在 Node 裡你既可以建立只能往尾端追加的檔案,也可以建立可隨機位置讀寫的檔案。
幾乎所有檔案相關操作都離不開路徑處理,所以我們先談 path 模組,再進到讀寫本身。
路徑分相對與絕對兩種。如果你直接用字串硬接,問題很快出現:有的片段以「/」結尾有的沒有,而路徑分隔符在不同作業系統上還不一樣,程式碼瞬間變得囉嗦又脆弱。
Node 提供了 path 模組來處理這些瑣事:標準化、連接、解析、絕對與相對互轉、提取各段資訊、檢查存在性。基本上它做的都是字串運算,不會去驗證檔案系統(exists 是唯一例外)。
在使用或儲存路徑前先標準化,是個值得堅持的習慣——尤其是那些來自使用者輸入、設定檔,或多段拼接而來的路徑。normalize 還能一併處理 ..、.、重複的 //:
var path = require('path');
path.normalize('/foo/bar//baz/asdf/quux/..');
// => '/foo/bar/baz/asdf'
join 可以連接任意多段路徑:
var path = require('path');
path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// => '/foo/bar/baz/asdf'
如你所見,join 內部會自動做標準化。
resolve 的效果就像對這些路徑依序執行 cd,最後得到一個絕對路徑。與 cd 不同的是,參數可以是檔案,而且不必真的存在——resolve 從不存取檔案系統:
var path = require('path');
path.resolve('/foo/bar', './baz');
// => /foo/bar/baz
path.resolve('/foo/bar', '/tmp/file/');
// => /tmp/file
若解析結果不是絕對路徑,resolve 會把當前工作目錄接在後面:
path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
// 若當前工作目錄是 /home/myself/node,則回傳
// => /home/myself/node/wwwroot/static_files/gif/image.gif
relative 告訴你「從 A 走到 B 該怎麼走」:
var path = require('path');
path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb');
// => ../../impl/bbb
拿到目錄部分用 dirname:
path.dirname('/foo/bar/baz/asdf/quux.txt');
// => /foo/bar/baz/asdf
拿到檔名用 basename:
path.basename('/foo/bar/baz/asdf/quux.html');
// => quux.html
basename 還能接第二個參數指定副檔名,回傳時自動剝除:
path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// => quux
要這麼做,你得先知道副檔名是什麼,用 extname 取得:
path.extname('/a/b/index.html');
// => '.html'
path.extname('/a/b.c/index');
// => ''
path.extname('/a/b.c/.');
// => ''
path.extname('/a/b.c/d.');
// => '.'
前面的操作都不碰檔案系統,但有些時候你就是得問一句「這個檔案在不在」。例如建立檔案或目錄前先確認它不存在:
var path = require('path');
path.exists('/etc/passwd', function(exists) {
console.log('exists:', exists); // => true
});
path.exists('/does_not_exist', function(exists) {
console.log('exists:', exists); // => false
});
注意:從 Node 0.8 起,exists 從 path 模組搬到了 fs 模組,改名為 fs.exists,其餘行為不變:
var fs = require('fs');
fs.exists('/does_not_exist', function(exists) {
console.log('exists:', exists); // => false
});
exists 是 I/O 操作,因此是等非同步的,需要回呼函式接收結果。也有同步版本 existsSync(),行為相同但直接回傳:
var path = require('path');
path.existsSync('/etc/passwd');
// => true
fs 模組囊括了所有檔案查詢與處理的函式。先引入:
var fs = require('fs');
想知道檔案大小、建立時間或權限,用 stat 查詢中介資料:
var fs = require('fs');
fs.stat('/etc/passwd', function(err, stats) {
if (err) { throw err; }
console.log(stats);
});
輸出大致長這樣:
{ dev: 234881026,
ino: 95028917,
mode: 33188,
nlink: 1,
uid: 0,
gid: 0,
rdev: 0,
size: 5086,
blksize: 4096,
blocks: 0,
atime: Fri, 18 Nov 2011 22:44:47 GMT,
mtime: Thu, 08 Sep 2011 23:50:04 GMT,
ctime: Thu, 08 Sep 2011 23:50:04 GMT }
回呼收到的 stats 物件提供了一組型別判斷方法,省去你自己解位元遮罩:
isFile():是普通檔案(而非目錄、socket、符號連結或裝置)isDirectory():是目錄isBlockDevice():是區塊裝置,多數 UNIX 系統中位於 /dev 底下isCharacterDevice():是字元裝置isSymbolicLink():是符號連結isFIFO():是 UNIX 命名管道isSocket():是 UNIX socket讀寫之前必須先用 open 把檔案打開,回呼會拿到檔案描述符,之後靠它操作這個已開啟的檔案:
var fs = require('fs');
fs.open('/path/to/file', 'r', function(err, fd) {
// 拿到了 fd(檔案描述符)
});
第二個參數是模式旗標,決定以什麼方式開啟(以下說明整理自 UNIX fopen 文件):
選錯旗標會直接吃掉既有資料,這是最常見的初學者事故之一。
讀檔之前得先準備一個緩衝區來承接資料,這個緩衝物件會作為參數傳給 fs.read,並被它填滿:
var fs = require('fs');
fs.open('./my_file.txt', 'r', function opened(err, fd) {
if (err) { throw err }
var readBuffer = new Buffer(1024),
bufferOffset = 0,
bufferLength = readBuffer.length,
filePosition = 100;
fs.read(fd,
readBuffer,
bufferOffset,
bufferLength,
filePosition,
function read(err, readBytes) {
if (err) { throw err; }
console.log('just read ' + readBytes + ' bytes');
if (readBytes > 0) {
console.log(readBuffer.slice(0, readBytes));
}
});
});
這段程式開啟檔案後,要求從第 100 個位元組開始讀 1024 個位元組。read 的回呼會在兩種情況下被觸發:讀取成功,或已無資料可讀(錯誤則由第一個參數表達)。
回呼參數的約定是:若有錯誤,第一個參數是錯誤物件,否則為 null;成功時第二個參數說明實際讀入多少位元組,值為 0 代表已到達檔案結尾。
這裡有個容易忽略的細節:緩衝物件一旦交給 fs.read,控制權就轉移出去了,直到回呼被觸發才回到你手上。在這之前不要讀寫它、也不要讓其他函式碰它,否則你可能讀到不完整資料,更糟的情況是併發寫入同一塊記憶體。
寫檔同樣靠緩衝物件:
var fs = require('fs');
fs.open('./my_file.txt', 'a', function opened(err, fd) {
if (err) { throw err; }
var writeBuffer = new Buffer('writing this string'),
bufferPosition = 0,
bufferLength = writeBuffer.length,
filePosition = null;
fs.write(fd,
writeBuffer,
bufferPosition,
bufferLength,
filePosition,
function wrote(err, written) {
if (err) { throw err; }
console.log('wrote ' + written + ' bytes');
});
});
這裡以附加模式開啟檔案,然後寫入資料。write 需要連帶幾項資訊:緩衝物件本身、從緩衝哪個位置開始取、取多長、寫到檔案的哪個位置、以及完成後的回呼。
本例中 filePosition 為 null,代表寫到檔案指標目前所在的位置;因為是附加模式,指標就在檔案末尾。同樣地,write 執行期間不要碰那個緩衝物件,等回呼被觸發再說。
你可能注意到,前面的範例都沒寫關檔程式碼。這是因為它們短小、只用一次,而 Node 進程結束時作業系統會保證把檔案關掉。
但在真實應用裡,開了就要負責關。你需要追蹤所有已開啟的描述符,並在不再使用時呼叫 fs.close(fd[, callback])。實務上很容易漏掉某個分支,尤其是錯誤路徑。下面這個寫法示範了如何把關檔做乾淨:
var fs = require('fs');
function openAndWriteToSystemLog(writeBuffer, callback) {
fs.open('./my_file', 'a', function opened(err, fd) {
if (err) { return callback(err); }
function notifyError(err) {
fs.close(fd, function() {
callback(err);
});
}
var bufferOffset = 0,
bufferLength = writeBuffer.length,
filePosition = null;
fs.write(fd, writeBuffer, bufferOffset, bufferLength, filePosition,
function wrote(err, written) {
if (err) { return notifyError(err); }
fs.close(fd, function() {
callback(err);
});
}
);
});
}
openAndWriteToSystemLog(
new Buffer('writing this string'),
function done(err) {
if (err) {
console.log("error while opening and writing:", err.message);
return;
}
console.log('All done with no errors');
}
);
這個函式接受一個裝著待寫資料的緩衝,以及一個完成或出錯時呼叫的回呼;出錯時錯誤物件會放在回呼的第一個參數。特別留意內部的 notifyError——它負責在錯誤路徑上把檔案關掉並回報,這是避免描述符洩漏的關鍵。
最後補充:底層原子操作之外,Node 還有一層更高階的包裝。若你想讓多個寫入操作安全地併發追加到同一個檔案,可以用 WriteStream;若你想讀取檔案的某個區段,可以考慮 ReadStream。這兩者屬於資料串流的主題。
處理檔案時,多數時間你都在跟路徑打交道:連接、標準化、計算差異、相對與絕對互轉,以及取出副檔名、檔名、目錄等片段,這些交給 path 模組即可。
真正的讀寫則落在 fs 模組的底層 API 上,以檔案描述符為中心:open 開啟、read 讀取、write 寫入、close 關閉。
切記一件事:只要有可能出錯,就必須在函式返回前把已開啟的描述符關掉,錯誤路徑尤其容易被遺漏。