Типовые ошибки: потеря `msg`, неправильный тип данных, зацикливание

Урок 6 · Node-RED: установка, flows, msg/JSON, отладка · 30 мин · theory

Введение: цена типовой ошибки в автоматизации

При проектировании систем автоматизации на платформе Node-RED инженер сталкивается с задачами, цена ошибки в которых может быть крайне высока. Три типовые ошибки — потеря объекта `msg`, несоответствие типов данных и зацикливание потока — являются самыми распространенными и коварными. Они редко вызывают немедленный отказ системы, но проявляются в виде нестабильной работы, ложных срабатываний и сложных для диагностики "плавающих" дефектов.

Представим последствия на реальном объекте, управляемом контроллером HI:

Потеря `msg`: Поток, управляющий климатом, получает данные от датчика температуры, но из-за ошибки в ноде `Function` объект `msg` не передается дальше. В результате, команда на включение отопительного котла никогда не будет отправлена. Для жилого дома зимой это означает остывшее помещение и потенциальный риск заморозки системы отопления.
Несоответствие типов данных: MQTT-брокер передает значение температуры `"25.0"` (строка). Нода `Switch`, настроенная на сравнение с числом `24`, не срабатывает, так как строковое сравнение дает непредсказуемый результат. Система безопасности не активирует кондиционирование, и оборудование в серверной перегревается.
Зацикливание: Поток, управляющий освещением, отправляет команду "включить" в тот же MQTT-топик, на который он подписан для получения статуса. Это создает бесконечный цикл. Контроллер HI будет со 100% загрузкой процессора пытаться обработать лавину сообщений, что приведет к его зависанию, отказу интерфейса и полной потере управления объектом до аппаратной перезагрузки.

Именно поэтому важно не просто исправлять ошибки по факту их появления, а строить превентивно отказоустойчивые потоки. Это означает, что на этапе проектирования нужно закладывать механизмы, которые не дадут этим ошибкам проявиться. Как мы уже рассматривали при создании «Операционного слоя» (Ops Layer), централизованный мониторинг, перехват ошибок и журналирование являются вашими главными союзниками. Этот урок посвящен тому, как выявлять и предотвращать эти три фундаментальные проблемы на самом раннем этапе.

---

Ошибка №1: Потеря `msg` объекта в потоке

Основа всей работы в Node-RED — это жизненный цикл объекта `msg`. Каждая нода в потоке получает на свой вход объект `msg`, выполняет с ним какие-либо действия и (в большинстве случаев) передает его дальше на выход. Потеря `msg` означает, что на каком-то из этапов этот жизненный цикл прервался, и поток перестал исполняться, не выдав при этом явной ошибки.

Причины потери `msg`

Ключевая особенность, которую нужно понять: если нода не возвращает `msg` (или не создает и не отправляет новый `msg` с помощью `node.send()`), то поток на этой ветке останавливается.

Нода `Function` без оператора `return msg;`

Это самая частая причина. Инженер пишет сложную логику, изменяет `msg.payload`, но забывает в конце добавить `return msg;`. Нода успешно выполняет код, но так как ничего не возвращено, последующие ноды никогда не получат сообщение.

    // Неправильно: `msg` будет потерян
    let temperature = msg.payload.value;
    if (temperature > 25) {
        msg.payload = "HIGH";
    } else {
        msg.payload = "NORMAL";
    }
    // Отсутствует 'return msg;'

Нода `Switch` без совпадений

Если нода `Switch` настроена на проверку условия, и ни одно из правил не выполняется, а опция "otherwise" (иначе) не используется, `msg` просто "исчезает". Поток не продолжит свое выполнение.

Неправильно сконфигурированные ноды

Некоторые ноды, например `Split`, могут разделять одно сообщение на несколько. Если следующая за ними нода ожидает единый `msg`, логика нарушится. Другие ноды, такие как `Join`, наоборот, ждут определенное количество сообщений для сборки, и если одно из них потеряется по пути, `Join` никогда не сработает и не передаст `msg` дальше.

Синтаксическая ошибка, пойманная `try...catch` без `throw`

Внутри ноды `Function` может быть блок `try...catch`. Если в блоке `try` произойдет ошибка, управление перейдет в `catch`. Если в `catch` нет `return msg` или `throw error`, то выполнение функции просто завершится, и `msg` будет потерян.

> ℹ️ Информация: Важно различать потерю `msg` и ошибку в потоке. Нода `Catch`, как мы рассматривали ранее, перехватывает исключения, которые генерируются внутри нод (например, ошибка подключения к Modbus-устройству или синтаксическая ошибка в коде). Потеря `msg` из-за логической ошибки (забытый `return`) не является исключением, и нода `Catch` ее не увидит. Система будет "молчать", что делает диагностику сложнее.

