Кастомні ноди для n8n: розробка під ключ

Навіщо потрібні кастомні ноди?

Стандартний набір n8n включає HTTP Request, Function, Webhook та інші. Однак при інтеграції з сучасними API часто виникають завдання, які складно вирішити вбудованими засобами: складна пагінація, retry з експоненційною затримкою, підтримка кількох версій API, вбудований OAuth2 з refresh-токенами. Кастомна нода — це TypeScript-пакет, який реєструється в n8n і працює як нативна. Вона дає повний контроль над логікою та перевикористовується в будь-якому workflow.

Візьмемо реальний кейс: інтеграція з CRM з rate limit 100 запитів/хв і необхідністю обробки помилок 429 та 500. У кастомній ноді ми реалізували чергу запитів із затримкою, retry з backoff і власний моніторинг. Результат — стабільна синхронізація десятків тисяч контактів без ручного втручання. Наш досвід — понад 20 інтеграцій для CRM, платіжних систем і пагінованих API. Працюємо з актуальними версіями n8n та TypeScript.

«Custom nodes are TypeScript packages that extend n8n’s functionality» — n8n docs

Як ми розробляємо кастомні ноди?

Розробка починається з аналізу документації API: визначаємо ресурси, операції, ліміти. Потім проектуємо схему credentials, структуру ноди та параметри. Реалізація на TypeScript з урахуванням усіх сценаріїв, включаючи обробку помилок. Після — тестування з моками та інтеграційні тести. Фінальний етап — пакування та постачання через npm registry або архів.

Типова структура проекту

my-n8n-nodes/
├── nodes/
│   └── MyService/
│       ├── MyService.node.ts
│       ├── MyService.node.json
│       └── myservice.svg
├── credentials/
│   └── MyServiceApi.credentials.ts
├── package.json
└── tsconfig.json

Credentials та основна нода

package.json:

{
  "name": "n8n-nodes-myservice",
  "version": "1.0.0",
  "description": "n8n nodes for MyService API",
  "main": "index.js",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "credentials": ["dist/credentials/MyServiceApi.credentials.js"],
    "nodes": ["dist/nodes/MyService/MyService.node.js"]
  },
  "devDependencies": {
    "n8n-workflow": "*",
    "typescript": "^5.0.0"
  }
}

Credentials:

// credentials/MyServiceApi.credentials.ts
import { ICredentialType, INodeProperties } from 'n8n-workflow';

export class MyServiceApi implements ICredentialType {
  name = 'myServiceApi';
  displayName = 'MyService API';
  documentationUrl = 'https://docs.myservice.com/api';

  properties: INodeProperties[] = [
    {
      displayName: 'API Key',
      name: 'apiKey',
      type: 'string',
      typeOptions: { password: true },
      default: '',
    },
    {
      displayName: 'Base URL',
      name: 'baseUrl',
      type: 'string',
      default: 'https://api.myservice.com/v1',
    },
  ];
}

Основна нода:

// nodes/MyService/MyService.node.ts
import {
  IExecuteFunctions,
  INodeExecutionData,
  INodeType,
  INodeTypeDescription,
  NodeApiError,
} from 'n8n-workflow';

export class MyService implements INodeType {
  description: INodeTypeDescription = {
    displayName: 'MyService',
    name: 'myService',
    icon: 'file:myservice.svg',
    group: ['transform'],
    version: 1,
    description: 'Interact with MyService API',
    defaults: { name: 'MyService' },
    inputs: ['main'],
    outputs: ['main'],
    credentials: [
      { name: 'myServiceApi', required: true }
    ],
    properties: [
      {
        displayName: 'Resource',
        name: 'resource',
        type: 'options',
        options: [
          { name: 'Contact', value: 'contact' },
          { name: 'Deal', value: 'deal' },
        ],
        default: 'contact',
      },
      {
        displayName: 'Operation',
        name: 'operation',
        type: 'options',
        displayOptions: { show: { resource: ['contact'] } },
        options: [
          { name: 'Create', value: 'create', action: 'Create a contact' },
          { name: 'Get', value: 'get', action: 'Get a contact' },
          { name: 'Update', value: 'update', action: 'Update a contact' },
        ],
        default: 'create',
      },
      {
        displayName: 'Email',
        name: 'email',
        type: 'string',
        displayOptions: {
          show: { resource: ['contact'], operation: ['create'] }
        },
        default: '',
        required: true,
      },
    ],
  };

