node

相關技能

fsharp-testing24萬

dogfood22萬

export-download-debugging9.3萬

SKILL.md

唯讀

名稱

node

描述

使用時機

當你處理 Node.js 程式碼時，使用此技能以獲得建構穩健、高效且可維護的 Node.js 應用程式的領域特定知識。

搭配型別剝離的 TypeScript

當為 Node.js 撰寫 TypeScript 時，請使用型別剝離（Node.js 22.6+），而非 ts-node 或 tsx 等建置工具。型別剝離會直接執行 TypeScript，在執行階段移除型別註解，無需轉譯。

型別剝離相容性的關鍵要求：

使用 import type 進行僅型別匯入
使用 const 物件取代列舉
避免命名空間與參數屬性
在匯入中使用 .ts 副檔名

最小範例 — 一個有效的型別剝離 TypeScript 檔案：

// greet.ts
import type { IncomingMessage } from 'node:http';

const greet = (name: string): string => `Hello, ${name}!`;
console.log(greet('world'));

直接執行：

node greet.ts

完整配置與範例請參閱 rules/typescript.md。

常見工作流程

對於多步驟流程，請在查閱相關規則檔案前，遵循以下高層級順序：

優雅關機：註冊訊號處理器（SIGTERM/SIGINT）→ 停止接受新工作 → 排空進行中的請求 → 關閉外部連線（資料庫、快取）→ 以適當的狀態碼退出。請參閱 rules/graceful-shutdown.md。

錯誤處理：定義共用的錯誤基底類別 → 分類錯誤（操作錯誤 vs 程式設計錯誤）→ 新增非同步邊界處理器（process.on('unhandledRejection')）→ 在呼叫堆疊中傳遞型別化錯誤 → 在回應或當機前記錄上下文。請參閱 rules/error-handling.md。

診斷不穩定測試：使用 --test-only 隔離測試 → 檢查共享狀態或計時器相依性 → 檢查非同步清理順序 → 新增重試邏輯作為暫時診斷步驟 → 修復根本原因。請參閱 rules/flaky-tests.md。

診斷卡住的程序/測試（node --test 無回應、「程序未退出」、CI 超時、開啟的控制代碼）：隔離檔案/測試 → 使用明確的超時/報告器執行 → 透過 why-is-node-running（SIGUSR1）檢查控制代碼 → 在資源建立範圍內修補確定性清理 → 重新執行隔離測試及完整測試套件，直到穩定。請參閱 rules/stuck-processes-and-tests.md。

分析慢速路徑：在真實負載下重現 → 使用 --cpu-prof 擷取 CPU 分析 → 識別熱點函式 → 檢查串流背壓或不必要的序列化 → 透過基準測試驗證改善。請參閱 rules/profiling.md 與 rules/performance.md。

高優先級啟用檢查清單（串流 + 快取）

當任務提及 CSV、ETL、資料攝取管線、大型檔案處理、背壓、重複查詢或重複的非同步呼叫去重時，請明確套用此檢查清單：

使用 await pipeline(...) 來自 node:stream/promises（在指引/程式碼中優先於鏈式 .pipe()）。
當資料在串流中被轉換時，至少包含一個明確的 async function* 轉換。
當出現重複工作時，選擇快取策略：
- lru-cache 用於單一程序中有界限的記憶體內重複使用。
- async-cache-dedupe 用於非同步請求去重 / 過時-重新驗證行為。
展示背壓的處理位置（透過 pipeline() 隱式處理，或透過 drain 明確處理）。