N8n программирование

N8n программирование: полное руководство по созданию автоматизированных рабочих процессов

N8n (произносится как «n-eight-n») — это платформа с открытым исходным кодом для оркестровки рабочих процессов (workflow automation). В отличие от многих других low-code/no-code решений, N8n построен на принципах гибкости и расширяемости, что позволяет не только использовать готовые интеграции, но и программировать собственную логику, создавать кастомные узлы (ноды) и глубоко настраивать процессы. Программирование в N8n — это процесс создания, настройки и расширения рабочих процессов с использованием JavaScript, выражений, API и собственного кода.

Архитектура и ключевые концепции N8n

Понимание архитектуры критически важно для эффективного программирования в N8n. Платформа построена на основе узлов (Nodes), которые соединяются между собой, образуя рабочий процесс (Workflow).

Узел (Node): Базовый строительный блок. Каждый узел выполняет одну конкретную задачу: получение данных, их преобразование, отправку запроса, выполнение условия.
Соединение (Connection): Стрелки, связывающие узлы. Они определяют поток данных и последовательность выполнения.
Данные (Data): Информация, которая передается между узлами в формате JSON. Каждый узел получает на входе данные от предыдущего узла и может передавать свой результат дальше.
Контекст выполнения (Execution Context): Среда, в которой работает узел, включая входящие данные, переменные окружения, параметры узла.

Основные типы узлов и их программируемость

Все узлы в N8n можно разделить на несколько категорий с точки зрения программирования.

Тип узла	Назначение	Уровень программирования
Триггерные (Trigger)	Запускают workflow (Webhook, Schedule, Polling).	Настройка параметров (CRON, endpoint).
Действия (Action)	Выполняют операции с внешними сервисами (HTTP Request, Email, Database).	Настройка запросов, заголовков, тел запросов с использованием выражений.
Преобразования (Transform)	Обрабатывают и меняют данные (Function, Code, Aggregate).	Высокий. Прямое написание кода на JavaScript.
Логика (Logic)	Управляют потоком выполнения (IF, Switch, Merge).	Программирование условий с помощью выражений.
Утилиты (Utility)	Вспомогательные операции (Wait, Set).	Настройка с использованием выражений.

Язык выражений (Expression Language) — сердце программирования в N8n

Встроенный язык выражений позволяет динамически вычислять значения параметров любого узла. Выражения заключаются в двойные фигурные скобки {{ }} и имеют доступ к различным контекстам.

Доступ к данным: {{ $json.itemId }} — получить значение поля itemId из входящего JSON.
Функции: {{ $now.format("YYYY-MM-DD") }} — текущая дата в заданном формате.
Контекст выполнения:
- $json: Данные текущего элемента.
- $input: Данные от предыдущего узла.
- $node: Данные, полученные от другого узла по имени: {{ $node["Webhook"].json["body"] }}.
- $env: Переменные окружения: {{ $env.API_KEY }}.
- $workflow: Информация о workflow (id, name).
- $now: Текущая дата и время.
- $jmespath: Выполнение запроса JMESPath к данным.

Узел «Function» и «Code»: прямое программирование на JavaScript

Эти узлы предоставляют максимальную свободу для программиста. Они выполняют пользовательский код на JavaScript (Node.js).

Узел «Function» (Функция): Предназначен для быстрой обработки данных. Код возвращает массив объектов, которые передаются дальше по workflow.

// Пример: Фильтрация и обогащение данных
const newItems = [];
for (const item of items) {
  if (item.price > 100) {
    newItems.push({
      json: {
        id: item.id,
        name: item.name.toUpperCase(),
        priceWithTax: item.price 1.2,
        timestamp: new Date().toISOString()
      }
    });
  }
}
return newItems;

Узел «Code» (Код): Более мощный и гибкий. Позволяет асинхронные операции, использование внешних npm-пакетов (если они установлены в инстансе N8n) и предоставляет полный контроль над выходными данными, включая парные данные (paired item).

Создание кастомных узлов (Custom Nodes)

Когда встроенных узлов и кода в Function-узле недостаточно, N8n позволяет создавать собственные, повторно используемые узлы. Это требует знаний TypeScript/JavaScript и структуры N8n.

Структура кастомного узла:
- node.ts: Основной класс узла, описывающий его свойства, методы, поведение.
- NodeDescription.ts: Описание узла (название, иконка, версия, входы/выходы).
- credentials.ts: Описание параметров аутентификации, если узел требует подключения к внешнему API.
- Файлы локализации, иконки.
Процесс разработки: Установка @n8n/node-dev пакета, создание проекта, кодирование логики, тестирование, упаковка и публикация (или локальное использование).

Работа с ошибками и отладка

Программирование в N8n включает обработку исключительных ситуаций.