  async execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]> {
    const items = this.getInputData();
    const returnData: INodeExecutionData[] = [];

    const credentials = await this.getCredentials('myServiceApi');
    const resource = this.getNodeParameter('resource', 0) as string;
    const operation = this.getNodeParameter('operation', 0) as string;

    for (let i = 0; i < items.length; i++) {
      try {
        let responseData: unknown;

        if (resource === 'contact' && operation === 'create') {
          const email = this.getNodeParameter('email', i) as string;

          responseData = await this.helpers.request({
            method: 'POST',
            url: `${credentials.baseUrl}/contacts`,
            headers: {
              'Authorization': `Bearer ${credentials.apiKey}`,
              'Content-Type': 'application/json',
            },
            body: { email },
            json: true,
          });
        }

        returnData.push({ json: responseData as object });
      } catch (error) {
        if (this.continueOnFail()) {
          returnData.push({ json: { error: error.message }, pairedItem: i });
          continue;
        }
        throw new NodeApiError(this.getNode(), error);
      }
    }

    return [returnData];
  }
}

Як встановити кастомну ноду в n8n?

Встановлення здійснюється через npm: npm install /path/to/my-n8n-nodes або з публічного registry. При використанні Docker монтуйте директорію з нодами через volume та вкажіть змінну середовища N8N_CUSTOM_EXTENSIONS. Після встановлення нода з'являється в редакторі та готова до використання.

Кастомна нода проти ланцюжка HTTP + Function: що обрати?

Типи credentials для кастомних нод

Кастомні ноди дозволяють реалізувати будь-які типи авторизації: API Key, OAuth2, Basic Auth, Bearer Token, Session Cookie. Для OAuth2 підтримується автоматичне оновлення refresh-токенів. У credentials можна додати кастомну перевірку та документацію.

Обсяг робіт та терміни

У послугу входить: вихідний код ноди (TypeScript) з коментарями, credentials-клас, інструкція по встановленню (npm/docker), документація з використання та тестове покриття (модульні + інтеграційні тести). Також надаємо консультацію з інтеграції з існуючими workflow.

Терміни: проста нода з 2–3 операціями та credentials — 2–4 дні. Складна нода з polling trigger, пагінацією, binary data — 1–2 тижні. Вартість розраховується індивідуально після аналізу вашого API. Інвестиція в кастомну ноду окупається за рахунок автоматизації. Зв'яжіться з нами для оцінки — надішлемо кошторис протягом дня. Замовте розробку, і ваша інтеграція перестане вимагати ручного втручання.

Чому варто інвестувати в кастомну ноду?

Кастомна нода — це не просто зручність, це зниження operational overhead. Замість десятків однакових workflow ви отримуєте єдину, протестовану інтеграцію. Ми гарантуємо стабільну роботу та надаємо підтримку. Наші інженери мають досвід роботи з найрізноманітнішими API — від платіжних до CRM. Отримайте консультацію інженера — напишіть нам.

Як відбувається тестування кастомних нод?

Ми проводимо модульне та інтеграційне тестування. Впроваджуємо моки для HTTP-запитів, тестуємо граничні випадки та обробку помилок. Це гарантує стабільну роботу в бойових сценаріях. Типове покриття — близько 80% рядків коду.

Типові помилки при розробці custom nodes

• Неправильна типізація параметрів displayOptions
• Відсутність обробки помилок для кожного виклику API
• Неправильне використання credentials в execute
• Ігнорування rate limit та пагінації
• Відсутність тестів

Детальніше про створення custom nodes читайте в офіційній документації n8n.

Послуги бекенд-розробки: production-grade надійність

