کد
Code
اجرای کد JavaScript/Python برای پردازش و محاسبات سفارشی
نمای کلی
نود Code چیست؟
نود Code قدرتمندترین نود n8n است که به شما امکان میدهد کد JavaScript یا Python بنویسید و در ورکفلو اجرا کنید. این نود برای موارد زیر ایدهآل است:
- پردازش پیچیده دادهها
- محاسبات سفارشی و ریاضیاتی
- تبدیل فرمت دادهها (JSON, XML, CSV)
- فیلتر و مرتبسازی پیشرفته
- رمزنگاری و امنیت
- فراخوانی APIهای سفارشی
- هر منطق خاصی که با نودهای استاندارد ممکن نیست
حالتهای اجرا
1. Run Once for All Items
کد یکبار اجرا میشود و به همه آیتمهای ورودی دسترسی دارد. مناسب برای:
- محاسبه مجموع یا میانگین
- گروهبندی دادهها
- مقایسه آیتمها با هم
2. Run Once for Each Item
کد برای هر آیتم جداگانه اجرا میشود. مناسب برای:
- تبدیل هر آیتم
- اعتبارسنجی دادهها
- افزودن فیلد به هر آیتم
دسترسی به دادهها
در JavaScript:
// همه آیتمهای ورودی
const items = $input.all();
// آیتم اول
const firstItem = $input.first();
// آیتم فعلی (در حالت Run for Each)
const currentItem = $input.item;
// داده JSON آیتم
const data = items[0].json;در Python:
# همه آیتمها
items = _input.all()
# آیتم اول
first_item = _input.first()
# داده JSON
data = items[0]['json']احراز هویت
احراز هویت
نود Code نیاز به احراز هویت خاصی ندارد.
دسترسی به Credentials دیگر نودها
اگر نیاز دارید در کد خود به credentials استفاده شده در نودهای دیگر دسترسی داشته باشید:
// دسترسی به متغیرهای محیطی (Environment Variables)
const apiKey = $env.MY_API_KEY;
// استفاده از HTTP Request داخلی
const response = await $http.request({
method: 'GET',
url: 'https://api.example.com/data',
headers: {
'Authorization': 'Bearer ' + apiKey
}
});نکات امنیتی
⚠️ هرگز اطلاعات حساس (API Key, Password) را مستقیم در کد ننویسید.
✅ از Environment Variables یا Credentials استفاده کنید.
عملیاتهای موجود
runOnceForAllItems
کد یکبار اجرا میشود و به همه آیتمها دسترسی دارد
runOnceForEachItem
کد برای هر آیتم جداگانه اجرا میشود
کاربردهای متداول
کاربردهای رایج
۱. تبدیل ساختار داده (Data Transformation)
تغییر ساختار JSON برای سازگاری با API یا سرویس مقصد. مثلاً تبدیل flat object به nested، یا برعکس.
// تبدیل آرایه flat به ساختار درختی
const items = $input.all();
const flat = items.map(i => i.json);
const tree = flat.reduce((acc, item) => {
const cat = item.category;
if (!acc[cat]) acc[cat] = { name: cat, items: [] };
acc[cat].items.push(item);
return acc;
}, {});
return Object.values(tree).map(g => ({ json: g }));۲. محاسبات مالی و حسابداری
محاسبه جمع فاکتور، مالیات بر ارزش افزوده، تخفیف، و تبدیل ارز.
const items = $input.all();
const orders = items.map(i => i.json);
const subtotal = orders.reduce((sum, o) => sum + o.amount, 0);
const tax = Math.round(subtotal * 0.09); // ۹% مالیات
const discount = subtotal > 1000000 ? Math.round(subtotal * 0.1) : 0;
const total = subtotal + tax - discount;
return [{ json: { subtotal, tax, discount, total,
formatted: total.toLocaleString('fa-IR') + ' تومان' } }];۳. پردازش متن و Regex
استخراج اطلاعات از متن با Regular Expressions: شماره موبایل، ایمیل، کد ملی، URL.
const text = $input.first().json.message;
const phones = text.match(/09[0-9]{9}/g) || [];
const emails = text.match(/[\w.-]+@[\w.-]+\.[a-z]{2,}/gi) || [];
const urls = text.match(/https?:\/\/[^\s]+/g) || [];
return [{ json: { phones, emails, urls } }];۴. اعتبارسنجی دادهها (Validation)
بررسی صحت دادههای ورودی قبل از ذخیره در دیتابیس یا ارسال به API.
const item = $input.first().json;
const errors = [];
if (!item.email?.match(/^[^\s@]+@[^\s@]+\.[^\s@]+$/)) errors.push('ایمیل نامعتبر');
if (!item.phone?.match(/^09\d{9}$/)) errors.push('موبایل نامعتبر');
if (!item.name || item.name.length < 2) errors.push('نام کوتاه است');
return [{ json: { isValid: errors.length === 0, errors, data: item } }];۵. تبدیل تاریخ میلادی/شمسی
کار با تاریخهای فارسی: تبدیل میلادی به شمسی، محاسبه اختلاف روزها، فرمتبندی.
const date = new Date($input.first().json.date);
const persian = date.toLocaleDateString('fa-IR', {
year: 'numeric', month: 'long', day: 'numeric',
weekday: 'long'
});
return [{ json: { original: date.toISOString(), persian } }];۶. Deduplication (حذف تکراریها)
حذف آیتمهای تکراری بر اساس یک فیلد خاص (مثل email یا phone).
const items = $input.all();
const seen = new Set();
const unique = items.filter(item => {
const key = item.json.email;
if (seen.has(key)) return false;
seen.add(key);
return true;
});
return unique;۷. Pagination Handler
مدیریت pagination برای APIهایی که دادهها را صفحهای برمیگردانند.
const allData = [];
let page = 1;
let hasMore = true;
while (hasMore) {
const res = await $http.request({
url: 'https://api.example.com/data?page=' + page + '&limit=100'
});
allData.push(...res.body.data);
hasMore = res.body.data.length === 100;
page++;
}
return allData.map(d => ({ json: d }));۸. ساخت پیام Telegram/Slack
فرمتبندی دادهها به صورت پیام خوانا با Markdown یا HTML.
const order = $input.first().json;
const msg = `🛒 *سفارش جدید #${order.id}*
👤 ${order.customer}
💰 ${order.total.toLocaleString()} تومان
📦 ${order.items.length} محصول
📅 ${new Date().toLocaleDateString('fa-IR')}`;
return [{ json: { message: msg } }];۹. تولید CSV/Excel
تبدیل دادههای JSON به فرمت CSV برای export و گزارشگیری.
۱۰. Merge/Join دادهها
ترکیب دادهها از چندین منبع بر اساس کلید مشترک (مشابه SQL JOIN).
const orders = $('Node1').all().map(i => i.json);
const customers = $('Node2').all().map(i => i.json);
const merged = orders.map(order => {
const customer = customers.find(c => c.id === order.customerId);
return { json: { ...order, customer } };
});
return merged;نکات حرفهای
نکات حرفهای
۱. همیشه آرایه با ساختار صحیح برگردانید
// صحیح: آرایهای از آبجکتها با کلید json
return items.map(item => ({ json: { ...item.json, newField: 'value' } }));۲. از Optional Chaining و Nullish Coalescing استفاده کنید
const value = data?.nested?.deep?.field ?? 'پیشفرض';
const count = data?.items?.length ?? 0;۳. Debug با console.log
خروجی console.log در Execution Log نمایش داده میشود:
console.log('Items count:', items.length);
console.log('Data:', JSON.stringify(data, null, 2));۴. دسترسی به دادههای نودهای دیگر
// داده نود خاص (با نام)
const prevData = $('نام نود').all();
const firstItem = $('نام نود').first();
// آخرین نود
const lastData = $input.all();۵. استفاده از Environment Variables
اطلاعات حساس را در Environment Variables ذخیره کنید:
const apiKey = $env.MY_API_KEY;
const baseUrl = $env.API_BASE_URL;۶. مدیریت خطا با try/catch
try {
const result = await someOperation();
return [{ json: { success: true, data: result } }];
} catch (error) {
return [{ json: { success: false, error: error.message } }];
}۷. ماژولهای مجاز Node.js
این ماژولها در Code node قابل استفادهاند: crypto, url, querystring, path, Buffer, Date, Math, JSON, RegExp.
۸. Run Once for All vs Run for Each
- All Items: وقتی نیاز به مقایسه یا aggregation بین آیتمها دارید
- Each Item: وقتی هر آیتم مستقل پردازش میشود
۹. Performance Tips
- از
MapوSetبرای lookup سریع استفاده کنید - از
Array.reduceبجای حلقههای تو در تو - دادههای بزرگ را stream کنید
- عملیات async را parallel اجرا کنید
۱۰. Binary Data
برای کار با فایلها (تصویر، PDF، CSV):
// خواندن binary
const binaryData = items[0].binary.data;
const buffer = Buffer.from(binaryData.data, 'base64');
// ایجاد binary
return [{ json: {}, binary: {
data: { data: Buffer.from('content').toString('base64'),
mimeType: 'text/csv', fileName: 'export.csv' }
}}];۱۱. دسترسی به Workflow Info
const workflowId = $workflow.id;
const workflowName = $workflow.name;
const executionId = $execution.id;
const isTestRun = $execution.mode === 'manual';۱۲. Timestamp و تاریخ فارسی
const now = new Date();
const persian = now.toLocaleDateString('fa-IR');
const timestamp = Math.floor(now.getTime() / 1000);۱۳. کار با Python
Python در Code node با sandbox اجرا میشود. از _input (با underscore) بجای $input استفاده کنید.
۱۴. Reusable Functions
توابع helper را در بالای کد تعریف کنید و در جاهای مختلف استفاده کنید:
function formatPrice(amount) {
return amount.toLocaleString('fa-IR') + ' تومان';
}۱۵. Conditional Output
برای ارسال داده به مسیرهای مختلف:
// فقط آیتمهای معتبر برگردانید
const valid = items.filter(i => i.json.isValid);
if (valid.length === 0) return []; // خروجی خالی = توقف مسیر
return valid;رفع مشکلات
رفع مشکلات رایج
❌ خطای SyntaxError
علت: اشکال در نوشتار کد (پرانتز، براکت، نقطهویرگول)
راهحل
- کد را در VS Code یا editor دیگر بررسی کنید
- از linter استفاده کنید
- مطمئن شوید همه پرانتزها بسته شدهاند
❌ خطای "Cannot read property of undefined"
علت: دسترسی به فیلدی که وجود ندارد
راهحل
// بد ❌
const name = item.json.user.name;
// خوب ✅ - Optional Chaining
const name = item.json?.user?.name || 'پیشفرض';❌ خطای Timeout (کد بیش از حد طول میکشد)
علت: حلقههای سنگین یا درخواستهای API زیاد
راهحل
- از حلقههای بهینه استفاده کنید
$http.requestرا بجایfetchاستفاده کنید- دادههای بزرگ را batch کنید
- از async parallel بجای sequential استفاده کنید
❌ خطای "Module not found"
علت: ماژول درخواستی در n8n وجود ندارد
راهحل
- فقط ماژولهای built-in Node.js مجاز هستند:
crypto,url,querystring,path,Buffer - ماژولهای npm خارجی مستقیماً قابل import نیستند
- از
$http.requestبجایaxiosیاnode-fetchاستفاده کنید - در n8n self-hosted، admin میتواند ماژولهای مجاز را تنظیم کند
❌ خروجی خالی (Empty Output)
علت: return نادرست
راهحل
- حتماً آرایهای از آبجکتها با کلید
jsonبرگردانید:
// صحیح ✅
return [{ json: { result: 'مقدار' } }];
// اشتباه ❌ - آرایه نیست
return { json: { result: 'مقدار' } };
// اشتباه ❌ - کلید json ندارد
return [{ result: 'مقدار' }];❌ خطای "items is not iterable"
علت: خروجی نود قبلی خالی است
راهحل
const items = $input.all();
if (!items || items.length === 0) {
return [{ json: { error: 'دادهای دریافت نشد' } }];
}❌ مشکل Encoding فارسی
علت: مشکل در encode/decode کاراکترهای فارسی
راهحل
- از
encodeURIComponent()برای URL استفاده کنید - JSON.stringify به صورت پیشفرض Unicode را handle میکند
- برای Binary data از
Buffer.from(text, 'utf-8')استفاده کنید
❌ خطای "Execution data is too large"
علت: حجم دادههای خروجی بیش از حد مجاز
راهحل
- فقط فیلدهای مورد نیاز را برگردانید
- دادههای binary بزرگ را جداگانه handle کنید
- از
delete item.json.largeFieldبرای حذف فیلدهای غیرضروری استفاده کنید
