هوش‌تکمیلی TypeScript در نودهای کد n8n با JSDoc

افزایش نودهای کد با هوش‌تکمیلی TypeScript با استفاده از JSDoc

این راهنما نحوه ادغام هوش‌تکمیلی (Intellisense) به سبک TypeScript را در نودهای کد n8n با استفاده از حاشیه‌نویسی‌های JSDoc نشان می‌دهد. این قابلیت با ارائه تکمیل خودکار هوشمند و راهنمایی نوع داده برای ساختارهای داده حیاتی n8n مانند Workflow و Node، تجربه توسعه‌دهنده را به طور قابل توجهی بهبود می‌بخشد.

این گردش‌کار را در Axeto.ai کاوش کنید: https://axeto.ai/n8n

نمای کلی گردش‌کار

این گردش‌کار برای نمایش قابلیت‌های هوش‌تکمیلی در یک نود کد سازماندهی شده است. این گردش‌کار از مراحل منطقی زیر عبور می‌کند:

1. محرک (Trigger): گردش‌کار را از طریق ارسال فرم آغاز می‌کند.

2. بازیابی داده: تعریف JSON گردش‌کار فعلی را با استفاده از API n8n واکشی می‌کند.

3. نمایش هوش‌تکمیلی: داده‌های گردش‌کار را در یک نود کد پردازش می‌کند که با تعاریف typedef JSDoc برای اشیاء Workflow و Node بهبود یافته است.

4. تجسم نتایج: اطلاعات پردازش شده را در قالبی کاربرپسند نمایش می‌دهد.

5. راهنمایی متنی: از یادداشت‌های چسبان (Sticky Notes) برای ارائه توضیحات و دستورالعمل‌ها در سراسر بوم گردش‌کار استفاده می‌کند.

تحلیل دقیق نودها

۱. محرک: ارسال فرم

• نوع نود: formTrigger
• هدف: به عنوان نقطه ورود عمل می‌کند و گردش‌کار را پس از دریافت ارسال فرم فعال می‌کند.
• پیکربندی: برای گوش دادن به ارسال فرمی با عنوان "Test Code Node" پیکربندی شده است. یک URL وب‌هوک برای دریافت درخواست‌های HTTP POST تولید می‌شود.
• ورودی‌ها: ندارد (زیرا یک نود محرک است).
• خروجی‌ها: به نود "Get This Workflow" متصل می‌شود.
• نسخه: ۲.۲

۲. بازیابی داده: Get This Workflow

• نوع نود: n8n (به طور خاص، یک نود API n8n)
• هدف: تعریف JSON گردش‌کار در حال اجرا را بازیابی می‌کند.
• پیکربندی:

* عملیات (Operation): get

* شناسه گردش‌کار (Workflow ID): با استفاده از عبارت ={{ $workflow.id }} برای ارجاع پویا به گردش‌کار فعلی تنظیم شده است.

• اعتبارنامه‌ها (Credentials): برای احراز هویت به یک اعتبارنامه API n8n معتبر (مانند "n8n unio API v1") نیاز دارد.
• ورودی‌ها: سیگنال محرک را از نود "On form submission" دریافت می‌کند.
• خروجی‌ها: JSON گردش‌کار بازیابی شده را به نود "Code With Intellisense" ارسال می‌کند.
• نسخه: ۱

۳. نمایش هوش‌تکمیلی: Code With Intellisense

• نوع نود: code (جاوا اسکریپت)
• هدف: این نود هسته اصلی نمایش است. از نظرات JSDoc برای تعریف typedef برای اشیاء Workflow و Node استفاده می‌کند. با تبدیل JSON ورودی به این انواع تعریف شده با استفاده از @type، ویرایشگر n8n هوش‌تکمیلی شبیه TypeScript (تکمیل خودکار کد، بررسی نوع) را هنگام نوشتن کد شما ارائه می‌دهد.
• پیکربندی:

* شامل typedef های JSDoc درون خطی برای Node و Workflow است.

از تبدیل درون خطی استفاده می‌کند: const wf = / @type {Workflow} / ($input.first().json);

* یک رشته HTML ایجاد می‌کند که خلاصه‌ای از ویژگی‌های گردش‌کار و جزئیات نود را ارائه می‌دهد.

• عبارات کلیدی:

* typedef های JSDoc برای Node و Workflow.

* تبدیل درون خطی با @type.

