Node-RED:Создание нод/Создание первой ноды

Материал из Онлайн справочника
Перейти к навигацииПерейти к поиску

Перевод: Максим Кузьмин
Проверка/Оформление/Редактирование: Мякишев Е.А.


Черновик


Создание первой ноды[1]

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

Ноды состоят, как правило, из пары файлов: JavaScript-файла, который задает, что делает нода, и HTML-файла, который задает свойства ноды, меню настроек и текст справки.

Файл «package.json» используется, чтобы упаковать это все вместе в виде npm-модуля.

Создание простой ноды

Ниже мы покажем, как создать ноду, которая будет конвертировать значение, хранящееся в свойстве «payload» сообщения, в значение, где все символы – это символы нижнего регистра.

Убедитесь, что в вашей системе установлена рекомендуемая LTS-версия Node.js. На момент написания этой статьи это LTS 8.x, куда входит npm версии 5.x.

Создайте папку, куда вы будете сохранять свой код. Внутри этой директории создайте 3 файла:

  • package.json
  • lower-case.js
  • lower-case.html

Файл «package.json»

Это стандартный файл, используемый модулями Node.js для описания своего содержимого.

Чтобы сгенерировать стандартный файл «package.json», можно воспользоваться командой «npm init». Она задаст вам несколько вопросов, чтобы помочь создать начальное содержимое этого файла при помощи, где возможно, разумных умолчаний. Когда вас попросят, задайте название «node-red-contrib-example-lower-case».

Когда файл будет сгенерирован, вам нужно будет добавить в него секцию «node-red».

{
    "name" : "node-red-contrib-example-lower-case",
    ...
    "node-red" : {
        "nodes": {
            "lower-case": "lower-case.js"
        }
    }
}

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

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

Примечание: Пожалуйста, не публикуйте эту тестовую ноду в npm!


Файл «lower-case.js»

module.exports = function(RED) {
    function LowerCaseNode(config) {
        RED.nodes.createNode(this,config);
        var node = this;
        node.on('input', function(msg) {
            msg.payload = msg.payload.toLowerCase();
            node.send(msg);
        });
    }
    RED.nodes.registerType("lower-case",LowerCaseNode);
}

Эта нода имеет обертку модуля Node.js. Модуль экспортирует функцию, которая вызывается, когда среда выполнения, запускаясь, будет загружать и саму ноду. Функция вызывается только с одним аргументом – «RED» – который дает модулю доступ к API среды выполнения Node-RED.

Сама нода определена как функция LowerCaseNode(), которая вызывается при создании любого нового экземпляра ноды. Ей передается объект, в котором содержатся свойства тестовой ноды, заданные в редакторе потока.

Эта функция, в свою очередь, вызывает функцию RED.nodes.createNode(), чтобы инициализировать функционал, используемый вообще всеми нодами. После этого идет код, отвечающий за работу самой ноды. В данном случае нода регистрирует прослушивателя для события «input», которое происходит каждый раз, когда в ноду приходит новое сообщение. Затем внутри этого прослушивателя все символы в «payload» конвертируются в символы нижнего регистра, после чего вызывается функция send(), отправляющая преобразованное сообщение дальше в поток.

Наконец, функция LowerCaseNode() регистрируется в среде выполнения при помощи названия ноды – «lower-case».

Если у ноды есть зависимости от внешних модулей, они должны быть вписаны в раздел «dependencies» файла «package.json».

Более подробно о той части ноды, что связана со средой выполнения, читайте тут.

Файл «lower-case.html»

<script type="text/javascript">
    RED.nodes.registerType('lower-case',{
        category: 'function',
        color: '#a6bbcf',
        defaults: {
            name: {value:""}
        },
        inputs:1,
        outputs:1,
        icon: "file.png",
        label: function() {
            return this.name||"lower-case";
        }
    });
</script>

<script type="text/x-red" data-template-name="lower-case">
    <div class="form-row">
        <label for="node-input-name"><i class="icon-tag"></i> Name</label>
        <input type="text" id="node-input-name" placeholder="Name">
    </div>
</script>

<script type="text/x-red" data-help-name="lower-case">
    <p>A simple node that converts the message payloads into all lower-case characters</p>
    <!- Простая нода, конвертирующая символы из свойства «payload» в символы нижнего регистра -->
</script>

В HTML-файле ноды содержится следующая информация:

  • Вся информация о ноде, необходимая редактору (объект с ее свойствами)
  • Меню редактирования ноды
  • Справочная информация о ноде