Узел «Error Trigger»: Специальный триггер, который активирует под-workflow при ошибке в основном.
Стратегии обработки:
- Использование узла «IF» для проверки условий (например, наличие поля в ответе API).
- Использование try-catch внутри узла «Function» или «Code».
- Настройка политики повторных попыток (Retry) на уровне узла HTTP Request.
Инструменты отладки:
- Встроенный редактор выражений с автодополнением.
- Просмотр данных после выполнения каждого узла в истории выполнения (Execution).
- Использование console.log() внутри узлов «Function»/»Code» и просмотр логов сервера N8n.

Интеграция с внешними системами и API

Программирование в N8n часто связано с взаимодействием с внешним миром через API.

Узел HTTP Request: Универсальный инструмент для любых REST API вызовов. Программирование заключается в динамическом формировании URL, заголовков (Headers) и тела запроса (Body) с использованием языка выражений.
OAuth2 аутентификация: Многие встроенные узлы (Google, GitHub) поддерживают OAuth. Для кастомных узлов можно реализовать свой OAuth flow.
Webhook-узлы: Позволяют N8n выступать в роли приемника вебхуков. Программирование включает валидацию подписи, парсинг входящих данных и маршрутизацию.

Оптимизация и лучшие практики программирования

Эффективная обработка данных: Используйте узлы «Split Out» для работы с массивами и «Aggregate» для их сборки. Избегайте блокирующих операций в цикле.
Модульность: Создавайте несколько небольших, переиспользуемых workflow вместо одного гигантского. Связывайте их через «Execute Workflow» узел.
Безопасность: Никогда не храните секреты (ключи API, пароли) прямо в параметрах узла. Всегда используйте переменные окружения ($env) или Credentials.
Документация: Активно используйте поля «Notes» для комментирования сложной логики внутри workflow.
Управление версиями: Экспортируйте workflow как JSON и храните в системах контроля версий (Git).

Развертывание и управление средами

Программирование в N8n не заканчивается созданием workflow. Важен процесс доставки.

Экспорт/Импорт: Workflow, Credentials, Variables можно экспортировать в JSON. Это основа для CI/CD.
N8n CLI: Командная строка позволяет экспортировать, импортировать workflow, обновлять переменные, что позволяет автоматизировать развертывание.
Разделение сред: Рекомендуется иметь как минимум две среды: разработки (development) и производства (production). Перемещение workflow между ними осуществляется через экспорт/импорт с учетом различий в переменных окружения.

Часто задаваемые вопросы (FAQ) по программированию в N8n

Можно ли использовать внешние npm-пакеты в узле «Function»?

Нет, напрямую в узле «Function» — нельзя. Он работает в изолированной песочнице с ограниченным набором встроенных модулей. Для использования внешних пакетов необходимо либо создать кастомный узел, в котором прописать зависимости, либо использовать узел «Code» (режим «Run Once for All Items»), если пакеты установлены глобально в среде выполнения N8n (что требует доступа к серверу).

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

Избегайте обработки огромных массивов в памяти одним узлом. Используйте стратегию «разделяй и властвуй»: узел «SplitOut» разбивает массив на отдельные элементы, которые обрабатываются параллельно (если не стоит ограничение на параллелизм), после чего могут быть собраны узлом «Aggregate». Для пакетной обработки данных используйте пагинацию в API-запросах.

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

Есть несколько способов:

Создать отдельный workflow с общей логикой и вызывать его через узел «Execute Workflow».
Создать кастомный узел, который можно будет добавлять в любое количество workflow.
Выносить часто используемые значения и шаблоны в Workflow Variables (Переменные рабочего процесса).

Как реализовать цикл (loop) в N8n?

Прямого узла «Loop» нет. Циклы реализуются косвенно:

Для элементов массива: Узел «SplitOut» автоматически создает итерации.
По условию (while): Используется связка узлов «IF» и «Merge». Ветка «true» от узла IF возвращает данные на вход этого же узла (через другие узлы для изменения условия). Необходимо добавить узел «Wait» или ограничитель, чтобы избежать бесконечного цикла.

Как отлаживать сложные выражения?

Используйте встроенный редактор выражений (иконка рядом с полем). В нем можно в реальном времени видеть результат вычисления выражения на основе данных из предыдущего узла. Для промежуточного вывода значений используйте узел «Function» с console.log(items) и смотрите логи сервера N8n.

В чем разница между режимами выполнения «Run Once» и «Run for Each Item» в узлах Function/Code?

«Run Once for All Items»: Узел получает на вход ВЕСЬ массив элементов (items). Код выполняется один раз. Подходит для агрегации, группировки, операций со всем набором данных.
«Run Once for Each Item»: Узел запускается отдельно для КАЖДОГО элемента. Код получает на вход один элемент (массив items, но с одним объектом). Это режим по умолчанию, аналогичный поведению большинства других узлов.

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