노드를 빌드할 때 정의된 코드 표준을 따르면 코드를 더 읽기 쉽고 유지 관리하기 쉽게 만들 수 있으며, 오류를 방지하는 데 도움이 됩니다. 이 문서는 노드 빌드를 위한 좋은 코드 관행에 대한 가이드를 제공합니다. 코드 세부 사항에 중점을 둡니다. UI 표준 및 UX 가이드에 대해서는 노드 UI 디자인을 참고하세요.

린터 사용#

n8n 노드 린터는 많은 노드 빌드 표준에 대한 자동 검사를 제공합니다. 노드를 게시하기 전에 린터의 검사를 통과하는지 확인해야 합니다. 자세한 내용은 n8n 노드 린터 문서를 참고하세요.

n8n-node 도구 사용#

n8n은 노드를 빌드하고 테스트하는 데 n8n-node CLI 도구를 사용할 것을 권장합니다. 특히 노드를 검증용으로 제출할 계획이라면 이는 중요합니다. 이렇게 하면 노드가 올바른 구조를 가지고 커뮤니티 노드 요구 사항을 따르도록 보장됩니다. 또한 린팅 및 테스트가 간소화됩니다.

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이 사용자가 입력한 데이터를 유지할 수 있습니다.

예를 들어, 'Order'라는 이름의 리소스를 가진 노드를 빌드한다고 가정해 보겠습니다. 이 리소스에는 Get, Edit, Delete를 포함한 여러 작업이 있습니다. 이러한 각 작업은 지정된 주문에 대해 작업을 수행하기 위해 주문 ID를 사용합니다. 사용자에게 ID 필드를 표시해야 합니다. 이 필드에는 표시 레이블과 내부 이름이 있습니다. 각 리소스의 작업 ID 필드에 동일한 내부 이름(value에 설정됨)을 사용하면, 사용자는 Get 작업이 선택된 상태에서 ID를 입력하고, Edit로 전환해도 이를 잃지 않습니다.

내부 이름을 재사용할 때는 한 번에 하나의 필드만 사용자에게 표시되도록 해야 합니다. 이는 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 헬퍼를 참고하세요.