---

Практика: отслеживание `msg` с помощью ноды Debug

Самый надежный способ найти, где именно в потоке теряется объект `msg` — это применить стратегию «разделяй и властвуй» с помощью ноды `Debug`. Идея проста: мы расставляем «контрольные точки» и смотрим, до какой из них доходит сообщение.

Стратегия пошаговой трассировки

Определите путь потока. Проследите визуально, через какие ноды должен проходить `msg` от начала до конца.

Поставьте ноды `Debug` на выходе каждой ключевой ноды. Особенно важно ставить их после нод `Function`, `Switch`, `Change` и любых других, где происходит трансформация данных или маршрутизация.

Настройте каждую ноду `Debug` на вывод полного объекта сообщения. Это критически важно. Анализ одного лишь `msg.payload` может скрыть проблему. Возможно, `msg` передается, но в нем отсутствует необходимое для следующей ноды свойство.

> 💡 Подсказка: Используйте ноду `Debug` с выводом полного объекта `msg` на каждом шаге, где вы подозреваете потерю. Это самый быстрый способ локализовать проблемный участок потока.

Пример: Поиск утечки в ноде `Switch`

Предположим, у нас есть поток, который должен включать вентиляцию, если влажность превышает 60%.

Проблемный поток:

`(MQTT In: humidity)` -> `(Switch: > 60)` -> `(Function: create command)` -> `(Relay Out)`

Нода `MQTT In` получает `msg` с `payload` равным, например, `{"value": 65}`.
Мы видим, что реле не включается. На выходе из ноды `Relay Out` в `Debug` пусто.
Шаг 1: Ставим ноду `Debug` после `MQTT In`. Видим, что `msg.payload` = `{"value": 65}`. Сообщение приходит.
Шаг 2: Ставим ноду `Debug` после `Switch`. В панели отладки пусто. Сообщение не прошло через `Switch`.
Диагностика: Открываем ноду `Switch`. Видим, что она проверяет `msg.payload` на `> 60`. Но `msg.payload` — это объект `{"value": 65}`, а не число. Объект не может быть больше числа.
Исправление: Меняем настройку ноды `Switch`, чтобы она проверяла свойство `msg.payload.value`. Теперь `65 > 60`, условие выполняется, и `msg` проходит дальше.

Пример: Фиксация "пожирающей" `msg` ноды `Function`

Рассмотрим код из предыдущего раздела, который "теряет" `msg`.

// Проблемный код в ноде Function
let temperature = msg.payload.value;
if (temperature > 25) {
    msg.payload = "HIGH";
    // здесь нет return
} else {
    msg.payload = "NORMAL";
    // и здесь нет return
}
// и здесь общего return тоже нет

Если мы поставим `Debug` до этой ноды, `msg` будет виден. Если поставим после, `msg` виден не будет. Это однозначно указывает на проблему внутри `Function`.

Исправленный код:

let temperature = msg.payload.value;
if (temperature > 25) {
    msg.payload = "HIGH";
} else {
    msg.payload = "NORMAL";
}
// Добавляем return
return msg;

Более надежный вариант — использовать несколько выходов для разных состояний, чтобы логика была еще более явной.

let temperature = msg.payload.value;
if (temperature > 25) {
    // Отправляем msg на первый выход
    return [msg, null]; 
} else {
    // Отправляем msg на второй выход
    return [null, msg];
}

---

Ошибка №2: Несоответствие типов данных (Data Type Mismatch)

JavaScript, язык, на котором работает Node-RED, является языком с динамической типизацией. Это означает, что переменная может легко менять свой тип (например, из числа стать строкой). Однако, большинство нод ожидают на входе данные строго определенного типа. Именно это расхождение между гибкостью языка и строгостью нод порождает массу проблем.

Источники данных с непредсказуемым типом

MQTT: Самый частый источник проблем. Многие MQTT-брокеры по умолчанию передают все значения в `payload` как строки (string). Сообщение, которое выглядит как `{ "value": 25.5 }`, на самом деле может быть строкой `'{ "value": 25.5 }'`.
HTTP-запросы: Данные, приходящие в теле (body) HTTP-запроса, часто являются строкой, которую нужно дополнительно парсить в JSON.
Node-RED Dashboard (UI): Поля ввода текста всегда возвращают строки. Слайдеры могут возвращать числа или строки в зависимости от конфигурации.