На production-сервері о 3:14 ночі черга Laravel Jobs перестала оброблятися — 40 000 необроблених завдань у Redis. Причина: worker упав через memory leak у статичній змінній Eloquent observer, supervisor не перезапустив через misconfigured stopwaitsecs. Ми розбирали такий інцидент на проекті з 500 RPS: діагностика 4 години, фікс — 20 хвилин. Щоб ви не втрачали гроші, пропонуємо послуги бекенд-розробки з акцентом на production-grade надійність — 10+ років досвіду, 50+ проектів, 5 років на ринку. Оцінимо ваш проект за 2 дні.

Які проблеми вирішуємо

N+1 запити: головний вбивця швидкості

N+1 — найпоширеніша причина повільних сторінок у Laravel-додатках. Стандартна історія: сторінка працювала нормально на dev з 10 записами, на production з 10 000 — 8-секундне завантаження.

Laravel Debugbar у dev-оточенні показує кількість запитів. Більше 20 — сигнал для audit.

Model::preventLazyLoading(! app()->isProduction());

Telescope для профілювання: логує всі запити, jobs, mail, notifications з деталізацією. Після впровадження eager loading час завантаження сторінки падає з 8 с до 0.3 с — у 27 разів.

Memory leak у статичних змінних

У Laravel Octane або Swoole додаток тримається в пам’яті між запитами. Статичні змінні не скидаються — призводять до неконтрольованого росту пам’яті. Використовуємо defer-функції та контейнерні біндинги для коректного скидання стану.

Неправильний connection pool

Rails, Laravel, Django відкривають нове з'єднання PostgreSQL на кожен PHP/Python процес. 100 воркерів — 100 з'єднань. PostgreSQL деградує від 200+ активних з'єднань через overhead на управління.

PgBouncer у transaction pooling: 1000 воркерів → 20–50 реальних з'єднань. Це знижує latency на 40% та зменшує витрати на хостинг на 30% — при середній вартості хостингу $2,000/міс економить $600/міс. GIN-індекс для JSONB до 100 разів швидший за B-tree при пошуку.

Як Octane справляється з високим навантаженням?

Laravel Octane (RoadRunner або Swoole) прибирає overhead bootstrap на кожен HTTP-запит. Приріст: 3–8x на синтетичних бенчмарках, 2–4x на реальних додатках. Важливо: не зберігати стан у статичних змінних — застосовуємо це на проектах >1000 RPS.

Як PostgreSQL допомагає уникнути повільних запитів?

Використовуємо composite indexes для WHERE + ORDER BY, partial indexes для фільтрів з високою селективністю, GIN-індекси для JSONB та full-text search. to_tsvector + GIN замість LIKE '%query%' — запобігає seq scan навіть на мільйонах записів. Аналізуємо плани через EXPLAIN ANALYZE та pg_stat_statements.

Як обрати стек для вашого проекту?

Node.js виправданий для realtime: Laravel публікує події в Redis Pub/Sub, Node.js підписується та транслює клієнтам. Go — для goroutines (10k з'єднань на сервер — норма), але розробка повільніша, ніж Laravel.

Чому Redis критичний для продуктивності?

Redis виконує кілька ролей:

Redis Cluster для горизонтального масштабування, Sentinel для автоматичного failover. Замовте консультацію щодо оптимізації Redis для вашого проекту.

Що входить в роботу під ключ

• Архітектурне проектування (документація API, схема БД, діаграма сервісів)
• Реалізація за узгодженим ТЗ з code review
• Налаштування CI/CD (GitHub Actions, Docker), моніторингу (Sentry, Grafana), алертингу
• Навантажувальне тестування (k6, wrk) зі звітом
• Передача вихідних кодів, доступів, інструкція з деплою
• Навчання команди замовника (2–3 сесії)
• Гарантійна підтримка 1 місяць після здачі

Орієнтири по термінах

Вартість розраховується індивідуально після аналізу вимог до навантаження, інтеграцій та бізнес-логіки. Зв'яжіться з нами для безкоштовного аудиту вашого поточного backend — отримайте план оптимізації за 2 дні. Замовте консультацію та дізнайтеся, як знизити витрати на інфраструктуру на 30% без втрати продуктивності.