У нашей ноды только одно редактируемое свойство – «name». Оно необязательное, но среди разработчиков бытует договоренность использовать это свойство для того, чтобы различать между собой разные экземпляры одной ноды, находящиеся в одном потоке.

Более подробно о той части ноды, что связана с редактором, читайте тут.

Проверка ноды в Node-RED

Теперь, когда мы создали этот простой нодовый модуль (согласно инструкциям выше), мы можем установить его в среду выполнения Node-RED.

Чтобы протестировать нодовый модуль локально при помощи npm 5.x, нужно воспользоваться командой «npm install <папка>». Это позволит вам разрабатывать ноду в папке на локальной машине, а также во время разработки связать ее с локальной версией Node-RED.

В своей пользовательской директории Node-RED (как правило, это «~/.node-red») запустите:

npm install <путь_к_модулю_ноды>

К примеру, если у вас Mac OS или Linux и если ваша нода расположена в «~/dev/node-red-contrib-example-lower-case», вам нужно будет вписать следующее:

cd ~/.node-red
npm install ~/dev/node-red-contrib-example-lower-case

Это создаст символическую ссылку к папке, где хранится ваш нодовый модуль (в «~/.node-red/node_modules»), чтобы Node-RED при запуске мог найти эту ноду. Все изменения в файле ноды можно задействовать, просто перезапустив Node-RED. Если у вас Windows, то, опять же, необходимо использовать npm 5.x или новее:

cd C:\Users\my_name\.node_red
npm install C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case

Если вы используете старую версию npm, то можете вручную создать символическую ссылку на свой проект. К примеру, на системах с Mac или Linux это делается так:

cd ~/.node-red/node_modules
ln -s ~/dev/node-red-contrib-example-lower-case

На Windows со старой версией npm воспользуйтесь «mklink»:

cd C:\Users\my_name\.node_red
mklink /D node_modules\node-red-contrib-example-lower-case C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case


Примечание: npm 5 добавит ваш модуль в качестве зависимости в файл «package.json», находящийся в вашей пользовательской директории. Если вы хотите это предотвратить, воспользуйтесь в npm опцией «--no-save».


Модульное тестирование

Чтобы воспользоваться модульным тестированием, вам понадобится npm-модуль «node-red-node-test-helper». Это фреймворк, построенный на базе среды выполнения Node-RED с целью упростить тестирование нод.

При помощи этого фреймворка можно создавать тестовые потоки, а затем проверять, работают ли как следует свойства ноды и получаются ли выходные данные такими, как нужно. К примеру, чтобы модульно протестировать свою ноду «lower-case», вы можете создать в пакете своего нодового модуля папку «test», а внутри нее – файл «_spec.js».

Файл «test/_spec.js»

var should = require("should");
var helper = require("node-red-test-helper");
var lowerNode = require("../lower-case.js");

describe('lower-case Node', function () {

  afterEach(function () {
    helper.unload();
  });

  it('should be loaded', function (done) {
    var flow = [{ id: "n1", type: "lower-case", name: "test name" }];
    helper.load(lowerNode, flow, function () {
      var n1 = helper.getNode("n1");
      n1.should.have.property('name', 'test name');
      done();
    });
  });

  it('should make payload lower case', function (done) {
    var flow = [{ id: "n1", type: "lower-case", name: "test name",wires:[["n2"]] },
    { id: "n2", type: "helper" }];
    helper.load(lowerNode, flow, function () {
      var n2 = helper.getNode("n2");
      var n1 = helper.getNode("n1");
      n2.on("input", function (msg) {
        msg.should.have.property('payload', 'uppercase');
        done();
      });
      n1.receive({ payload: "UpperCase" });
    });
  });
});

Эти тесты проверяют, корректно ли нода загружается в среду выполнения, а также, правильно ли она меняет данные в «payload» на символы нижнего регистра.

Оба теста загружают ноду в среду выполнения при помощи helper.load(), которой «скармливается» и сама тестируемая нода, и тестовый поток. В первом тесте проверяется, обладает ли эта нода, находящаяся в среде выполнения, корректным свойством «name». Во втором тесте проверяется, являются ли выходные символы ноды символами нижнего регистра.

Модуль «node-red-node-test-helper» содержит несколько примеров тестов, взятых из базовых нод Node-RED. Более подробно об этом модуле читайте в его README-файле.

См.также

Внешние ссылки