Function node n8n

Function Node в n8n: Полное руководство по кастомизации рабочих процессов

Function node в n8n является одним из наиболее мощных и гибких узлов платформы. Он позволяет выполнять пользовательский JavaScript-код (Node.js) непосредственно внутри рабочего процесса, обеспечивая полный контроль над обработкой данных, их трансформацией, логикой выполнения и интеграцией со сторонними сервисами на уровне кода. Этот узел служит мостом между визуальным программированием n8n и традиционной разработкой на JavaScript, открывая возможности для реализации любой необходимой логики, которую невозможно или сложно собрать с помощью стандартных узлов.

Архитектура и принцип работы Function Node

Function node выполняется в изолированной среде Node.js внутри n8n. При активации узла он получает на вход один или несколько входных элементов (items), которые представляют собой объекты JavaScript. Код, написанный пользователем, выполняется для каждого элемента или для всего массива элементов, в зависимости от выбранного режима. Результатом выполнения кода должен быть возврат новых или модифицированных элементов, которые затем передаются на следующие узлы в рабочем процессе.

Основные объекты, доступные внутри Function node:

• items: Массив объектов, представляющих входные данные. Каждый объект имеет структуру { json: {}, binary: {}, ... }.
• $input: Методы для получения входных данных от других узлов (например, $input.first(), $input.all()).
• $node: Позволяет получать данные из других узлов в том же рабочем процессе.
• $json, $binary: Сокращенные ссылки на данные текущего элемента.
• $itemIndex: Индекс текущего обрабатываемого элемента (начинается с 0).
• getNodeParameter(): Функция для чтения значений, заданных в полях конфигурации узла (например, строки, числа, опции).
• helpers: Объект, предоставляющий вспомогательные функции, такие как prepareFieldsArray().

Режимы выполнения Function Node

Function node может работать в двух основных режимах, которые определяют, как обрабатываются входные данные.

Режим	Описание	Когда использовать
Run Once for All Items	Код выполняется один раз. В переменной items доступен полный массив всех входных элементов. Пользователь должен вернуть массив элементов.	Агрегация данных, сравнение элементов между собой, пакетная обработка, операции, требующие полного набора данных.
Run Once for Each Item	Код выполняется отдельно для каждого элемента. В переменных $json, $binary доступны данные текущего элемента. Необходимо вернуть один объект элемента.	Трансформация каждого элемента независимо, обогащение данных из внешних API, валидация полей, индивидуальные вычисления.

Типовые сценарии использования с примерами кода

1. Трансформация и маппинг данных

Изменение структуры JSON, переименование полей, вычисление новых значений.

// Пример: Конкатенация полей и создание нового объекта
const transformedItem = {
  json: {
    fullName: `${$json.firstName} ${$json.lastName}`,
    userId: $json.id,
    metadata: {
      original: $json,
      processedAt: new Date().toISOString()
    }
  }
};
return transformedItem;

2. Фильтрация элементов

Условное пропускание или отбрасывание элементов на основе их данных.

// Пример: Пропустить только заказы с суммой больше 100
if ($json.orderTotal > 100) {
  // Возвращаем элемент, чтобы он прошел дальше
  return { json: $json };
}
// Если условие не выполнено, возвращаем null, чтобы элемент не передавался
return null;

3. Агрегация и сводка данных

Используется в режиме «Run Once for All Items».

// Пример: Расчет общей суммы и среднего значения по всем элементам
let total = 0;
let count = items.length;

for (const item of items) {
  total += item.json.value;
}

const summaryItem = {
  json: {
    totalSum: total,
    averageValue: count > 0 ? total / count : 0,
    reportGenerated: new Date().toISOString(),
    numberOfRecords: count
  }
};
// Возвращаем массив с одним итоговым элементом
return [summaryItem];

4. Работа с внешними API и библиотеками

Function node позволяет использовать встроенные модули Node.js и устанавливать npm-пакеты.

// Пример: Использование axios для HTTP-запроса (пакет должен быть установлен в n8n)
const axios = require('axios');
const apiKey = getNodeParameter('apiKey');

