n8n 中文文档

代码标准

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

使用 linter

n8n 节点 linter 提供对许多节点构建标准的自动检查。您应该确保您的节点在发布之前通过 linter 检查。有关更多信息,请参阅 n8n 节点 linter 文档。

使用n8n节点工具

n8n 建议使用 n8n-node CLI 工具 来构建和测试您的节点。特别是,如果您计划提交节点进行验证,这一点尤其重要。这可确保您的节点具有正确的结构并遵循社区节点要求。它还简化了 linting 和测试。

使用声明式样式

请使用声明式样式构建节点。这是默认样式,它通过 routing 键而不是 execute() 方法来描述请求,因此节点代码更简短,也更易于维护。

仅当节点确实需要时才使用编程式样式,例如触发器节点、使用非 REST API 的节点、转换传入数据的节点,或需要基于功能的版本控制的节点。声明式节点仍可使用轻量版本控制。有关完整适用场景及两种样式的并列比较,请参阅选择节点构建方式。

用 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',
                // 仅为资源一显示这些操作
                displayOptions: {
                    show: {
                        resource: [
                            'resourceOne'
                        ]
                    }
                },
                options: [
                    {
                        name: 'Create',
                        value: 'create',
                        description: 'Create an instance of Resource One'
                    }
                ]
            }
        ]
    }
}

重用内部参数名称

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

例如:您正在构建一个名为 'Order' 的资源节点。此资源有几个操作,包括 Get、Edit 和 Delete。每个操作都使用订单 ID 对指定订单执行操作。您需要为用户显示一个 ID 字段。此字段有一个显示标签和一个内部名称。通过对每个资源上的操作 ID 字段使用相同的内部名称(在 value 中设置),用户可以在选择 Get 操作时输入 ID,如果切换到 Edit 也不会丢失它。

重用内部名称时,您必须确保用户一次只能看到一个字段。您可以使用 displayOptions 控制这一点。

编写编程式节点 的详细指南

这些准则适用于使用编程节点构建方式构建节点时。使用声明式风格时它们不相关。有关不同节点构建风格的更多信息,请参阅选择节点构建方法。

不要更改传入数据

永远不要更改节点接收的传入数据(可通过 this.getInputData() 访问的数据),因为所有节点都共享它。如果您需要添加、更改或删除数据,请克隆传入数据并返回新数据。如果您不这样做,在当前节点之后执行的兄弟节点将对更改的数据进行操作并处理不正确的数据。

并不总是需要克隆所有数据。例如,如果节点更改二进制数据但不更改 JSON 数据,您可以创建一个重用对 JSON 项目引用的新项目。

使用内置请求库

一些第三方服务在 npm 上有自己的库,这使得创建集成变得更加容易。这些包的问题是你添加了另一个依赖项(加上依赖项的所有依赖项)。这会增加越来越多的代码,这些代码必须加载,可能会引入安全漏洞、错误等。相反,使用内置模块:

// 如果不需要身份验证
const response = await this.helpers.httpRequest(options);

// 如果需要身份验证
const response = await this.helpers.httpRequestWithAuthentication.call(
    this,
    'credentialTypeName', // 例如:pipedriveApi
    options,
);

这使用 npm 包 Axios{:target=_blank .external-link}。

请参阅 HTTP 帮助程序 了解更多信息以及已删除的 this.helpers.request 的迁移说明。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。