node를 빌드할 때 정의된 코드 표준을 따르면 코드가 더 읽기 쉽고 유지 관리 가능해지며 오류를 방지하는 데 도움이 됩니다. 이 문서는 node 빌드를 위한 좋은 코드 관행에 대한 안내를 제공합니다. 코드 세부 사항에 초점을 맞춥니다. UI 표준 및 UX 안내는 node UI 디자인을 참고하세요.

린터 사용#

n8n node 린터는 node 빌드 표준의 많은 부분을 자동으로 확인합니다. 게시하기 전에 node가 린터 검사를 통과하는지 확인해야 합니다. 자세한 내용은 n8n node 린터 문서를 참고하세요.

n8n-node 도구 사용#

n8n은 node를 빌드하고 테스트하기 위해 n8n-node CLI 도구를 사용하는 것을 권장합니다. 특히 검증을 위해 node를 제출할 계획이라면 중요합니다. 이것은 node가 올바른 구조를 갖추고 커뮤니티 node 요건을 따르도록 보장합니다. 또한 린팅과 테스트를 단순화합니다.

TypeScript로 작성#

모든 n8n 코드는 TypeScript입니다. TypeScript로 node를 작성하면 개발 속도를 높이고 버그를 줄일 수 있습니다.

node 작성을 위한 상세 가이드라인#

이 가이드라인은 빌드하는 모든 node에 적용됩니다.

리소스와 작업#

node가 여러 작업을 수행할 수 있는 경우, 작업을 설정하는 파라미터를 Operation으로 부릅니다. node가 하나 이상의 리소스에서 이러한 작업을 수행할 수 있는 경우, 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: 'Create an instance of Resource One'
                    }
                ]
            }
        ]
    }
}

내부 파라미터 이름 재사용#

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

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

내부 이름을 재사용할 때는 한 번에 하나의 필드만 사용자에게 표시되도록 해야 합니다. displayOptions를 사용하여 이를 제어할 수 있습니다.

프로그래매틱 스타일 node 작성을 위한 상세 가이드라인#

이 가이드라인은 프로그래매틱 node 빌드 스타일을 사용하여 node를 빌드할 때 적용됩니다. 선언형 스타일을 사용할 때는 해당되지 않습니다. 다양한 node 빌드 스타일에 대한 자세한 내용은 node 빌드 접근 방식 선택을 참고하세요.

들어오는 데이터 변경 금지#

모든 node가 공유하므로 node가 수신하는 들어오는 데이터(this.getInputData()로 접근 가능)를 절대 변경하지 마세요. 데이터를 추가, 변경 또는 삭제해야 하는 경우 들어오는 데이터를 복제하고 새 데이터를 반환합니다. 이렇게 하지 않으면 현재 node 이후에 실행되는 형제 node가 변경된 데이터에서 작동하여 잘못된 데이터를 처리합니다.

항상 모든 데이터를 복제할 필요는 없습니다. 예를 들어, node가 바이너리 데이터는 변경하지만 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 헬퍼를 참고하세요.