try {
  const response = await axios.get('https://api.example.com/data', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
  // Обогащаем текущий элемент данными из API
  $json.externalData = response.data;
  return { json: $json };
} catch (error) {
  // Обработка ошибок - можно выбросить ошибку или вернуть элемент с флагом ошибки
  throw new Error(`API Call Failed: ${error.message}`);
}

5. Сложная бизнес-логика и ветвление

Принятие решений о дальнейшем пути выполнения рабочего процесса.

// Пример: Определение приоритета заявки на основе нескольких полей
let priority = 'low';
if ($json.urgentFlag || $json.customerTier === 'premium') {
  priority = 'high';
} else if ($json.estimatedValue > 5000) {
  priority = 'medium';
}

// Добавляем поле priority и динамически задаем выход, к которому пойдет элемент
$json.priority = priority;

// Возвращаем объект с указанием индекса выхода (0, 1, 2...)
if (priority === 'high') {
  return [[{ json: $json }], [], []]; // Пойдет на первый выход
} else if (priority === 'medium') {
  return [[], [{ json: $json }], []]; // Пойдет на второй выход
} else {
  return [[], [], [{ json: $json }]]; // Пойдет на третий выход
}

Работа с бинарными данными (файлами)

Function node может обрабатывать не только JSON, но и файлы (изображения, PDF, документы).

// Пример: Получение информации о бинарном файле
const binaryData = $binary.data; // Название бинарного свойства (например, 'data')
const fileName = $binary.data.fileName;
const fileSize = $binary.data.data.length; // Размер в байтах
const mimeType = $binary.data.mimeType;

// Можно модифицировать метаданные или обработать содержимое файла
$json.fileProcessed = true;
$json.originalFileName = fileName;

return { json: $json, binary: $binary };

Обработка ошибок и отладка

Правильная обработка ошибок критически важна для надежности рабочего процесса.

• Throw Error: Использование throw new Error("Сообщение") остановит выполнение узла и пометит весь workflow как неудачный.

<

• Возврат ошибки в данных: Можно возвращать элемент с полем _error и обрабатывать его в последующих узлах.
• Использование try-catch: Обязательно для асинхронных операций (запросы к API).
• Отладка через console.log: Сообщения выводятся в панель выполнения узла (Execution Details). Используйте console.log(), console.table() для инспекции данных.

Производительность и лучшие практики

Практика	Рекомендация	Причина
Выбор режима	Используйте «Run Once for Each Item» для независимой обработки. Используйте «Run Once for All Items» для операций над всем набором.	Оптимизация использования памяти и времени выполнения.
Кэширование	Кэшируйте результаты тяжелых операций или запросов, если данные повторяются.	Снижение нагрузки на внешние системы и ускорение выполнения.
Асинхронный код	Всегда используйте async/await или Promises для операций ввода-вывода (API, БД, файлы).	Избежание блокировки event loop и повышение эффективности.
Валидация входных данных	Проверяйте наличие и тип ожидаемых полей в $json в начале кода.	Предотвращение runtime-ошибок из-за неожиданной структуры данных.
Модульность	Для сложной логики выносите код в отдельные функции внутри узла.	Улучшение читаемости, тестируемости и повторного использования кода.

Интеграция Function Node с другими узлами n8n

Function node часто выступает связующим звеном:

• До: Узлы, собирающие данные (HTTP Request, SQL, Google Sheets) передают сырые данные в Function node для обработки.
• После: Обработанные данные из Function node отправляются в узлы для сохранения (Database, Spreadsheet), уведомления (Email, Slack) или дальнейшей маршрутизации (Switch, IF).
• Параллельно: Использование нескольких Function nodes для разделения ответственности (например, один для валидации, другой для обогащения).

Ответы на часто задаваемые вопросы (FAQ)

Какие версии JavaScript поддерживает Function node?

Function node поддерживает стандарт ECMAScript, соответствующий версии Node.js, на которой работает ваш экземпляр n8n (обычно Node.js LTS). Это включает поддержку async/await, деструктуризации, стрелочных функций, optional chaining и других современных возможностей. Следует избегать использования функций, специфичных для браузерного JavaScript (например, `window`, `document`).

Как установить внешнюю npm-библиотеку для использования в Function node?

Библиотеки должны быть установлены на уровне сервера n8n. Если вы используете Docker-образ, вам нужно создать собственный Dockerfile, который выполняет `npm install ` внутри директории n8n. При самостоятельной установке n8n выполните команду `npm install ` в корневой директории проекта n8n. После перезагрузки n8n библиотека станет доступна для require() внутри узла.

Чем Function node отличается от Code node?

В n8n существует два узла для выполнения кода: Function node и Code node (или «Python Script»). Function node работает на JavaScript/Node.js и имеет прямой доступ к внутренним объектам n8n (`$input`, `$json`, `items`). Code node, как правило, предназначен для выполнения скриптов на других языках (например, Python) через отдельный процесс или среду выполнения, что может накладывать ограничения на производительность и доступ к контексту n8n. Function node является более интегрированным и производительным решением для JavaScript-логики.

Как обрабатывать большие объемы данных без утечек памяти?

При обработке тысяч элементов в режиме «Run Once for All Items» избегайте создания в памяти чрезмерно больших промежуточных массивов. Обрабатывайте данные поточнее, если это возможно. Используйте режим «Run Once for Each Item» для независимой обработки. Убедитесь, что в коде нет глобальных переменных, накапливающих данные от всех выполнений. В случае очень больших наборов данных рассмотрите возможность разделения потока на пачки с помощью узлов «Split In Batches» или «Limit».

Можно ли использовать Function node для записи данных в базу данных напрямую?

Да, это технически возможно, если установлен соответствующий драйвер базы данных (например, `pg` для PostgreSQL, `mysql2` для MySQL). Однако рекомендуется использовать для этого специализированные узлы n8n (такие как «PostgreSQL», «MySQL»), так как они обеспечивают встроенную обработку ошибок, пул соединений и более удобную конфигурацию. Function node для работы с БД стоит использовать только для выполнения сложных запросов или операций, которые не поддерживаются стандартными узлами.

Как организовать повторное использование кода из Function node в разных workflow?

Прямого механизма импорта/экспорта кода Function node между workflow не существует. Распространенные стратегии:

• Создание шаблонного workflow с настроенным Function node и его копирование.
• Вынос общей логики в пользовательский npm-модуль, который устанавливается в n8n и затем подключается через `require()` в каждом Function node.
• Использование внешнего HTTP-сервиса, инкапсулирующего логику, и вызов его через узел «HTTP Request».

Как обеспечить безопасность при выполнении пользовательского кода?

В n8n Community Edition код выполняется в той же среде, что и сам n8n. Это представляет риски безопасности, особенно при развертывании в многопользовательском режиме или использовании непроверенных workflow. Рекомендации:

• Запускайте n8n в изолированной среде (Docker-контейнер, виртуальная машина).
• Тщательно проверяйте код Function node в workflow, полученных из ненадежных источников.
• Рассмотрите использование n8n Enterprise Edition, которая предлагает изоляцию выполнения пользовательского кода в песочнице (sandbox) для повышения безопасности.
• Ограничивайте использование опасных функций Node.js (например, доступа к файловой системе, child processes) если это возможно.