قدرت‌نمایی با نود Code در n8n: راهنمای جامع جاوااسکریپت برای اتوماسیون‌های پیشرفته در 1404

برخلاف تصور رایج، محدودیت اصلی ابزارهای Low-Code/No-Code مانند n8n، ضعف در اتصال به APIها یا کمبود نودهای آماده نیست.

محدودیت واقعی زمانی آشکار می‌شود که شما، به عنوان یک معمار فنی، با یک منطق تجاری (Business Logic) پیچیده و غیر استاندارد روبرو می‌شوید. سناریویی را تصور کنید که در آن یک API داخلی، داده‌ها را با ساختاری نامتعارف و نیازمند پاکسازی بازمی‌گرداند.

نودهای بصری مانند Set در این نقطه به بن‌بست می‌رسند. آن‌ها برای عملیات ساده و خطی طراحی شده‌اند، نه برای مدیریت منطق‌های تودرتو، تبدیل داده‌های پیچیده یا اجرای الگوریتم‌های خاص.

اینجاست که ورک‌فلو شما در پلتفرم اتوماسیون n8n از یک ابزار توانمندسازی به یک قفس دیجیتال تبدیل می‌شود. درد ناشی از این محدودیت، لحظه‌ای است که متوجه می‌شوید ابزار به جای شما تصمیم می‌گیرد.

نود Code، فراتر از یک ویژگی، یک بیانیه است: کنترل نهایی، همواره در دستان توسعه‌دهنده باقی می‌ماند. این نود، دریچه‌ای به موتور Node.js است که n8n بر پایه آن ساخته شده و به شما اجازه می‌دهد از محدودیت‌های رابط کاربری فراتر رفته و هر منطقی را که با جاوااسکریپت قابل پیاده‌سازی است، اجرا کنید.

وقتی Drag & Drop کافی نیست: چرا نودهای آماده n8n شما را محدود می‌کنند؟

در پروژه‌های واقعی، بارها با این سناریو مواجه شده‌ایم: فرض کنید در حال ساخت یک ورک‌فلو برای همگام‌سازی اطلاعات مشتریان از یک سامانه CRM ایرانی با پلتفرم حسابداری خود هستید. پاسخ API از CRM، یک آبجکت JSON است که در آن، سابقه خرید مشتریان به صورت یک رشته متنی (stringified JSON) در یکی از فیلدها قرار گرفته و تاریخ‌ها با فرمت غیراستاندارد شمسی ارائه شده‌اند.

نودهای استاندارد n8n در این سناریو فلج می‌شوند:

شما به ابزاری نیاز دارید که بتواند رشته را به آبجکت JSON تبدیل کند، در میان آرایه خریدها حلقه بزند، تاریخ‌ها را استانداردسازی کند و در نهایت، یک خروجی تمیز و ساختاریافته تولید کند.

تلاش برای انجام این کار با زنجیره‌ای از ده نود بصری، نه تنها ورک‌فلو را پیچیده و غیرقابل نگهداری می‌کند، بلکه در بسیاری از موارد اساساً غیرممکن است. این بن‌بست، نقطه تولد نیاز به نود Code است.

آناتومی نود Code: آشنایی با محیط کدنویسی شما در n8n

نود Code یک محیط ایزوله مبتنی بر Node.js در اختیار شما قرار می‌دهد. درک ساختار ورودی و خروجی آن برای استفاده موثر، حیاتی است.

*(توضیح تصویری: یک اسکرین‌شات از محیط نود Code که بخش‌های مختلف آن با فلش و متن فارسی مشخص شده‌اند: ۱. پنل کدنویسی، ۲. متغیرهای ورودی گلوبال، ۳. پنل خروجی و دیباگ)*

داده‌ها از نودهای قبلی به صورت یک آرایه از آیتم‌ها به نود Code وارد می‌شوند. این آرایه items نام دارد و متغیر اصلی شماست.

خروجی نود Code
کد شما باید یک آرایه از آبجکت‌ها را بازگرداند (return). هر آبجکت در این آرایه، به یک آیتم خروجی برای نود بعدی تبدیل می‌شود. ساختار استاندارد هر آبجکت خروجی، { json: yourDataObject } است.

