+
+
Practice
+Guideline for creating clear and reusable flows
+Admin, runtime and storage APIs
+ diff --git a/docs/practice/designing.md b/docs/practice/designing.md new file mode 100644 index 00000000..eb090e51 --- /dev/null +++ b/docs/practice/designing.md @@ -0,0 +1,65 @@ +--- +layout: docs +toc: practice-toc.html +title: 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 through 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](https://github.com/node-red/node-red.github.io/wiki/Flow-Guideline-Contents).* + +#### 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 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 exhaust available memory. Instead, you had better put the data on a persistent storage that is outside of Node-RED and use reference to the data for handling the data.* + +#### Processing messages in order of their arrival + +*Since Node-RED (JavaScript) processes asynchronously, a node cannot assume that it executes process for arrival `msgs` by the order of arrival.* + + \ No newline at end of file diff --git a/docs/practice/implementation.md b/docs/practice/implementation.md new file mode 100644 index 00000000..92dbf704 --- /dev/null +++ b/docs/practice/implementation.md @@ -0,0 +1,25 @@ +--- +layout: docs +toc: practice-toc.html +title: 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 flow parameter + +*Global context can be used as a parameter 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 place strict restrictions on creating flows and does not provide debugging tools such as a lint. Thus, you can easily create dangerous flows that can cause bugs. In particular, it is also possible to lead to resource exhaust of Node-RED engine.* + +*This chapter shows certain cautions and principles preventing from creating 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.* \ No newline at end of file diff --git a/docs/practice/index.md b/docs/practice/index.md new file mode 100644 index 00000000..891f3562 --- /dev/null +++ b/docs/practice/index.md @@ -0,0 +1,12 @@ +--- +layout: docs +toc: practice-toc.html +title: Introduction +--- +*This guide is for developers who understand the basic fuctinality and want to develop more clear and reusable flows. If you think that you are beginner, please read **[User Guide](https://nodered.org/docs/user-guide/)** and **[Cookbook](https://cookbook.nodered.org/)** first.* + +*In Node-RED, users can create flows easily and in ad hoc manner. However, if you want to create more reusable and readable flows, some tips, practices and know how may be needed. Therefore, flow development guideline page is intended for gathering such knowledge. 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.* \ No newline at end of file diff --git a/docs/practice/multiple-developers.md b/docs/practice/multiple-developers.md new file mode 100644 index 00000000..35918ddb --- /dev/null +++ b/docs/practice/multiple-developers.md @@ -0,0 +1,19 @@ +--- +layout: docs +toc: practice-toc.html +title: 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 \ No newline at end of file diff --git a/docs/practice/non-functional.md b/docs/practice/non-functional.md new file mode 100644 index 00000000..db3491cd --- /dev/null +++ b/docs/practice/non-functional.md @@ -0,0 +1,37 @@ +--- +layout: docs +toc: practice-toc.html +title: 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)* + + \ No newline at end of file diff --git a/docs/practice/readability.md b/docs/practice/readability.md new file mode 100644 index 00000000..b3ad2cd3 --- /dev/null +++ b/docs/practice/readability.md @@ -0,0 +1,41 @@ +--- +layout: docs +toc: practice-toc.html +title: Improving readability +--- +### 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**.* + +*The **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 of 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.* + +#### Link node + +*You can divide the flows when it become too long by using Link node. And it allows you to create flows accroding to the size of the display and makes the layout clean.* + +### 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.* + +### 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* \ No newline at end of file diff --git a/images/guide-practice.png b/images/guide-practice.png new file mode 100644 index 00000000..670b290b Binary files /dev/null and b/images/guide-practice.png differ