Как несоответствие типов ломает логику

Проблема проявляется в узлах, выполняющих сравнение или математические операции.

| Операция | Неправильно (сравнение строк) | Правильно (сравнение чисел) |

| -------------------------- | ----------------------------- | --------------------------- |

| `msg.payload > 100` | `"25"` > `100` -> `true` | `25` > `100` -> `false` |

| `msg.payload == true` | `"true"` == `true` -> `false` | `true` == `true` -> `true` |

| `msg.payload + 1` | `"10"` + `1` -> `"101"` | `10` + `1` -> `11` |

В первом примере `"25"` сравнивается с `100` лексикографически (посимвольно). Символ `"2"` идет раньше символа `"1"`, поэтому результат может быть непредсказуемым в зависимости от реализации движка JS. Во втором примере строка `"true"` не равна булевому значению `true`. В третьем примере происходит конкатенация строк вместо сложения чисел.

Пример: Ошибка в потоке управления климатом

Задача: Включать кондиционер, если температура из MQTT-топика `sensors/office/temperature` превышает 24.5 °C. Поток: `[MQTT In]` -> `(JSON parser)` -> `(Switch: > 24.5)` -> `[Call Service: AC ON]` Проблема: Нода `MQTT In` получает сообщение `msg.payload` = `"25.1"`. Это строка. Нода `JSON parser` в данном случае не нужна, так как это не JSON-строка. Сообщение поступает в `Switch`, который настроен на проверку: `msg.payload` (number) `>` `24.5`. Нода сравнивает строку `"25.1"` с числом `24.5`. Такое сравнение либо не выполняется, либо дает неверный результат. Кондиционер не включается. Решение: Добавить ноду `Change` или `Function` для явного преобразования типа перед `Switch`. С помощью ноды `Change`:

Set: `msg.payload`
to: `JSONata`
Expression: `$number(payload)`

С помощью ноды `Function`:

// Преобразуем payload в число с плавающей точкой
msg.payload = parseFloat(msg.payload);

// Проверка, что преобразование прошло успешно
if (isNaN(msg.payload)) {
    // Если результат не является числом, останавливаем поток и логируем ошибку
    node.error("Failed to parse payload to a number: " + msg.sent_payload, msg);
    return null;
}

return msg;

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

---

Ошибка №3: Бесконечные циклы (Infinite Loops)

> ⚠️ Внимание: Бесконечные циклы — одна из самых опасных ошибок. Они могут привести к полной остановке контроллера HI и потребовать аппаратной перезагрузки. Всегда проверяйте логику обратной связи в потоках, особенно при работе с MQTT.

Зацикливание в Node-RED — это ситуация, когда поток прямо или косвенно триггерит сам себя, создавая бесконечную цепочку выполнения. Это приводит к экспоненциальному росту количества сообщений в системе.

Классический сценарий зацикливания

Самый распространенный пример связан с протоколом MQTT:

Нода `MQTT In` подписывается на топик `home/livingroom/light/state`.

Далее по потоку идет логика, которая решает, нужно ли изменить состояние света.

В конце потока нода `MQTT Out` отправляет новое состояние в тот же самый топик `home/livingroom/light/state`.

Что происходит:

Нода `MQTT Out` отправляет сообщение.
Брокер доставляет это сообщение всем подписчикам, включая нашу же ноду `MQTT In`.
Нода `MQTT In` получает `msg`, и весь цикл начинается заново. И так до бесконечности.

Последствия для контроллера HI

100% загрузка CPU: Процессор контроллера будет полностью занят обработкой лавины сообщений.
Рост потребления RAM: Очередь сообщений будет расти, занимая всю доступную оперативную память.
Отказ интерфейса: Веб-интерфейс Node-RED и система управления контроллером перестанут отвечать.
Остановка потоков: Node-RED может полностью "зависнуть", и никакие другие сценарии автоматизации исполняться не будут.
Переполнение логов: Если настроено журналирование, логи будут забиты одинаковыми сообщениями, что затруднит диагностику.

Диагностика цикла

Если вы подозреваете зацикливание, а интерфейс уже недоступен, можно подключиться к контроллеру HI по SSH и выполнить команду `top`. Вы увидите процесс `node-red`, потребляющий 99-100% одного из ядер процессора. Это верный признак проблемы.

# Пример вывода команды top на контроллере
$ top