مثال پایه‌ای برای شروع: فرض کنید نود قبلی، یک آبجکت ساده { "name": "Arash", "level": "admin" } را ارسال کرده است. کد زیر این داده را دریافت کرده و یک فیلد جدید به آن اضافه می‌کند.

// Data from the previous node is available in the 'items' array.
// $json is a shorthand for items[0].json
// Create a new object based on the input data.

const outputData = {
  ...$json, // Copy all fields from the input
  processed: true,
  timestamp: new Date().toISOString()
};

// The node MUST return an array of objects.
// Each object will become an output item for the next node.
return [{
  json: outputData
}];

این ساختار ساده، سنگ بنای تمام عملیات پیچیده‌ای است که در ادامه بررسی خواهیم کرد.

جادوی جاوااسکریپت: ۳ مثال عملی برای حل مشکلات واقعی

در تجربه ما در کارورا، قدرت واقعی نود Code در حل مشکلات بومی و خاص بازار ایران آشکار می‌شود. در ادامه سه سناریوی واقعی را پیاده‌سازی می‌کنیم.

۱. پاکسازی و فرمت‌دهی داده API یک درگاه پرداخت

فرض کنید از API یک درگاه پرداخت ایرانی استعلام وضعیت یک تراکنش را گرفته‌اید و پاسخ زیر را دریافت می‌کنید. داده‌ها نامرتب، دارای فیلدهای اضافی و با نام‌گذاری غیراستاندارد هستند.

ورودی JSON (از نود HTTP Request):

{
  "status_code": 200,
  "data": {
    "trans_id": "TR-10928B3",
    "amount_rials": 5000000,
    "card_info": {
      "masked_pan": "6037---1111",
      "bank": "Melli"
    },
    // Stringified JSON inside a string
    "customer_details": "{\"name\": \"شرکت کارورا\", \"phone\": \"09120000000\"}",
    "extra_data": null,
    "payment_timestamp": "1403/04/01 15:30:00"
  }
}

هدف: استخراج اطلاعات کلیدی، تغییر نام فیلدها به فرمت camelCase، پارس کردن customer_details و تبدیل مبلغ از ریال به تومان.

ورک‌فلو: Webhook -> HTTP Request (Get Transaction) -> Code -> Google Sheets

⚠️ نکته امنیتی: هنگام استفاده از نود Webhook در محیط پروداکشن، حتماً از بخش تنظیمات نود، گزینه Authentication را روی Basic Auth یا Header Auth تنظیم کرده و یک توکن امن برای آن تعریف کنید تا از دریافت درخواست‌های غیرمجاز جلوگیری شود.

کد داخل نود Code:

// Access the nested data object from the first input item
const rawData = $json.data;

// Parse the stringified JSON for customer details
// Use a try-catch block to handle cases where parsing might fail
let customerInfo = {};

try {
  customerInfo = JSON.parse(rawData.customer_details);
} catch (error) {
  console.log('Could not parse customer_details:', rawData.customer_details);
}

// Create the clean, structured output object
const cleanTransaction = {
  transactionId: rawData.trans_id,
  amountToman: rawData.amount_rials / 10,
  customerName: customerInfo.name || 'N/A', // Provide a default value
  customerPhone: customerInfo.phone || 'N/A',
  maskedCard: rawData.card_info.masked_pan,
  paymentDate: rawData.payment_timestamp
};

// Return the cleaned data as a single output item
return [{
  json: cleanTransaction
}];

نتیجه: نود Google Sheets اکنون یک ردیف تمیز و استاندارد با فیلدهای transactionId, amountToman و… دریافت می‌کند که مستقیماً قابل استفاده است.

۲. اجرای منطق شرطی پیچیده برای مدیریت سفارش‌ها

یک فروشگاه آنلاین می‌خواهد بر اساس وضعیت کاربر و جزئیات سفارش، عملیات متفاوتی انجام دهد. زنجیره‌سازی چند نود IF این ورک‌فلو را به یک اسپاگتی بصری تبدیل می‌کند.

ورودی JSON:

{
  "orderId": "ORD-5541",
  "totalAmount": 2500000, // Toman
  "userType": "VIP", // Can be 'VIP', 'New', 'Regular'
  "couponCode": null
}

هدف:

ورک‌فلو: Webhook (New Order) -> Code -> Router (Based on 'tag')

کد داخل نود Code:

