코드 표준

노드를 구축할 때 정의된 코드 표준을 따르는 것은 코드의 가독성과 유지보수성을 높이며 오류를 예방하는 데 도움이 됩니다. 이 문서는 노드 구축을 위한 좋은 코드 관행에 대한 안내를 제공합니다. 코드 세부 사항에 초점을 맞추고 있습니다. UI 표준 및 UX 가이드는 Node UI design를 참조하십시오.

린터 사용하기

n8n 노드 린터는 많은 노드 구축 표준에 대한 자동 검사를 제공합니다. 노드를 게시하기 전에 린터의 검사를 통과해야 합니다. 더 많은 정보는 n8n node linter 문서를 참조하십시오.

스타터 사용하기

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',
                // Resource One에 대해서만 이러한 작업을 표시합니다.
                displayOptions: {
                    show: {
                        resource: [
                            'resourceOne'
                        ]
                    }
                },
                options: [
                    {
                        name: 'Create',
                        value: 'create',
                        description: 'Resource One의 인스턴스 생성'
                    }
                ]
            }
        ]
    }
}

내부 매개변수 이름 재사용

모든 n8n 노드의 리소스 및 작업 필드는 두 가지 설정이 있습니다: name 매개변수를 사용하여 설정된 표시 이름과 value 매개변수를 사용하여 설정된 내부 이름입니다. 필드에 대한 내부 이름을 재사용하면 사용자가 작업을 전환할 때 n8n이 사용자 입력 데이터를 보존할 수 있습니다.

예를 들어: 'Order'라는 리소스를 가진 노드를 구축하고 있다고 가정할 때, 이 리소스는 Get, Edit, Delete를 포함한 여러 작업을 제공합니다. 이러한 각 작업은 지정된 주문에서 작업을 수행하기 위해 주문 ID를 사용합니다. 사용자를 위해 ID 필드를 표시해야 합니다. 이 필드는 표시 레이블과 내부 이름을 가집니다. 각 리소스의 작업 ID 필드에 대해 동일한 내부 이름(value에 설정됨)을 사용하여 사용자가 Get 작업을 선택한 상태에서 ID를 입력하고 Edit로 전환해도 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을 사용합니다.

더 많은 정보와 제거된 this.helpers.request에 대한 마이그레이션 지침은 HTTP 헬퍼를 참조하세요.