Использование кастомного кода в n8n: Function и Function Item

Визуальная автоматизация бизнес-процессов через n8n открывает огромные возможности, но иногда встроенных узлов недостаточно для решения специфических задач. В таких случаях на помощь приходит n8n кастомный код. Это руководство предназначено для специалистов по автоматизации, разработчиков и бизнес-аналитиков, которые хотят расширить функциональность своих рабочих процессов с помощью JavaScript. Вы узнаете, как эффективно использовать узлы Function и Function Item, научитесь обрабатывать данные программно и решать сложные задачи трансформации информации.

Предварительные требования

Перед началом работы с кастомным кодом в n8n убедитесь, что у вас есть:

• Установленный экземпляр n8n (локальный или облачный)
• Базовые знания JavaScript (понимание переменных, функций, циклов)
• Понимание структуры данных JSON
• Доступ к редактированию рабочих процессов в n8n
• Знакомство с концепцией обработки данных в пакетном режиме

Основные различия между Function и Function Item

Первое, что необходимо понять при работе с кастомным кодом в n8n, это различия между двумя основными узлами для программирования.

Характеристика	Function Node	Function Item Node
Область применения	Обработка всех входящих элементов одновременно	Обработка каждого элемента отдельно
Доступ к данным	Через массив $input.all()	Через объект $json текущего элемента
Производительность	Выше для массовых операций	Ниже при большом объеме данных
Сложность кода	Требует явной работы с циклами	Проще для элементарных преобразований
Возврат результата	Массив объектов return items	Единичный объект return {...}
Использование циклов	Необходимо вручную перебирать элементы	Автоматически применяется к каждому

Function Node: работа с несколькими элементами

Function node предоставляет полный контроль над всем набором входящих данных. Это идеальный выбор, когда необходимо выполнить агрегацию, фильтрацию или сложные преобразования.

Структура Function Node

В Function node вы работаете с JavaScript кодом, где доступны специальные переменные и методы:

• $input.all() — получить все входящие элементы
• $input.first() — получить первый элемент
• $input.last() — получить последний элемент
• items — массив для возврата результата

Практический пример: агрегация данных о продажах

// Получаем все входящие элементы
const allItems = $input.all();

// Инициализируем объект для хранения суммарных продаж по категориям
const salesByCategory = {};

// Обрабатываем каждый элемент
for (const item of allItems) {
  const category = item.json.category;
  const amount = item.json.amount;
  
  if (!salesByCategory[category]) {
    salesByCategory[category] = 0;
  }
  
  salesByCategory[category] += amount;
}

// Формируем результирующий массив
const result = Object.entries(salesByCategory).map(([category, total]) => ({
  json: {
    category: category,
    totalSales: total,
    timestamp: new Date().toISOString()
  }
}));

return result;

Function Item Node: индивидуальная обработка

Function Item node автоматически применяется к каждому входящему элементу отдельно. Это упрощает код, когда нужно трансформировать данные без сложной логики взаимодействия между элементами.

Основные особенности Function Item

При работе с Function Item node важно понимать следующие аспекты:

• Код выполняется для каждого элемента независимо
• Доступ к данным через $json (объект текущего элемента)
• Возвращаемое значение автоматически оборачивается в структуру n8n
• Невозможно напрямую обращаться к другим элементам потока

Практический пример: обогащение данных клиентов

// Получаем данные текущего элемента
const customerData = $json;

// Вычисляем дополнительные поля
const fullName = `${customerData.firstName} ${customerData.lastName}`;
const emailDomain = customerData.email.split('@')[1];
const registrationYear = new Date(customerData.registeredAt).getFullYear();

// Определяем сегмент клиента на основе количества заказов
let segment;
if (customerData.orderCount > 50) {
  segment = 'VIP';
} else if (customerData.orderCount > 10) {
  segment = 'Regular';
} else {
  segment = 'New';
}

// Возвращаем обогащенный объект
return {
  ...customerData,
  fullName: fullName,
  emailDomain: emailDomain,
  registrationYear: registrationYear,
  customerSegment: segment,
  lastProcessed: new Date().toISOString()
};

Пошаговое руководство по внедрению кастомного кода

1. Определите тип задачи: Решите, нужна ли обработка всех элементов вместе (Function) или по отдельности (Function Item)
2. Добавьте соответствующий узел: Перетащите Function или Function Item node на канвас рабочего процесса
3. Проанализируйте входные данные: Используйте режим отладки для просмотра структуры входящих данных
4. Напишите код обработки: Реализуйте логику трансформации с использованием JavaScript
5. Протестируйте на примере данных: Выполните узел и проверьте корректность результата
6. Добавьте обработку ошибок: Включите проверки и try-catch блоки для устойчивости
7. Оптимизируйте производительность: При работе с большими объемами данных используйте эффективные алгоритмы
8. Документируйте код: Добавьте комментарии для будущего сопровождения

Продвинутые техники работы с данными

Использование встроенных библиотек

В n8n кастомный код имеет доступ к нескольким встроенным библиотекам, что расширяет возможности обработки данных:

• Luxon для работы с датами и временем
• JMESPath для запросов к JSON структурам
• Стандартные объекты JavaScript (Math, String, Array и другие)

// Пример работы с датами через Luxon
const { DateTime } = require('luxon');

const items = $input.all();

const processed = items.map(item => {
  const orderDate = DateTime.fromISO(item.json.orderDate);
  const deliveryDate = orderDate.plus({ days: 3 });
  
  return {
    json: {
      ...item.json,
      estimatedDelivery: deliveryDate.toISO(),
      dayOfWeek: deliveryDate.weekdayLong,
      isWeekend: deliveryDate.weekday > 5
    }
  };
});