let tag = 'standard-processing';
let notification = 'Process as standard order.';

// Condition 1: VIP high-value order
if (order.userType === 'VIP' && order.totalAmount > 1000000) {
  tag = 'high-priority';
  notification = `High-priority order #${order.orderId} from a VIP customer. Requires immediate attention.`;
}

// Condition 2: New user with welcome coupon
else if (order.userType === 'New' && order.couponCode === 'WELCOME2026') {
  tag = 'welcome-offer';
  notification = `New user #${order.orderId} used the welcome offer.`;
}

// Prepare the output object
const output = {
  ...order, // Pass through original order data
  processingTag: tag,
  internalNotification: notification
};

return [{
  json: output
}];

نتیجه: نود Router پس از این کد، می‌تواند به سادگی بر اساس مقدار فیلد processingTag جریان کار را به سه شاخه کاملاً مجزا هدایت کند. تمام منطق پیچیده در یک نود کپسوله شده است.

۳. تولید گزارش متنی داینامیک برای ارسال به تلگرام

شما می‌خواهید روزانه یک خلاصه عملکرد برای تیم فروش در تلگرام ارسال کنید. داده‌ها از دو منبع مختلف می‌آیند: یک API فروش و یک Google Sheet حاوی اهداف فروش.

ورودی (پس از نود Merge): دو آیتم در آرایه items وجود دارد.

هدف: تولید یک پیام متنی خوانا که این داده‌ها را ترکیب و مقایسه کند.

ورک‌فلو: Cron -> HTTP Request (Get Sales) -> Google Sheets (Get Targets) -> Merge -> Code -> Telegram

کد داخل نود Code:

// Access data from the two different input items
const salesData = items[0].json;
const targetData = items[1].json;

// Calculate performance metrics
const salesPercentage = ((salesData.dailySales / targetData.salesTarget) * 100).toFixed(1);
const leadPerformance = salesData.newLeads >= targetData.leadTarget ? '✅' : '⚠️';

// Get current date in Jalali format
const reportDate = new Date().toLocaleDateString('fa-IR');

// Generate the dynamic report text using template literals
const reportMessage = `
گزارش عملکرد روزانه – ${reportDate}
فروش امروز: ${salesData.dailySales.toLocaleString('fa-IR')} تومان
هدف فروش: ${targetData.salesTarget.toLocaleString('fa-IR')} تومان
درصد تحقق هدف: ${salesPercentage}%
سرنخ‌های جدید: ${salesData.newLeads} عدد
عملکرد جذب سرنخ: ${leadPerformance}
#گزارش_روزانه #فروش
`;

// The Telegram node needs the message in a specific field
return [{
  json: {
    text: reportMessage,
    chatId: '-100123456789' // Your Telegram Chat ID
  }
}];

گزارش عملکرد روزانه – ${reportDate}

گزارش_روزانه فروش

// The Telegram node needs the message in a specific field, e.g., 'text'
return [{
  json: {
    text: reportMessage,
    chatId: '-100123456789' // Your Telegram Chat ID
  }
}];

تکنیک‌های پیشرفته: کار با حلقه‌ها و مدیریت خطا در نود Code

وقتی با مجموعه‌ای از داده‌ها (مثلاً لیست محصولات در یک فاکتور) سر و کار دارید، حلقه‌ها ابزار اصلی شما خواهند بود. همچنین، تضمین پایداری ورک‌فلو در مواجهه با داده‌های غیرمنتظره، نیازمند مدیریت خطا است.

پردازش آرایه‌ها با حلقه‌ها

فرض کنید ورودی شما یک سفارش شامل آرایه‌ای از محصولات است و می‌خواهید مجموع مبلغ سفارش را محاسبه کنید.

ورودی JSON:

{
  "orderId": "ORD-5542",
  "items": [
    { "product": "A", "price": 50000, "quantity": 2 },
    { "product": "B", "price": 120000, "quantity": 1 },
    { "product": "C", "price": 75000, "quantity": 3 }
  ]
}

کد برای محاسبه مجموع:

const order = $json;

// A more functional approach using Array.reduce()
// This is often preferred for its conciseness and readability
const totalAmountWithReduce = order.items.reduce((accumulator, currentItem) => {
  return accumulator + (currentItem.price * currentItem.quantity);
}, 0); // 0 is the initial value of the accumulator

