使用 JSDoc 為 Code 節點提供 TypeScript 智能提示支援 - n8n 工作流程

資深 n8n 使用者: 經常使用 Code 節點來編寫客製化邏輯的開發者。
自動化專家: 需要強大除錯工具來建構複雜 n8n 工作流系統的人員。
技術內容創作者: 負責記錄或分享高效率 n8n 開發最佳實踐的人員。
任何使用者: 想在 n8n 範本中提升程式碼品質並減少錯誤的使用者。

當使用 JavaScript Code n8n 節點時，若沒有適當的自動完成功能，除錯和存取複雜的輸入物件（例如來自 n8n 節點或 API 操作的回傳物件）會變得相當棘手。這個特定的 n8n 工作流透過利用 JavaScript 生態系中廣泛使用的 JSDoc 註解方法來解決這個問題。

透過定義物件的預期結構——例如透過 n8n API 節點檢索到的 Workflow 物件——您可以為 n8n 編輯器內建的程式碼功能提供強大的型別提示。這將帶來 TypeScript 等級的智能提示，使您在 n8n 工作流中編寫、維護和除錯複雜的客製化腳本變得更加高效可靠。這項技術對於提升任何穩健 n8n 範本的開發速度來說，都極其寶貴。

這個示範性的 n8n 工作流利用以下四個關鍵步驟來說明智能提示技術：

1. 觸發器 (表單提交時): 此流程使用基本的 Form n8n 觸發器啟動，允許為了測試而手動啟動 n8n 工作流。


2. 擷取工作流資料 (取得此工作流): n8n 的 Get This Workflow 節點設定為使用 get 操作來檢索當前執行 n8n 工作流的完整中繼資料結構。這個複雜的 JSON 物件會傳遞給下一個 n8n 節點。


3. 套用智能提示 (帶有智能提示的程式碼): 這個 Code n8n 節點是核心示範。它定義了兩個 JSDoc 型別定義 (@typedef {Object} Node 和 / @typedef {Object} Workflow /)。接著使用行內 JSDoc 註解 (/ @type {Workflow} /) 將傳入的 JSON 轉換型別到變數 wf 上。這個操作使得在 Code n8n 節點內存取屬性如 wf.id、wf.name 以及迭代 wf.nodes 時，能獲得完美的智能提示。


4. 顯示結果 (顯示結果): 最後一個 Form n8n 節點將上一步驟 Code n8n 節點的輸出結果以有條理的 HTML 格式顯示出來，以證明前置 n8n 節點的功能性。

若想在您自己的 n8n 範本中安裝並使用這項強大的開發技術，請遵循以下步驟：

1. 匯入: 複製提供的 n8n 工作流 JSON，並透過「從 JSON 匯入」選項貼到您的 n8n 實例中。


2. n8n API 憑證: 'Get This Workflow' n8n 節點需要配置名稱為 n8n unio API v1 的有效 n8n API 憑證。請確保您已在 n8n 中設定好有效的 API 金鑰。


3. 執行: 執行 'On form submission' n8n 觸發器或手動測試 n8n 工作流。在編輯 'Code With Intellisense' n8n 節點時觀察：當您將滑鼠懸停在或輸入物件屬性（如 wf.）時，現在應該會顯示有用的程式碼建議。

表單提交時 (n8n 觸發器): 作為測試此 n8n 工作流的起始點。它是一個標準的 HTTP n8n 觸發機制。
取得此工作流 (n8n 節點): 使用 n8n 內部 API 來檢索當前執行 n8n 工作流的完整 JSON 表示形式。這提供了 JSDoc 範例所需的複雜物件結構。
帶有智能提示的程式碼 (Code n8n 節點): 核心元件。它使用 JSDoc 定義複雜型別，特別是 Workflow 和 Node 型別。關鍵配置在於行內型別轉換：const wf = / @type {Workflow} / ($input.first().json);，這對於在 n8n 範本中編碼時啟用強大的智能提示功能至關重要。

• 顯示結果 (Form n8n 節點): 將 Code n8n 節點執行結果輸出到一個格式整齊的 HTML 頁面，即時提供 n8n 工作流邏輯成功的視覺回饋。