return processed;

Работа с внешними API из Function Node

Иногда необходимо обогатить данные информацией из внешних источников прямо в коде:

const items = $input.all();
const enrichedItems = [];

for (const item of items) {
  // Используем $http для запросов (доступно в некоторых версиях)
  // Альтернатива: использовать HTTP Request node перед Function
  
  const processedItem = {
    json: {
      originalData: item.json,
      processingTimestamp: Date.now(),
      status: 'enriched'
    }
  };
  
  enrichedItems.push(processedItem);
}

return enrichedItems;

Ключевые возможности кастомного кода в n8n

При работе с Function и Function Item nodes доступны следующие возможности:

• Сложная трансформация данных с использованием любых JavaScript методов
• Условная логика и ветвление на основе содержимого данных
• Математические вычисления и статистическая обработка
• Работа с регулярными выражениями для парсинга текста
• Форматирование и валидация данных перед отправкой в другие системы
• Создание динамических структур данных на основе входящей информации
• Объединение и разделение массивов данных
• Фильтрация элементов по сложным критериям
• Генерация уникальных идентификаторов и хэшей
• Преобразование форматов данных (XML в JSON, CSV в массив и т.д.)

Устранение частых проблем

Ошибка: "Cannot read property of undefined"

Причина: Попытка обращения к несуществующему свойству объекта.

Решение: Всегда проверяйте наличие свойств перед обращением:

const items = $input.all();

const safe = items.map(item => {
  const data = item.json || {};
  const userName = data.user?.name || 'Unknown';
  const userAge = data.user?.age ?? 0;
  
  return {
    json: {
      name: userName,
      age: userAge
    }
  };
});

return safe;

Проблема: Function Node возвращает пустой результат

Причина: Забыли вернуть массив объектов в правильном формате.

Решение: Убедитесь, что возвращаете массив с объектами, содержащими ключ json:

// Неправильно
return [{ name: 'Test' }];

// Правильно
return [{ json: { name: 'Test' } }];

Проблема: низкая производительность при большом объеме данных

Причина: Использование Function Item node для обработки тысяч элементов.

Решение: Переключитесь на Function node и используйте эффективные методы массивов:

const items = $input.all();

// Быстрее чем циклы
const result = items
  .filter(item => item.json.status === 'active')
  .map(item => ({
    json: {
      id: item.json.id,
      processed: true
    }
  }));

return result;

Ошибка выполнения из-за синтаксиса

Причина: Опечатки в коде или использование несовместимого синтаксиса JavaScript.

Решение: Используйте современный синтаксис ES6+ и проверяйте код в редакторе:

• Используйте const и let вместо var
• Применяйте стрелочные функции для краткости
• Используйте template literals для строк
• Проверяйте закрытие скобок и кавычек

FAQ: Частые вопросы о кастомном коде в n8n

Можно ли использовать npm пакеты в Function node?

В стандартной версии n8n Function node имеет доступ только к встроенным библиотекам (Luxon, JMESPath). Для использования сторонних npm пакетов необходимо создать кастомный node или использовать Execute Command node для запуска отдельного Node.js скрипта. Однако в самостоятельно развернутых версиях n8n можно настроить доступ к дополнительным модулям через конфигурацию.

Какой узел выбрать: Function или Function Item?

Выбирайте Function node, когда вам нужно работать со всеми элементами одновременно (агрегация, группировка, сортировка, фильтрация с условиями между элементами). Используйте Function Item node для простых преобразований каждого элемента независимо (добавление полей, форматирование, вычисления на основе данных одного элемента). Function node обычно производительнее для больших объемов данных.

Как отлаживать код в Function node?

Для отладки используйте несколько методов: добавляйте console.log() для вывода промежуточных значений в консоль выполнения n8n, используйте режим выполнения с остановкой на узле для просмотра входных данных, возвращайте промежуточные результаты для проверки. Также можно тестировать логику в отдельном JavaScript окружении перед переносом в n8n.

Есть ли ограничения на время выполнения кастомного кода?

Да, по умолчанию в n8n есть таймаут выполнения узлов, который обычно составляет несколько минут (зависит от настроек экземпляра). Для длительных операций рекомендуется разбивать обработку на части или использовать асинхронные подходы. Также учитывайте лимиты памяти при обработке очень больших массивов данных.

Как обрабатывать ошибки в кастомном коде?

Используйте конструкцию try-catch для перехвата ошибок и возврата информативных сообщений. Например:

try {
  const items = $input.all();
  // ваш код обработки
  return processedItems;
} catch (error) {
  return [{
    json: {
      error: true,
      message: error.message,
      timestamp: new Date().toISOString()
    }
  }];
}

Это позволит продолжить выполнение workflow и обработать ошибку на следующих шагах.

Заключение и следующие шаги

Овладение кастомным кодом в n8n через Function и Function Item nodes открывает безграничные возможности для автоматизации бизнес-процессов. Вы научились выбирать правильный тип узла для конкретной задачи, писать эффективный JavaScript код для обработки данных и решать типичные проблемы.

Для дальнейшего развития навыков рекомендуется:

• Изучите документацию n8n по встроенным переменным и методам
• Практикуйтесь на реальных задачах автоматизации из вашего бизнеса
• Исследуйте примеры workflow в сообществе n8n
• Комбинируйте кастомный код с встроенными узлами для оптимальных решений
• Создайте библиотеку переиспользуемых функций для типовых задач

Помните, что хороший кастомный код должен быть читаемым, документированным и устойчивым к ошибкам. Начинайте с простых преобразований и постепенно переходите к более сложным сценариям обработки данных.