代码规范#

在构建节点时遵循既定的代码规范，可使代码更具可读性和可维护性，并有助于避免错误。本文档为节点构建提供了良好的代码实践指导，主要聚焦于代码细节。关于界面标准和用户体验指南，请参阅节点界面设计。

使用代码检查工具#

n8n节点代码检查工具可自动校验多项节点构建规范。在发布节点前，应确保代码通过该检查工具的检测。更多信息请参阅n8n节点代码检查工具文档。

使用入门模板#

n8n节点入门项目包含推荐配置、依赖项（含代码检查工具）及示例代码，可帮助您快速上手。请基于该入门模板启动新项目。

采用TypeScript编写#

所有n8n代码均使用TypeScript。使用TypeScript开发节点能提升开发效率并减少程序错误。

节点编写详细指南#

以下指南适用于所有节点开发。

资源与操作#

若节点支持多项操作，应将设置操作的参数命名为Operation。若节点可对多个资源执行这些操作，需创建Resource参数。以下代码示例展示了基础的资源与操作配置：

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'
                    }
                ]
            }
        ]
    }
}

重用内部参数名称#

n8n节点中的所有资源和操作字段均包含两项设置：通过name参数设置的显示名称，以及通过value参数设置的内部名称。为字段重用内部名称可使用户切换操作时，n8n能保留用户已输入的数据。

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

重用内部名称时，必须确保同一时间仅有一个字段对用户可见。您可通过displayOptions控制此行为。

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

本指南适用于使用程序化节点构建风格开发节点的情况，不适用于声明式风格。关于不同节点构建风格的更多信息，请参阅选择节点构建方法。

禁止修改输入数据#

绝对不要修改节点接收的输入数据（可通过this.getInputData()访问的数据），因为所有节点共享这些数据。如需添加、修改或删除数据，请克隆输入数据后返回新数据。若不遵循此规则，在当前节点之后执行的同级节点将基于被篡改的数据运行，导致处理错误数据。

无需始终克隆所有数据。例如，若节点仅修改二进制数据而不变更JSON数据，可创建重用JSON项引用的新数据项。

使用内置请求库#

部分第三方服务在npm上提供专属库以简化集成，但此类包会引入额外依赖（包括依赖包的依赖链）。这将持续增加代码量，导致加载负担加重，并可能引发安全漏洞和程序缺陷等问题。请改用内置模块：

// 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.helpers.request 的迁移说明，请参阅 HTTP 助手。