const output = {
  ...order,
  calculatedTotal: totalAmountWithReduce
};

return [{
  json: output
}];

این کد نشان می‌دهد چگونه می‌توان بر روی آرایه‌ای از آیتم‌های داخلی یک ورودی تکرار کرده و یک مقدار تجمعی را محاسبه نمود.

مدیریت خطا با try...catch

یک ورک‌فلو قدرتمند، ورک‌فلویی است که در مقابل خطاهای غیرمنتظره مقاوم باشد. اگر کد شما تلاش کند به یک پراپرتی که وجود ندارد دسترسی پیدا کند (مثلاً user.address.city وقتی address تعریف نشده)، کل ورک‌فلو متوقف می‌شود. بلوک try...catch از این فاجعه جلوگیری می‌کند.

سناریو: پردازش داده کاربری که ممکن است پروفایل کاملی نداشته باشد.

const user = $json.user;
let shippingCity = 'Not Provided';

try {
  // This line will throw an error if 'address' is undefined
  shippingCity = user.address.city;
} catch (error) {
  // This code executes only if an error occurs in the try block
  console.log(Error accessing city for user ${user.id}. Defaulting.);
  // The 'shippingCity' variable remains 'Not Provided'
}

const output = {
  userId: user.id,
  targetCity: shippingCity,
};

return [{
  json: output
}];

با این الگو، حتی اگر داده ورودی ناقص باشد، ورک‌فلو متوقف نشده و با یک مقدار پیش‌فرض به کار خود ادامه می‌دهد.

بهترین شیوه‌ها (Best Practices) برای کدنویسی در n8n

نتیجه‌گیری: از یک کاربر ساده به یک معمار اتوماسیون تبدیل شوید

نود Code در n8n صرفاً یک ابزار نیست؛ یک فلسفه است. فلسفه‌ای که می‌گوید هیچ محدودیتی نباید مانع خلاقیت یک توسعه‌دهنده برای حل یک مشکل واقعی شود.

این نود، مرز بین یک کاربر ابزار که در چارچوب‌ها کار می‌کند و یک معمار اتوماسیون که سیستم‌های منحصربه‌فرد طراحی می‌کند را از بین می‌برد. با تسلط بر جاوااسکریپت در این محیط، شما دیگر به نودهای موجود محدود نیستید؛ شما کنترل کامل بر جریان داده، منطق پردازش و ساختار خروجی را در دست می‌گیرید. این قدرت به شما اجازه می‌دهد تا پیچیده‌ترین چالش‌های کسب‌وکار خود را به فرآیندهای خودکار، هوشمند و مقیاس‌پذیر تبدیل کنید.

سوالات متداول

آیا جاوااسکریپت تنها زبان قابل استفاده در نود Code است؟

بله. محیط اجرایی نود Code بر پایه Node.js است و به طور انحصاری از جاوااسکریپت پشتیبانی می‌کند. شما می‌توانید از سینتکس‌های مدرن ES6+ مانند async/await و destructuring استفاده کنید.

آیا می‌توانم از پکیج‌های npm خارجی (مانند moment-jalaali) استفاده کنم؟

بله، اما نیازمند تنظیمات پیشرفته است. شما باید متغیر محیطی NODE_CODE_ALLOW_EXTERNAL را در سمت سرور n8n خود تنظیم کنید. این کار به شما اجازه می‌دهد تا ماژول‌های npm مورد نیازتان را require کنید.

تفاوت نود Code با نودهای Function و Function Item چیست؟

نودهای Function و Function Item نسخه‌های قدیمی‌تر و محدودتر هستند. نود Code مدرن‌تر و قدرتمندتر است زیرا کل مجموعه آیتم‌های ورودی را به صورت یک آرایه (items) دریافت می‌کند و به شما کنترل کامل بر روی کل بچ داده‌ها را می‌دهد. توصیه ما در کارورا استفاده انحصاری از نود Code است.

چگونه می‌توانم کدم را داخل نود Code دیباگ کنم؟

ساده‌ترین روش استفاده از console.log() است. شما می‌توانید هر متغیری را در کد خود لاگ کنید. هنگام اجرای دستی نود، خروجی console.log در پنل “Console” مرورگر شما (Developer Tools) نمایش داده می‌شود.