后端開發(fā)工具【免費下載鏈接】watchmanWatches files and records, or triggers actions, when they change.項目地址https://gitcode.com/gh_mirrors/watchm/watchman點擊查看免費下載本文以 Watchman 官方文檔 nodejs.md 為核心系統(tǒng)講解如何通過 npm 包fb-watchman在 Node.js 應用中接入 Watchman 文件監(jiān)控服務。你將掌握客戶端的安裝與初始化、能力capability檢測、watch-project建立監(jiān)視、subscribe實時訂閱文件變更、基于抽象時鐘clock的時間約束訂閱以及客戶端全部方法Methods與事件Events的 API 細節(jié)并深入了解這些 API 背后的底層實現原理。1. 安裝與初始化1.1 安裝 npm 包Node.js 客戶端的包名是fb-watchman通過 npm 直接安裝即可$ npm install fb-watchman從倉庫中的 watchman/node/package.json 可以看到該包的核心依賴是bser版本2.1.1它負責實現 Watchman 客戶端與服務端之間的 BSER 二進制協(xié)議編解碼{ name: fb-watchman, version: 2.0.2, main: index.js, dependencies: { bser: 2.1.1 } }1.2 導入并創(chuàng)建客戶端實例var watchman require(fb-watchman); var client new watchman.Client();這里創(chuàng)建出的Client實例繼承自 Node.js 的EventEmitter因此它同時具備了方法調用與事件訂閱兩種能力。從 watchman/node/index.js 的源碼結構看Client內部維護了一個命令隊列commands數組所有通過client.command()發(fā)起的調用都會被異步排隊并在連接建立后按 FIFO先進先出順序依次發(fā)送。如果你希望指定 watchman 可執(zhí)行文件的路徑可以在構造函數中傳入選項var client new watchman.Client({ watchmanBinaryPath: /usr/local/bin/watchman // 絕對路徑默認為 watchman從 PATH 中查找 });本文檔的示例假定你使用的是 npm 倉庫中發(fā)布的最新版fb-watchman包。2. 底層連接原理客戶端是如何找到 watchman 服務的在深入 API 之前先理解客戶端與服務端的連接建立方式這對排查問題很有幫助。從 watchman/node/index.js 的connect()實現可以看到兩條路徑環(huán)境變量直連如果環(huán)境變量WATCHMAN_SOCK已設置例如由 Watchman 的 trigger 命令導出客戶端會直接使用該 socket 路徑建立連接避免額外啟動子進程if (process.env.WATCHMAN_SOCK) { makeSock(process.env.WATCHMAN_SOCK); return; }詢問 CLI 獲取 socket 路徑否則客戶端會通過child_process.spawn執(zhí)行watchman --no-pretty get-sockname命令從返回的 JSON 中解析出sockname字段再建立連接。如果服務尚未運行這一步會順帶把 watchman 服務啟動起來const args [--no-pretty, get-sockname]; // ... const obj JSON.parse(stdout.join()); makeSock(obj.sockname);值得注意的兩個細節(jié)均有源碼依據若watchman二進制不在PATH中spawn 會失敗并拋出ENOENT錯誤客戶端會將錯誤信息改寫為提示安裝 watchman并通過error事件暴露給上層。建立 socket 連接后收到的所有字節(jié)流都交給bser模塊的BunserBuf見 watchman/node/bser/index.js做流式 BSER 解碼。解碼出的每個對象會判斷是否屬于unilateralTags [subscription, log]這兩種單邊unilateral響應——如果是就直接作為同名事件發(fā)出否則視為請求-響應序列中的響應回調對應的命令回調函數。理解了這條鏈路就能明白為什么客戶端可以單獨安裝而不需要 watchman 服務已經運行——連接是惰性建立的第一次調用命令時才會觸發(fā)。3. 檢查 watchman 是否可用capabilityCheck客戶端包可以在未安裝 watchman 服務的情況下先行安裝因此應用必須自行處理服務不可用的情況同時檢測服務端是否支持你的應用所需的能力capabilities。capabilityCheck方法會向服務端發(fā)出一個 version 命令以此查詢服務端的能力列表。var watchman require(fb-watchman); var client new watchman.Client(); client.capabilityCheck({optional:[], required:[relative_root]}, function (error, resp) { if (error) { // error 是一個 Error 對象可能因為 watchman 服務未安裝 // 或 required 數組中列出的某個能力不被服務端支持 console.error(error); } // resp 是擴展后的 version 響應 // {version: 3.8.0, capabilities: {relative_root: true}} console.log(resp); });關于能力檢測的底層邏輯源碼中還有兩點值得了解見 watchman/node/index.js響應結構resp.capabilities是一個對象其鍵是optional與required能力名的并集值取決于該能力是否被服務端支持。版本回退模擬對于不支持 capabilities 協(xié)議的舊版服務端_synthesizeCapabilityCheck()會基于服務端報告的版本號模擬出一份能力表。倉庫內置的版本對照表如下cap_versions能力名引入版本cmd-watch-del-all3.1.1cmd-watch-project3.1relative_root3.3term-dirname3.1term-idirname3.1wildmatch3.7如果required中的能力不被支持回調的error參數會被設置并帶有含義明確的錯誤信息。更多能力列表參見 capabilities.md。4. 建立監(jiān)視watch-project幾乎每個 watchman 操作都圍繞監(jiān)視某個目錄樹展開。你可以反復請求監(jiān)視同一個目錄而不會出錯——watchman 會復用已有的 watch。var watchman require(fb-watchman); var client new watchman.Client(); var dir_of_interest /some/path; client.capabilityCheck({optional:[], required:[relative_root]}, function (error, resp) { if (error) { console.log(error); client.end(); return; } // 發(fā)起監(jiān)視 client.command([watch-project, dir_of_interest], function (error, resp) { if (error) { console.error(Error initiating watch:, error); return; } // 最佳實踐把響應中的 warning 或 error 信息展示給用戶 // 它們可能提示了需要采取的補救措施 if (warning in resp) { console.log(warning: , resp.warning); } // watch-project 可能把你的 dir_of_interest 與樹中更高層級 // 的另一個 watch 合并復用因此務必記錄響應中的 relative_path console.log(watch established on , resp.watch, relative_path, resp.relative_path); }); });為什么relative_path如此重要這是watch-project與舊的watch命令最核心的區(qū)別當目標目錄位于某個已被監(jiān)視的項目根目錄之下時watchman 不會為它單獨建立一個新的根而是復用上層的 watch并通過resp.relative_path告訴你目標目錄相對該 watch 根的位置。后續(xù)的訂閱、查詢都必須帶上這個relative_path作為relative_root否則結果集會錯誤地覆蓋整個上層根目錄。倉庫中的 watchman/node/example.js 對此做了同樣的強調并把resp.watch與resp.relative_path分別保存在root與path_prefix變量中供后續(xù)使用。5. 訂閱實時變更subscribe大多數 Node 應用關心的是實時文件變更通知。在 watchman 中這通過發(fā)出 subscribe 命令來配置。一個訂閱在客戶端連接存續(xù)期間一直有效直到你用 unsubscribe 命令取消它。下面的例子會先為樹中所有匹配查詢表達式的文件生成一輪訂閱結果建立訂閱時的初始快照之后隨著文件變化持續(xù)生成訂閱結果// watch 取自 watch-project 響應中的 resp.watch // relative_path 取自 watch-project 響應中的 resp.relative_path function make_subscription(client, watch, relative_path) { sub { // 匹配 dir_of_interest 下的任意 .js 文件 expression: [allof, [match, *.js]], // 我們關心的字段 fields: [name, size, mtime_ms, exists, type] }; if (relative_path) { sub.relative_root relative_path; } client.command([subscribe, watch, mysubscription, sub], function (error, resp) { if (error) { // 多半是訂閱條件寫錯了 console.error(failed to subscribe: , error); return; } console.log(subscription resp.subscribe established); }); // 訂閱結果通過 subscription 事件發(fā)出。 // 注意該事件對所有訂閱統(tǒng)一觸發(fā)。如果不同訂閱使用了不同的 fields // 你需要自行檢查訂閱名并按需處理不同的數據結構。 // 實際運行中 resp 形如 // // { root: /private/tmp/foo, // subscription: mysubscription, // files: [ { name: node_modules/fb-watchman/index.js, // size: 4768, // exists: true, // type: f } ] } client.on(subscription, function (resp) { if (resp.subscription ! mysubscription) return; resp.files.forEach(function (file) { // 把 Int64 實例轉換為 javascript 整數 const mtime_ms file.mtime_ms; console.log(file changed: file.name, mtime_ms); }); }); }幾點關鍵說明expression表達式[allof, [match, *.js]]表示同時滿足所有子條件這里即匹配任意.js文件名。完整的表達式語法可參考 file-query.md。fields字段列表指定每個文件記錄里包含哪些字段。注意像mtime_ms這類字段在 BSER 協(xié)議中可能以 Int64 形式返回BSER 使用本地字節(jié)序見 watchman/node/bser/index.js示例中用一元加號file.mtime_ms將其安全轉換為 JS 數字。訂閱名作用域訂閱名綁定的是你的客戶端連接不同的客戶端可以放心使用相同的訂閱名而不會沖突。初始快照行為默認情況下watchman 在建立訂閱時會先投遞一遍當前所有匹配文件包括已刪除文件的exists: false記錄應用因此無需在啟動時自行遍歷目錄樹——倉庫中的 watchman/node/example.js 注釋明確指出了這一點。5.1 只訂閱變化之后的文件上面這個例子會在訂閱建立的那一刻為現存以及已刪除的文件生成一輪結果。某些應用不希望這樣。下面的例子演示如何加上邏輯時間約束。watchman 使用抽象時鐘abstract clock跟蹤變更。我們可以在發(fā)起監(jiān)視的同時取得當前時鐘然后把它作為訂閱的時間約束function make_time_constrained_subscription(client, watch, relative_path) { client.command([clock, watch], function (error, resp) { if (error) { console.error(Failed to query clock:, error); return; } sub { // 匹配 dir_of_interest 下的任意 .js 文件 expression: [allof, [match, *.js]], // 我們關心的字段 fields: [name, size, exists, type], // 加上時間約束 since: resp.clock }; if (relative_path) { sub.relative_root relative_path; } client.command([subscribe, watch, mysubscription, sub], function (error, resp) { // 在這里處理訂閱結果 }); }); }since字段接受一個 clockspec例如c:12345:6789這種形式它讓訂閱只報告時鐘之后發(fā)生的變更從而跳過建立訂閱時的存量文件。6. NodeJS API 參考方法Methods6.1 client.capabilityCheck(options, done)capabilityCheck方法向服務端發(fā)出 version 命令以查詢其能力。如果服務端不支持 capabilities 協(xié)議capabilityCheck會基于服務端報告的版本號為一組重要能力模擬出能力響應對應源碼_synthesizeCapabilityCheck與cap_versions表見上文第 3 節(jié)。options參數可包含以下屬性optional可選能力名的數組required必需能力名的數組這些屬性會原樣透傳給底層的version命令。done是命令完成時的回調簽名為(error, result)。單獨調用capabilityCheck而不提供done回調沒有意義。響應對象含有一個capabilities屬性其鍵為optional與required能力名的并集值為true或false取決于能力是否可用。如果required中的任一能力不被服務端支持done回調的error參數會被設置并附帶明確的錯誤消息。client.capabilityCheck({optional:[], required:[relative_root]}, function (error, resp) { if (error) { // error 是一個 Error 對象watchman 服務未安裝 // 或 required 中的能力不被服務端支持 console.error(error); } // resp 是擴展后的 version 響應 // {version: 3.8.0, capabilities: {relative_root: true}} console.log(resp); });6.2 client.command(args [, done])向 watchman 服務發(fā)送一條命令。args是數組第一個元素為命令名后續(xù)元素為命令參數。命令會被排隊并異步分發(fā)——你可以在連接建立前就連續(xù)command()多條命令它們會在連接就緒后按 FIFO 順序依次發(fā)送對應源碼中的commands隊列與sendNextCommand()。done是命令完成時的回調(error, result)如果對結果不感興趣可以省略。client.command([watch-project, process.cwd()], function(error, resp) { if (error) { console.log(watch failed: , error); return; } if (warning in resp) { console.log(warning: , resp.warning); } if (relative_path in resp) { // 我們需要記住并針對 relative_path 做調整 console.log(watching project , resp.watch, relative path to cwd is , resp.relative_path); } else { console.log(watching , resp.watch); } });關于warning字段如果resp中存在warning字段說明 watchman 服務正在傳達一個用戶應當看到并處理的問題。例如當系統(tǒng) watch 資源需要調整時watchman 會給出相關信息以及補救建議。建議所有基于本庫構建的工具把 warning 消息向上傳遞給用戶倉庫示例 watchman/node/example.js 也遵循了這一最佳實踐。6.3 client.end()終止與 watchman 服務的連接。注意它不會等待任何已排隊但尚未發(fā)送的命令。從源碼看end()會先以 The client was ended 為原因取消所有待處理命令逐個以錯誤回調收尾再關閉 socket。7. NodeJS API 參考事件Events客戶端對象會發(fā)出以下事件7.1 事件connect客戶端成功連接到 watchman 服務時觸發(fā)。7.2 事件error到 watchman 服務的 socket 遇到錯誤時觸發(fā)。它也可能在連接建立之前觸發(fā)——例如無法成功執(zhí)行 watchman CLI 二進制來確定與服務端的通信方式時對應第 2 節(jié)中 spawnget-sockname失敗的分支?；卣{會收到一個封裝了錯誤信息的變量。7.3 事件end到 watchman 服務的 socket 關閉時觸發(fā)。結合源碼可見socket 的end事件處理中會先把socket、bunser置空取消所有待處理命令錯誤信息為 The watchman connection was closed最后才發(fā)出end事件。7.4 事件log響應 watchman 服務發(fā)來的單邊logPDU 時觸發(fā)。要啟用它需要先向服務發(fā)送log-level命令// 這非常冗長通常你不應該這么做 client.command([log-level, debug]); client.on(log, function(info) { console.log(info); });7.5 事件subscription響應 watchman 服務發(fā)來的單邊subscriptionPDU 時觸發(fā)。要啟用它需要先向服務發(fā)送subscribe命令// 訂閱關于 .js 文件的通知 client.command([subscribe, process.cwd(), mysubscription, { expression: [match, *.js] }], function(error, resp) { if (error) { // 多半是訂閱條件寫錯了 console.log(failed to subscribe: , error); return; } console.log(subscription resp.subscribe established); } ); // 訂閱結果通過 subscription 事件發(fā)出。 // 注意watchman 在首次訂閱時會先投遞當前所有文件的列表 // 因此啟動時你無需自行遍歷目錄樹 client.on(subscription, function(resp) { console.log(resp.root, resp.subscription, resp.files); });取消訂閱使用unsubscribe命令并傳入要取消的訂閱名client.command([unsubscribe, process.cwd(), mysubscription]);再次強調訂閱名的作用域是你的連接不同客戶端可以使用相同的訂閱名而互不干擾。8. 倉庫中的完整示例與集成測試8.1 開箱即用的完整示例倉庫中的 watchman/node/example.js 是一個可以直接運行的端到端示例覆蓋了上述全部流程監(jiān)聽end與error事件capabilityCheck({required:[relative_root]})檢測服務可用性故意發(fā)送一條無效命令[invalid-command-never-will-work]演示錯誤回調watch-project建立監(jiān)視并妥善處理resp.watch/resp.relative_path建立mysubscription訂閱expression: [allof, [match, *.js]]配合relative_root再通過clocksince建立只關注之后變化的sincesub訂閱。其中sincesub示例還演示了一個實用細節(jié)當訂閱只請求fields: [name]一個字段時訂閱響應中的files會退化為文件名組成的字符串數組而非對象數組。8.2 自動化集成測試watchman 的集成測試通過 Python 的 unittest 驅動 Node.js 腳本來驗證客戶端行為見 watchman/integration/test_nodejs.pyfind_js_tests裝飾器會掃描integration目錄下所有*.js文件為每個腳本動態(tài)生成一個測試類用node_bin執(zhí)行腳本測試會先通過 yarn 在臨時目錄安裝fb-watchman含其bser依賴設置WATCHMAN_SOCK環(huán)境變量指向測試實例的 socket然后運行腳本并校驗退出狀態(tài)碼相關的 JS 測試腳本包括 watchman/integration/node_basic.js 等它們構成了 Node.js 客戶端在真實 watchman 服務上的行為回歸保障。如果你要為自己的項目編寫類似測試可以直接復用這套模式把 watchman/node/index.js 與 watchman/node/bser 作為依賴通過WATCHMAN_SOCK注入 socket 路徑即可在測試環(huán)境中驅動真實服務。9. 實踐要點小結關注點關鍵做法服務可用性任何命令之前先做capabilityCheck并處理error監(jiān)視目錄使用watch-project而非舊watch務必記錄resp.relative_path實時通知subscribesubscription事件用resp.subscription區(qū)分多個訂閱初始快照默認首次訂閱會返回存量文件不需要時用clocksince約束字段與類型fields決定記錄內容Int64 字段用轉成 JS 數字資源釋放退出時調用client.end()連接關閉前排隊中的命令會被取消錯誤處理關注resp.warning它可能是系統(tǒng) watch 資源不足等問題的提示贊分享后端開發(fā)工具【免費下載鏈接】watchmanWatches files and records, or triggers actions, when they change.項目地址https://gitcode.com/gh_mirrors/watchm/watchman點擊查看免費下載相關推薦fb-watchman 使用指南在 Node.js 中接入 Watchman 實現高效文件監(jiān)聽與變更訂閱fb watchman 使用指南在 Node.js 中接入 Watchman 實現高效文件監(jiān)聽與變更訂閱 fb watchman 是 Watchman 文件監(jiān)后端開發(fā)工具Watchman C 客戶端庫實戰(zhàn)指南連接、命令與訂閱的完整用法Watchman C 客戶端庫實戰(zhàn)指南連接、命令與訂閱的完整用法 Watchman 官方提供了面向 C 應用的高層客戶端庫封裝了本地 Watchma后端開發(fā)工具Watchman Java 客戶端庫從構建、BSER 協(xié)議到訂閱使用的完整指南Watchman Java 客戶端庫從構建、BSER 協(xié)議到訂閱使用的完整指南 本指南以倉庫內 watchman/java/README.md https:/后端開發(fā)工具上一篇LeetCode-Book 圖解 LCR 141「訓練計劃 III」雙指針迭代與遞歸兩種方式反轉鏈表下一篇酷安桌面版安裝指南5 分鐘跑起來大屏刷動態(tài)更順手創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考