“`html

n8n برای توسعه‌دهندگان: سفارشی‌سازی و توسعه نودها

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

چرا سفارشی‌سازی و توسعه نودها در n8n مهم است؟

n8n به طور پیش‌فرض با مجموعه گسترده‌ای از نودها برای اتصال به سرویس‌ها و برنامه‌های مختلف ارائه می‌شود. اما در برخی موارد، نیازهای خاص یک کسب‌وکار یا پروژه ممکن است فراتر از قابلیت‌های این نودهای از پیش تعریف شده باشد. در اینجاست که سفارشی‌سازی و توسعه نودها اهمیت پیدا می‌کند. این امکان به توسعه‌دهندگان می‌دهد تا:

• اتصال به سرویس‌های اختصاصی: اگر یک سرویس یا API اختصاصی وجود داشته باشد که n8n به طور پیش‌فرض از آن پشتیبانی نمی‌کند، می‌توان یک نود سفارشی برای اتصال به آن ایجاد کرد.
• پیاده‌سازی منطق تجاری پیچیده: نودهای سفارشی امکان پیاده‌سازی منطق تجاری پیچیده را فراهم می‌کنند که ممکن است با استفاده از نودهای موجود امکان‌پذیر نباشد.
• بهینه‌سازی گردش کار: با توسعه نودهای سفارشی، می‌توان گردش کار را برای نیازهای خاص بهینه کرد و عملکرد و کارایی را بهبود بخشید.
• اشتراک‌گذاری نودها با جامعه: نودهای سفارشی می‌توانند با جامعه n8n به اشتراک گذاشته شوند، که به دیگران امکان می‌دهد از آن‌ها در پروژه‌های خود استفاده کنند.

پیش‌نیازها برای توسعه نودهای سفارشی

قبل از شروع به توسعه نودهای سفارشی در n8n، اطمینان حاصل کنید که پیش‌نیازهای زیر را دارید:

• دانش JavaScript یا TypeScript: n8n مبتنی بر Node.js است، بنابراین دانش JavaScript یا TypeScript برای توسعه نودها ضروری است.
• آشنایی با Node.js و npm: درک مفاهیم Node.js و نحوه استفاده از npm (Node Package Manager) برای مدیریت وابستگی‌ها ضروری است.
• نصب n8n: یک نسخه از n8n باید نصب و راه‌اندازی شده باشد. می‌توانید n8n را به صورت محلی، روی یک سرور ابری یا با استفاده از Docker نصب کنید.
• درک معماری n8n: آشنایی با معماری n8n، به ویژه نحوه عملکرد نودها و گردش کار، برای توسعه نودهای مؤثر ضروری است.
• دسترسی به API سرویس مورد نظر: برای توسعه نودی که با یک سرویس خاص تعامل دارد، باید به API آن سرویس دسترسی داشته باشید و مستندات آن را مطالعه کنید.

مراحل توسعه یک نود سفارشی

توسعه یک نود سفارشی در n8n شامل مراحل زیر است:

1. ایجاد ساختار پروژه

اولین قدم ایجاد یک ساختار پروژه برای نود سفارشی است. این ساختار معمولاً شامل فایل‌های زیر است:

• package.json: این فایل شامل اطلاعات مربوط به نود سفارشی، مانند نام، نسخه، وابستگی‌ها و اسکریپت‌های مورد نیاز است.
• src/nodes/[NodeName]/[NodeName].node.ts: این فایل شامل کد اصلی نود سفارشی است.
• src/nodes/[NodeName]/[NodeName].description.ts: این فایل شامل توضیحات نود سفارشی، پارامترها و خروجی‌ها است.
• tsconfig.json: این فایل تنظیمات TypeScript را مشخص می‌کند.

می‌توانید از یک قالب آماده برای ایجاد ساختار پروژه استفاده کنید یا آن را به صورت دستی ایجاد کنید. برای مثال، می‌توانید از دستور زیر برای ایجاد یک پروژه npm جدید استفاده کنید:

npm init -y

سپس، فایل‌های لازم را در ساختار پروژه ایجاد کنید.

2. تعریف توضیحات نود

فایل `[NodeName].description.ts` شامل توضیحات نود سفارشی است. این توضیحات شامل اطلاعاتی مانند نام نود، دسته‌بندی، آیکون، پارامترها و خروجی‌ها است. مثال زیر یک نمونه از فایل توضیحات نود را نشان می‌دهد:

import { INodeType, INodeTypeDescription } from 'n8n-workflow';

 export class MyCustomNode implements INodeType {
  description: INodeTypeDescription = {
   displayName: 'My Custom Node',
   name: 'myCustomNode',
   group: ['transform'],
   version: 1,
   description: 'A custom node example',
   defaults: {
    name: 'My Custom Node',
   },
   inputs: ['main'],
   outputs: ['main'],
   properties: [
    {
     displayName: 'My Parameter',
     name: 'myParameter',
     type: 'string',
     default: '',
     description: 'Enter a value for my parameter',
    },
   ],
  };
  async execute() {
   // Your code here
  }
 }
 

در این مثال، `displayName` نام نمایشی نود در رابط کاربری n8n را مشخص می‌کند. `name` نام داخلی نود است که در گردش کار استفاده می‌شود. `group` دسته‌بندی نود را مشخص می‌کند. `inputs` و `outputs` تعداد ورودی‌ها و خروجی‌های نود را مشخص می‌کنند. `properties` لیست پارامترهای نود را تعریف می‌کند.

3. پیاده‌سازی منطق نود

فایل `[NodeName].node.ts` شامل کد اصلی نود سفارشی است. این کد منطق نود را پیاده‌سازی می‌کند و عملیات مورد نظر را انجام می‌دهد. مثال زیر یک نمونه از فایل کد نود را نشان می‌دهد:

import { IExecuteFunctions } from 'n8n-workflow';
 import { INodeType, INodeTypeDescription } from 'n8n-workflow';

 export class MyCustomNode implements INodeType {
  description: INodeTypeDescription = {
   displayName: 'My Custom Node',
   name: 'myCustomNode',
   group: ['transform'],
   version: 1,
   description: 'A custom node example',
   defaults: {
    name: 'My Custom Node',
   },
   inputs: ['main'],
   outputs: ['main'],
   properties: [
    {
     displayName: 'My Parameter',
     name: 'myParameter',
     type: 'string',
     default: '',
     description: 'Enter a value for my parameter',
    },
   ],
  };

  async execute(this: IExecuteFunctions) {
   const items = this.getInputData();
   const myParameter = this.getNodeParameter('myParameter', 0) as string;

   const result = items.map(item => ({
    json: {
     ...item.json,
     myResult: `Value: ${myParameter}`,
    },
   }));

   return [result];
  }
 }
 

تابع `execute` اصلی‌ترین بخش نود است. این تابع داده‌های ورودی را دریافت می‌کند، منطق نود را اجرا می‌کند و داده‌های خروجی را تولید می‌کند. `this.getInputData()` برای دریافت داده‌های ورودی استفاده می‌شود. `this.getNodeParameter()` برای دریافت مقادیر پارامترهای نود استفاده می‌شود. در این مثال، نود یک پارامتر به نام `myParameter` دارد که مقدار آن از طریق رابط کاربری n8n دریافت می‌شود. سپس، نود یک فیلد جدید به نام `myResult` به هر آیتم ورودی اضافه می‌کند و مقدار آن را بر اساس مقدار پارامتر `myParameter` تعیین می‌کند.

4. کامپایل و بسته‌بندی نود

پس از پیاده‌سازی منطق نود، باید آن را کامپایل و بسته‌بندی کنید. برای این کار، می‌توانید از ابزارهای ساخت مانند Webpack یا Rollup استفاده کنید. ابتدا، وابستگی‌های لازم را نصب کنید:

npm install -D typescript webpack webpack-cli ts-loader

سپس، یک فایل پیکربندی Webpack به نام `webpack.config.js` ایجاد کنید:

const path = require('path');

 module.exports = {
  entry: './src/nodes/MyCustomNode/MyCustomNode.node.ts',
  devtool: 'inline-source-map',
  module: {
   rules: [
    {
     test: /\.tsx?$/,
     use: 'ts-loader',
     exclude: /node_modules/,
    },
   ],
  },
  resolve: {
   extensions: ['.ts', '.js'],
  },
  output: {
   filename: 'MyCustomNode.node.js',
   path: path.resolve(__dirname, 'dist'),
   libraryTarget: 'commonjs',
  },
  externals: {
   'n8n-workflow': 'n8n-workflow',
  },
 };
 

این فایل پیکربندی مشخص می‌کند که فایل `MyCustomNode.node.ts` به عنوان ورودی استفاده شود، از `ts-loader` برای کامپایل TypeScript استفاده شود و فایل خروجی به نام `MyCustomNode.node.js` در پوشه `dist` ذخیره شود. همچنین، `n8n-workflow` به عنوان یک وابستگی خارجی مشخص شده است، به این معنی که در فایل خروجی گنجانده نمی‌شود و در زمان اجرا از محیط n8n بارگیری می‌شود.

در نهایت، دستور زیر را برای کامپایل و بسته‌بندی نود اجرا کنید:

npx webpack

این دستور فایل `MyCustomNode.node.js` را در پوشه `dist` ایجاد می‌کند.

5. نصب و فعال‌سازی نود در n8n

برای نصب نود سفارشی در n8n، باید آن را در پوشه `~/.n8n/custom/nodes` قرار دهید. اگر این پوشه وجود ندارد، آن را ایجاد کنید. سپس، فایل `MyCustomNode.node.js` و فایل `MyCustomNode.description.js` را در این پوشه قرار دهید. توجه داشته باشید که نام فایل‌ها باید دقیقاً با نام کلاس نود مطابقت داشته باشد.

پس از قرار دادن فایل‌ها در پوشه `~/.n8n/custom/nodes`، n8n را مجدداً راه‌اندازی کنید. نود سفارشی باید در لیست نودها در رابط کاربری n8n ظاهر شود. می‌توانید از آن در گردش کار خود استفاده کنید.

تست و اشکال‌زدایی نودهای سفارشی

تست و اشکال‌زدایی نودهای سفارشی بخش مهمی از فرآیند توسعه است. برای اطمینان از اینکه نود به درستی کار می‌کند، باید آن را به طور کامل تست کنید. می‌توانید از روش‌های مختلفی برای تست نودهای سفارشی استفاده کنید:

• تست واحد: تست واحد شامل تست جداگانه هر تابع یا ماژول در نود است. این نوع تست به شما کمک می‌کند تا مشکلات را در سطح کد شناسایی کنید.
• تست ادغام: تست ادغام شامل تست تعامل بین نود و سایر سرویس‌ها یا برنامه‌ها است. این نوع تست به شما کمک می‌کند تا مشکلات مربوط به اتصال به سرویس‌های خارجی را شناسایی کنید.
• تست دستی: تست دستی شامل اجرای نود در یک گردش کار واقعی و بررسی نتایج است. این نوع تست به شما کمک می‌کند تا مشکلات مربوط به عملکرد نود در یک محیط واقعی را شناسایی کنید.

برای اشکال‌زدایی نودهای سفارشی، می‌توانید از ابزارهای اشکال‌زدایی مختلف استفاده کنید، مانند:

• console.log: استفاده از `console.log` برای چاپ مقادیر متغیرها و بررسی جریان کد.
• debugger: استفاده از دستور `debugger` برای توقف اجرای کد در یک نقطه خاص و بررسی وضعیت برنامه.
• اشکال‌زدایی در مرورگر: استفاده از ابزارهای اشکال‌زدایی مرورگر برای بررسی کد و مقادیر متغیرها در زمان اجرا.

همچنین، می‌توانید از ابزارهای تست خودکار مانند Jest یا Mocha برای نوشتن تست‌های واحد و ادغام استفاده کنید.

بهترین شیوه‌ها برای توسعه نودهای سفارشی

برای توسعه نودهای سفارشی کارآمد و قابل نگهداری، رعایت بهترین شیوه‌های زیر توصیه می‌شود:

• نام‌گذاری مناسب: از نام‌های توصیفی و معنی‌دار برای نودها، پارامترها و متغیرها استفاده کنید.
• مستندسازی کامل: نودها را به طور کامل مستند کنید، شامل توضیحات، پارامترها، خروجی‌ها و نمونه‌های استفاده.
• مدیریت خطا: مدیریت خطا را به درستی پیاده‌سازی کنید و پیام‌های خطای معنی‌دار ارائه دهید.
• امنیت: از داده‌های ورودی به درستی اعتبارسنجی کنید و از آسیب‌پذیری‌های امنیتی جلوگیری کنید.
• بهینه‌سازی عملکرد: کد را برای عملکرد بهینه بنویسید و از مصرف بیش از حد منابع جلوگیری کنید.
• استفاده از TypeScript: استفاده از TypeScript به جای JavaScript به بهبود خوانایی، نگهداری و قابلیت اطمینان کد کمک می‌کند.
• استفاده از کتابخانه‌های کمکی: از کتابخانه‌های کمکی برای انجام وظایف رایج مانند ارسال درخواست‌های HTTP، تجزیه JSON و اعتبارسنجی داده‌ها استفاده کنید.
• بازبینی کد: کد را قبل از انتشار توسط دیگران بازبینی کنید تا از کیفیت و صحت آن اطمینان حاصل کنید.

نمونه‌های کاربردی از توسعه نودهای سفارشی

در اینجا چند نمونه از کاربردهای توسعه نودهای سفارشی در n8n آورده شده است:

• اتصال به یک CRM اختصاصی: یک نود سفارشی می‌تواند برای اتصال به یک سیستم مدیریت ارتباط با مشتری (CRM) اختصاصی ایجاد شود که n8n به طور پیش‌فرض از آن پشتیبانی نمی‌کند.
• ادغام با یک سیستم پردازش پرداخت: یک نود سفارشی می‌تواند برای ادغام با یک سیستم پردازش پرداخت ایجاد شود و پرداخت‌ها را به طور خودکار پردازش کند.
• اتصال به یک سیستم مدیریت موجودی: یک نود سفارشی می‌تواند برای اتصال به یک سیستم مدیریت موجودی ایجاد شود و موجودی را به طور خودکار به‌روزرسانی کند.
• انجام تجزیه و تحلیل داده‌های پیشرفته: یک نود سفارشی می‌تواند برای انجام تجزیه و تحلیل داده‌های پیشرفته با استفاده از الگوریتم‌های خاص ایجاد شود.
• ارسال پیامک از طریق یک سرویس SMS اختصاصی: یک نود سفارشی می‌تواند برای ارسال پیامک از طریق یک سرویس SMS اختصاصی ایجاد شود.

منابع و ابزارهای مفید

در اینجا چند منبع و ابزار مفید برای توسعه نودهای سفارشی در n8n آورده شده است:

• مستندات رسمی n8n: مستندات رسمی n8n شامل اطلاعات کاملی در مورد توسعه نودهای سفارشی است.
• مخزن GitHub n8n: مخزن GitHub n8n شامل کد منبع n8n و نمونه‌های نود سفارشی است.
• انجمن n8n: انجمن n8n یک منبع عالی برای دریافت کمک و پاسخ به سوالات مربوط به توسعه نودهای سفارشی است.
• n8n CLI: ابزار خط فرمان n8n (CLI) برای مدیریت n8n و توسعه نودهای سفارشی استفاده می‌شود.
• TypeScript: TypeScript یک زبان برنامه‌نویسی است که بر اساس JavaScript ساخته شده و امکانات بیشتری را برای توسعه برنامه‌های بزرگ فراهم می‌کند.
• Webpack: Webpack یک ابزار بسته‌بندی ماژول است که برای بسته‌بندی کد JavaScript و دارایی‌های دیگر استفاده می‌شود.
• Jest: Jest یک چارچوب تست JavaScript است که برای نوشتن تست‌های واحد و ادغام استفاده می‌شود.

نتیجه‌گیری

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

“`