Skip to content

代码标准#

¥Code standards

在构建节点时遵循已定义的代码标准，可以使代码更易读、更易维护，并有助于避免错误。本文档提供了关于节点构建良好代码实践的指南。它专注于代码细节。有关 UI 标准和 UX 指南，请参阅 Node UI 设计。

¥Following defined code standards when building your node makes your code more readable and maintainable, and helps avoid errors. This document provides guidance on good code practices for node building. It focuses on code details. For UI standards and UX guidance, refer to Node UI design.

使用代码检查器#

¥Use the linter

n8n 节点代码检查器可自动检查许多节点构建标准。你应该确保你的节点在发布之前通过代码检查工具的检查。请参阅 n8n 节点代码检查器 文档，了解更多信息。

¥The n8n node linter provides automatic checking for many of the node-building standards. You should ensure your node passes the linter's checks before publishing it. Refer to the n8n node linter documentation for more information.

使用入门工具#

¥Use the starter

n8n 节点启动项目包含推荐的设置、依赖（包括代码检查器）以及示例，可帮助你快速入门。使用 starter 协议创建新项目。

¥The n8n node starter project includes a recommended setup, dependencies (including the linter), and examples to help you get started. Begin new projects with the starter.

使用 TypeScript 编写代码#

¥Write in TypeScript

所有 n8n 代码均为 TypeScript。使用 TypeScript 编写节点可以加快开发速度并减少错误。

¥All n8n code is TypeScript. Writing your nodes in TypeScript can speed up development and reduce bugs.

编写节点的详细指南#

¥Detailed guidelines for writing a node

这些准则适用于你构建的任何节点。

¥These guidelines apply to any node you build.

资源和操作#

¥Resources and operations

如果你的节点可以执行多个操作，请将设置操作的参数命名为 Operation。如果你的节点可以对多个资源执行这些操作，请创建一个 Resource 参数。以下代码示例展示了基本的资源和操作设置：

¥If your node can perform several operations, call the parameter that sets the operation Operation. If your node can do these operations on more than one resource, create a Resource parameter. The following code sample shows a basic resource and operations setup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
export const ExampleNode implements INodeType {
    description: {
        displayName: 'Example Node',
        ...
        properties: [
            {
                displayName: 'Resource',
                name: 'resource',
                type: 'options',
                options: [
                    {
                        name: 'Resource One',
                        value: 'resourceOne'
                    },
                    {
                        name: 'Resource Two',
                        value: 'resourceTwo'
                    }
                ],
                default: 'resourceOne'
            },
            {
                displayName: 'Operation',
                name: 'operation',
                type: 'options',
                // Only show these operations for Resource One
                displayOptions: {
                    show: {
                        resource: [
                            'resourceOne'
                        ]
                    }
                },
                options: [
                    {
                        name: 'Create',
                        value: 'create',
                        description: 'Create an instance of Resource One'
                    }
                ]
            }
        ]
    }
}

重用内部参数名称#

¥Reuse internal parameter names

n8n 节点中的所有资源和操作字段均有两个设置：使用 name 参数设置的显示名称和使用 value 参数设置的内部名称。重用字段的内部名称可以让 n8n 在用户切换操作时保留用户输入的数据。

¥All resource and operation fields in an n8n node have two settings: a display name, set using the name parameter, and an internal name, set using the value parameter. Reusing the internal name for fields allows n8n to preserve user-entered data if a user switches operations.

例如：你正在构建一个包含名为 '排序' 的资源的节点。此资源包含多个操作，例如获取、编辑和删除。每个操作都使用订单 ID 对指定的订单执行操作。你需要显示用户的 ID 字段。此字段包含显示标签和内部名称。通过在每个资源的操作 ID 字段中使用相同的内部名称（在 value 中设置），用户可以在选择“获取”操作时输入 ID，并且在切换到“编辑”操作时不会丢失该 ID。

¥For example: you're building a node with a resource named 'Order'. This resource has several operations, including Get, Edit, and Delete. Each of these operations uses an order ID to perform the operation on the specified order. You need to display an ID field for the user. This field has a display label, and an internal name. By using the same internal name (set in value) for the operation ID field on each resource, a user can enter the ID with the Get operation selected, and not lose it if they switch to Edit.

重用内部名称时，必须确保用户一次只能看到一个字段。你可以使用 displayOptions 控制内存使用情况。

¥When reusing the internal name, you must ensure that only one field is visible to the user at a time. You can control this using displayOptions.

编写程序化风格节点的详细指南#

¥Detailed guidelines for writing a programmatic-style node

这些指南适用于使用程序化节点构建方式构建节点。在使用声明式风格时，这些参数无关紧要。有关不同节点构建方式的更多信息，请参阅 选择你的节点构建方法。

¥These guidelines apply when building nodes using the programmatic node-building style. They aren't relevant when using the declarative style. For more information on different node-building styles, refer to Choose your node building approach.

请勿更改传入数据#

¥Don't change incoming data

切勿更改节点接收的传入数据（可通过 this.getInputData() 访问的数据），因为所有节点共享这些数据。如果你需要添加、更改或删除数据，请克隆传入数据并返回新数据。如果你不进行此操作，则在当前节点之后执行的同级节点将使用已更改的数据，并处理错误数据。

¥Never change the incoming data a node receives (data accessible with this.getInputData()) as all nodes share it. If you need to add, change, or delete data, clone the incoming data and return the new data. If you don't do this, sibling nodes that execute after the current one will operate on the altered data and process incorrect data.

不必总是克隆所有数据。例如，如果节点更改了二进制数据但没有更改 JSON 数据，你可以创建一个新项，该新项重用对 JSON 项的引用。

¥It's not necessary to always clone all the data. For example, if a node changes the binary data but not the JSON data, you can create a new item that reuses the reference to the JSON item.

使用内置请求库#

¥Use the built in request library

某些第三方服务在 npm 上有自己的库，这使得创建集成更加容易。这些包的问题在于，它们会增加一个额外的依赖（以及所有依赖的依赖）。此操作会添加越来越多的代码，这些代码需要加载，可能会引入安全漏洞、错误等。请使用内置模块：

¥Some third-party services have their own libraries on npm, which make it easier to create an integration. The problem with these packages is that you add another dependency (plus all the dependencies of the dependencies). This adds more and more code, which has to be loaded, can introduce security vulnerabilities, bugs, and so on. Instead, use the built-in module:

1
2
3
4
5
6
7
8
9
// If no auth needed
const response = await this.helpers.httpRequest(options);

// If auth needed
const response = await this.helpers.httpRequestWithAuthentication.call(
	this, 
	'credentialTypeName', // For example: pipedriveApi
	options,
);

这使用 npm 包 Axios。

¥This uses the npm package Axios.

有关已移除的 this.helpers.request 的更多信息和迁移说明，请参阅 HTTP 辅助函数。

¥Refer to HTTP helpers for more information, and for migration instructions for the removed this.helpers.request.