top - 10:35:12 up 1 day,  2:10,  1 user,  load average: 1.15, 0.85, 0.50
Tasks: 123 total,   2 running, 121 sleeping,   0 stopped,   0 zombie
%Cpu(s): 25.2 us,  0.5 sy,  0.0 ni, 74.3 id,  0.0 wa,  0.0 hi,  0.0 si,  0.0 st
MiB Mem :   3921.4 total,   1521.4 free,    800.0 used,   1600.0 buff/cache
MiB Swap:    100.0 total,    100.0 free,      0.0 used.   2921.4 avail Mem

  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND
1234 nodered   20   0  785860 158788  21896 R  99.9   4.0   0:45.12 node-red

---

Практика: предотвращение и разрыв циклов

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

1. Архитектурный подход: разделение топиков

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

Топик для команд (записи): `home/livingroom/light/set`
Топик для состояния (чтения): `home/livingroom/light/state`

Поток управления будет выглядеть так:

Управляющий элемент (UI, другой поток): Отправляет `ON` или `OFF` в топик `.../set`.
Поток-исполнитель: Подписан на `.../set`. Получив команду, он выполняет действие (например, через Modbus) и отправляет подтверждение о новом статусе в топик `.../state`.
Поток-отображения (UI): Подписан на `.../state` и обновляет свой интерфейс.

В такой схеме `MQTT In` и `MQTT Out` в одном потоке слушают и пишут в разные топики, что делает цикл невозможным.

2. Использование ноды `RBE` (Report by Exception)

Нода `rbe` (часто устанавливается как `node-red-contrib-rbe`) пропускает сообщение только в том случае, если его `payload` отличается от предыдущего. Это идеальный инструмент для разрыва циклов.

Схема: `[MQTT In]` -> `(RBE)` -> `[Logic]` -> `[MQTT Out]`

В этом случае, даже если `MQTT Out` отправит сообщение в тот же топик, на который подписан `MQTT In`, нода `RBE` заблокирует второе и последующие сообщения, так как их `payload` будет идентичен первому. Это простое и эффективное решение для многих сценариев.

3. Паттерн «Семафор» (Gate)

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

В начале потока ставится нода `Switch`, которая проверяет флаг в контексте, например `flow.gate_is_open == true`.

Если "ворота открыты", `msg` проходит. Сразу после этого нода `Change` устанавливает `flow.gate_is_open = false`.

В самом конце потока (после всех действий) другая нода `Change` снова устанавливает `flow.gate_is_open = true`. Можно добавить небольшую задержку с помощью ноды `Trigger` перед открытием "ворот", чтобы гарантировать завершение всех процессов.

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

---

Итоги и чек-лист для самопроверки

Мы рассмотрели три наиболее опасные и распространенные ошибки в Node-RED, которые могут привести к серьезным сбоям в работе системы автоматизации. Понимание их природы и методов предотвращения — это не просто навык отладки, а основа профессионального подхода к проектированию потоков. Потеря `msg` ведет к неисполнению логики, несоответствие типов данных — к неверным решениям, а бесконечные циклы — к полному отказу контроллера.

Перед тем, как активировать любой новый или измененный поток на реальном объекте, пройдитесь по этому короткому чек-листу. Он поможет вам избежать 90% типовых проблем.

Чек-лист для самопроверки потока

✅ Трассировка `msg`:

* Я проследил все возможные пути выполнения потока?

* У каждой ноды `Function` есть `return msg` или `node.send(msg)` для каждой логической ветки?

* Моя нода `Switch` имеет ветку `otherwise` (иначе) для обработки непредусмотренных значений, или я уверен, что `msg` должен быть отброшен?

✅ Проверка типов данных:

* Я добавил ноды `Change` (с JSONata) или `Function` (с `parseInt`/`parseFloat`) для явного преобразования типов данных, приходящих из внешних систем (MQTT, HTTP, UI)?

* Я проверяю, что преобразование прошло успешно, и обрабатываю случаи, когда данные некорректны (например, c помощью `isNaN`)?

✅ Анализ циклов:

* Использую ли я архитектуру с разделением топиков на `/set` и `/state`?

* Если нет, добавил ли я ноду `RBE` после `MQTT In` для блокировки дублирующихся сообщений?

* Исключена ли любая возможность того, что выход ноды может прямо или косвенно отправить сообщение на ее же вход, вызвав петлю?

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

Что дальше

В следующем уроке мы перейдем к более сложным сценариям и разберем, как создавать свои собственные, переиспользуемые ноды-субпотоки (subflows) для инкапсуляции типовой логики, такой как обработка ошибок, валидация и взаимодействие с устройствами. Это позволит поднять ваши проекты на новый уровень стандартизации и упростит поддержку сложных систем.