代码规范

在构建节点时遵循既定的代码规范可以使您的代码更具可读性和可维护性，并有助于避免错误。本文档提供了节点开发的代码最佳实践指南，主要关注代码细节。关于 UI 标准和用户体验指南，请参阅节点 UI 设计。

使用代码检查工具

n8n 节点代码检查工具(n8n node linter)提供了对许多节点构建标准的自动检查。在发布节点前，您应确保代码通过检查工具的验证。更多信息请参考n8n 节点代码检查工具文档。

使用起始模板

n8n 节点起始项目(n8n node starter)包含推荐的配置、依赖项(包括代码检查工具)和示例代码，可帮助您快速开始开发。请使用起始模板开始新项目。

使用 TypeScript 编写

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

节点编写的详细指南

以下指南适用于您构建的任何节点。

资源与操作

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

export const ExampleNode implements INodeType {
    description: {
        displayName: '示例节点',
        ...
        properties: [
            {
                displayName: '资源',
                name: 'resource',
                type: 'options',
                options: [
                    {
                        name: '资源一',
                        value: 'resourceOne'
                    },
                    {
                        name: '资源二',
                        value: 'resourceTwo'
                    }
                ],
                default: 'resourceOne'
            },
            {
                displayName: '操作',
                name: 'operation',
                type: 'options',
                // 仅对资源一显示这些操作
                displayOptions: {
                    show: {
                        resource: [
                            'resourceOne'
                        ]
                    }
                },
                options: [
                    {
                        name: '创建',
                        value: 'create',
                        description: '创建资源一的实例'
                    }
                ]
            }
        ]
    }
}

重用内部参数名称

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

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

重用内部名称时，必须确保同一时间只有一个字段对用户可见。您可以使用 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。

更多信息请参考 HTTP 辅助工具，以及已移除的 this.helpers.request 的迁移指南。