Skip to content

Flow Dev Guideline

Jump to bottom Edit New page
LEEHYUKJOO edited this page Feb 5, 2019 · 51 revisions

※ This page is for discussing how to make Flow Development Guideline.
※ Please do not edit this page.
※ If you have any opinions or ideas, please share on pull request.
※ If you want to add something new, please write and share it.
※ This discussion will be reflected ideas from users once at the end of February.
※ After reflection, we will review the page and finish this discussion around March 10.

Introduction of this wiki page

In Node-RED, users can create flows easily and ad hoc. However, if you want to create more reusable and readable flows, some tips, practices and know how may be needed. Therefore, we would propose to create a new flow development guideline page to show such knowledge on Node-RED official page. We believe this page is useful for most Node-RED users.

Before adding guideline to the Node-RED official page through a pull request, we would like to discuss contents and where to place it with somebody who are interested in this guideline. This wiki page is for discussing them.

At first, we’d like to show a contents list and where to place it on Node-RED official page. After that, we will write the actual contents and discuss it with Node-RED community because we would reduce unnecessary work.

Comments are very welcome. Let us know them on pull request.

Expecting discussion points

  • Chapter structure
  • It is necessary to think about the chapter structure which it is easy for other community members to append contents later.
  • Whether considering contents are suitable for the Node-RED official page or not
  • Actual contents (after discussion above points)
  • etc.

Table of Contents

Table of contents is shown in below. Overview of each chapter is shown in the next section of this page.
This table will be the base for making sidebar of document page.

Style

Align nodes

As the size of the application increases, the process of flow will become complicated, which decreases readability and understandability. One of the key points to improve readability and understandability is a proper node alignment such that flows of one function are adjacent to each other. This chapter shows effective node alignment.

Naming rule

Name of nodes, tabs and subflow is important for readability and reusability of flows. This chapter presents some effective naming rules of them.

Using proper nodes

Each node can be used flexibly. For example, a function node can cover the same function of Change node, Switch node and so on. However, using a proper specialized node for your objective contributes improving understandability of your flows. This chapter introduces the roles and usage of core nodes such as Change, Switch, Template, Link, HTTP.

Function node and Exec node are useful for JavaScript and other language developers because they can write JavaScript codes and commands directly. However, heavy use of them makes understanding flow difficult for other developers. This chapter describes a caution of these nodes and shows examples of alternative methods against Function node and Exec node.

Changing icon

When the same kind nodes are in the flow (e.g. a case that managing a large number of devices with MQTT nodes), it is difficult to distinguish nodes. But, it can be solved by designating different icons for each node. This chapter introduces the procedure for changing the icon and some Use Cases.

Designing a flow

Development steps

If a project needs complicated logic, it is better to design flow before starting development. After that, you create flows based on the flow design. In this subsection, we show an overview of whole recommended steps of design and development.

  • Design
    • Flow structure
    • Message
  • Implementation

Designing flow structure

As the size of flows in a tab gets larger, it can be difficult to recognize a function of each flow within a tab. To improve reusability of flows, it would be better to decide the responsibility of flows within each tab and the scale of one tab. To do this, it is helpful to sort out what kind of things, people, work, rules are in the target domain of the application, and relationship of them.

Designing messages

There are risks that multiple nodes have dependencies by messages passing the nodes.
For other developers to reuse flows, it is important to design messages so that dependencies get to be relaxed. This chapter proposes a guide about designing message.

We have already written actual contents on here.

Designing key-value structure of msg

msg is a JavaScript object that contains a key-value structure like JSON. While a msg transits across multiple nodes, the nodes use some keys and values of the msg. If two or more nodes of them use the same key for different their own purposes, preparing msg for input of the nodes is so difficult.

Therefore, policies of key-value structure are needed and this subsection describes it as such as followings,

  • Top-level keys of msg are used to control the functionality of node
  • msg.payload is used as input parameters of a process of a node

Keeping properties

In the case of using function node, you can prepare output messages by creating new msg objects. However, the output messages may not have some properties that the input message has. This means that properties that should be kept in your flow has lost. Since this can be a cause of serious bugs, preparing output messages based on an input message is better, instead of creating new msg.

Add tag into msg to distinguish a node that sent the msg

[Tips] If it is needed that a (latter) node executes a different process depending on a (former) node that send msg, former node adds tags describing the former node itself. With the tag, the latter node decide the process to execute.

Using persistent storage outside of Node-RED

If you handle the large amount of data, it is not recommended to set the data into msg since msg can be a cause of a lack of memory. Instead, you had better put the data on a persistent storage that is in outside of Node-RED and use reference to the data for handling the data.

Processing in order of arrival of messages

Since Node-RED (JavaScript) processes asynchronously, a node cannot assume that it executes process for arrival msgs by the order of arrival.

Implementation of flow

Cooperation between flows

One application may be constructed by integration of small flows that provide small functions. Since each small flow may be created by a different team, deciding how to integrate the small flows is important for smooth collaborative development.

Http in/out/request nodes are useful for the integration. However, if you do not want to expose endpoints of small flows, you can make sub flows from the small flows and create an additional flow to integrate sub flows.

Managing environmental variables

Global context can be used as an environmental variable of flow execution. However, if you use the global context in various nodes, identifying dependencies between nodes becomes a hard work, and it can lead to bugs. To minimize the dependence on the global context, it is necessary to make it easier to see where the global context is used.

Flows that can have adverse effects

With Node-RED, even non-programmers can easily enjoy coding. However, Node-RED (as of 0.19.5) does not strict restrictions on creating flows and debugging tools such as a lint, you can easily create dangerous flows that can cause bugs. In particular, it is also possible to lead to resource exhaustion of Node-RED engine.

This chapter shows certain cautions and principles not to create such dangerous flows.

Error Handling

To create reliable flows, error handling is essential. This chapter explains its implementation method and arrangement of error handling flow to easily distinct between nominal flow and anomaly flow.

Improving readability

Comment

  • Comment on tab
  • Comment on flow (Comment node)
  • Comment on subflow
  • Logging strategy

Refactoring

It is better to check and refactor the developed flows before presenting it to other developers. This section shows refactoring points such as followings,

  1. Coding Style
  2. Flow implementation
  3. Readability and reusability

A project with multiple developers

When multiple developers join the development, you may need development standards and environments that can facilitate collaborative development. This chapter describes about them.

System and development environment

The project feature of Node-RED can be linked with Git and you can manage the version of flows. It is recommended to use Git remote repository such as GitLab or GitBucket for sharing flows and projects among members. This chapter describes the development environment using Git.

In detail, we plan to describe followings.

  • Configuration of development environment
  • Procedure of developing
  • Steps of release

Management of flow with git

Responding to strict non-functional requirements

Node-RED does not strongly focus on applications with strict non-functional requirements.
However, there are cases that it is necessary to satisfy high level non-functional requirements.
This chapter explains techniques and others to satisfy non-functional requirements.

Precautions due to single thread

If a node takes long time for execution, the process of the entire Node-RED instance stops.
Therefore, it is advisable to outsource the processing with running other services.

Sequential guarantee

Node - RED does not guarantee the arrival order of messages. Therefore, it is better to design related messages in a format expressing the order relation of messages. (Separated message format)

Add a custom footer
Add a custom sidebar
Clone this wiki locally