• ورودی‌ها: JSON گردش‌کار را از نود "Get This Workflow" دریافت می‌کند.
• خروجی‌ها: رشته قالب‌بندی شده HTML تولید شده را به نود "Display Results" ارسال می‌کند.
• نسخه: ۲

نمونه قطعه کد:

// تعریف typedef های JSDoc برای فعال کردن هوش‌تکمیلی برای Workflow و Node

/**
 * @typedef {Object} Node
 * @property {string} type
 * @property {number} typeVersion
 * @property {number} id
 * @property {string} name
 */

/**
 * @typedef {Object} Workflow
 * @property {string} name
 * @property {number} id
 * @property {boolean} isArchived
 * @property {Array<Node>} nodes
 */

// تبدیل JSON ورودی به نوع Workflow برای هوش‌تکمیلی
const wf = /** @type {Workflow} */ ($input.first().json);

let output = "<p>Example:</p>";
output += `<p>Workflow.id: ${wf.id}</p>`;
output += `<p>Workflow.name: ${wf.name}</p>`;
output += `<p>Workflow.isArchived: ${wf.isArchived}</p>`;

for (let i = 0; i < wf.nodes.length; i++) {
  const node = wf.nodes[i];
  output += `<p>Workflow.nodes[${i}]: ${node.name} (Type: ${node.type})</p>`;
}

return [{ json: { result: output } }];

۴. تجسم نتایج: Display Results

• نوع نود: form
• هدف: خروجی HTML تولید شده توسط نود کد را رندر می‌کند و نمایشی بصری از داده‌های پردازش شده ارائه می‌دهد.
• پیکربندی: حاوی یک فیلد فرم واحد است که برای نمایش محتوای HTML پیکربندی شده است. محتوا با استفاده از عبارت {{ $json.result }} پر می‌شود.
• ورودی‌ها: رشته HTML را از نود "Code With Intellisense" دریافت می‌کند.
• خروجی‌ها: ندارد (این یک نود پایانی است).
• نسخه: ۱

۵. راهنمایی متنی: Sticky Notes

• نوع نود: stickyNote
• هدف: این نودها بر روی بوم گردش‌کار قرار می‌گیرند تا توضیحات و راهنمایی ارائه دهند.
• نمونه محتوا:

* راه‌اندازی: "فقط این گردش‌کار را دریافت کنید تا بتوانیم کار نود کد را نشان دهیم."

* مثال هوش‌تکمیلی: "نود کد را باز کنید و ببینید چگونه به Workflow و Node راهنمایی هوش‌تکمیلی داده‌ایم."

* توضیح خروجی: "چاپ نتایج -- استفاده نمایشی از HTML در فرم‌ها."

* سطح بالا: "این مثال نحوه دریافت هوش‌تکمیلی برای کلاس‌های n8n را نشان می‌دهد. هنگام اشکال‌زدایی نودهای کد پیچیده عالی است."

جدول خلاصه

بازتولید گردش‌کار

1. افزودن محرک: یک نود Form Trigger ایجاد کنید. Form Title را روی "Test Code Node" تنظیم کنید.

2. افزودن بازیابی داده: یک نود n8n اضافه کنید. Operation را روی get تنظیم کنید. برای Workflow ID، از عبارت ={{ $workflow.id }} استفاده کنید. یک اعتبارنامه API n8n معتبر پیکربندی کنید.

3. افزودن نود کد: یک نود Code (جاوا اسکریپت) اضافه کنید. قطعه کد مثال ارائه شده را در ویرایشگر نود جای‌گذاری کنید.

4. افزودن نود نمایش: یک نود Form اضافه کنید. یک فیلد با نوع HTML پیکربندی کنید و مقدار آن را با استفاده از عبارت {{ $json.result }} تنظیم کنید.

5. اتصال نودها: اتصالات زیر را برقرار کنید:

On form submission → Get This Workflow → Code With Intellisense → Display Results

6. افزودن یادداشت‌های چسبان (اختیاری): نودهای Sticky Note را برای توضیح بخش‌های مختلف گردش‌کار اضافه کنید.

7. ذخیره و تست: گردش‌کار را ذخیره کنید، آن را فعال کنید و فرم را برای مشاهده نتایج ارسال کنید.

منابع

• مستندات JSDoc: https://jsdoc.app/
• گردش‌کارهای n8n در Axeto.ai: https://axeto.ai/n8n