Skip to content

代码标准(Code standards)#

在构建节点时遵循已定义的代码标准可以使代码更易读、易维护，并有助于避免错误。本文档提供了有关节点构建的良好代码实践的指导，重点关注代码细节。有关界面标准和用户体验指导，请参阅 节点 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.

例如：你正在构建一个名为“Order”的节点资源。该资源有几个操作，包括获取（Get）、编辑（Edit）和删除（Delete）。每个操作都使用订单ID来对指定的订单执行操作。你需要为用户显示一个ID字段。该字段有一个显示标签和一个内部名称。通过在每个资源的操作ID字段中使用相同的内部名称（在 value 中设置），用户可以在选择获取（Get）操作时输入ID，并且在切换到编辑（Edit）操作时不会丢失该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.

请参阅 HTTP 帮助 获取更多信息，以及被移除的 this.helpers.request 的迁移说明。

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