TypeScript에서 Lambda 함수 핸들러 정의 - AWS Lambda
비동기/대기 사용콜백 사용이벤트 객체에 대한 유형의 사용

TypeScript에서 Lambda 함수 핸들러 정의

Lambda 함수의 핸들러는 이벤트를 처리하는 함수 코드의 메서드입니다. 함수가 호출되면 Lambda는 핸들러 메서드를 실행합니다. 함수는 핸들러가 응답을 반환하거나 종료하거나 제한 시간이 초과될 때까지 실행됩니다.

예 TypeScript 핸들러

다음 예제 함수는 이벤트 객체의 내용을 로깅하고 로그의 위치를 반환합니다. 유의할 사항:

  • Lambda 함수에서 이 코드를 사용하기 전에 @types/aws-lambda 패키지를 개발 종속 항목으로 추가해야 합니다. 이 패키지에는 Lambda에 대한 유형 정의가 들어 있습니다. @types/aws-lambda가 설치되면 import 문(import ... from 'aws-lambda')이 유형 정의를 가져옵니다. 관련 없는 타사 도구인 aws-lambda NPM 패키지는 가져오지 않습니다. 자세한 내용은 DefinitelyTyped GitHub 리포지토리의 aws-lambda를 참조하세요.

  • 이 예제의 핸들러는 ES 모듈이며 package.json 파일에서 또는 ..mjs 파일 확장명을 사용하여 지정해야 합니다. 자세한 내용은 함수 핸들러를 ES 모듈로 지정을 참조하십시오.

import { Handler } from 'aws-lambda';

export const handler: Handler = async (event, context) => {
    console.log('EVENT: \n' + JSON.stringify(event, null, 2));
    return context.logStreamName;
};

런타임은 인수를 핸들러 메서드에 전달합니다. 첫 번째 인수는 호출자로부터의 정보가 포함된 event 객체입니다. 이 정보는 Invoke를 호출할 때 호출자가 JSON 형식 문자열로 전달하고, 런타임은 이 졍보를 객체로 변환합니다. AWS 서비스가 함수를 호출할 때, 이벤트 구조는 서비스별로 다릅니다. TypeScript에서는 이벤트 객체에 유형 주석을 사용하는 것이 좋습니다. 자세한 내용은 이벤트 객체에 대한 유형의 사용 단원을 참조하십시오.

두 번째 인수는 컨텍스트 객체이며, 여기에는 호출, 함수 및 실행 환경에 대한 정보가 포함되어 있습니다. 이전 예제에서는, 함수가 컨텍스트 객체로부터 로그 스트림의 이름을 가져와서 호출자에게 반환합니다.

응답을 전송하기 위해 비동기 핸들러에서 호출할 수 있는 함수인 콜백 인수를 사용할 수도 있습니다. 콜백 대신 비동기/대기를 사용하는 것이 좋습니다. 비동기/대기는 향상된 가독성, 오류 처리 및 효율성을 제공합니다. 비동기/대기 및 콜백 간의 차이에 대한 더 자세한 내용은 콜백 사용을 참조하십시오.

비동기/대기 사용

비동기식 작업을 수행하는 코드의 경우, 동기/대기 패턴을 사용하여 핸들러 실행을 완료하세요. 비동기/대기는 중첩된 콜백이나 체인 프라미스 없이 Node.js 내에서 비동기 코드를 작성할 수 있는 간결하고 읽기 쉬운 방법입니다. 비동기/대기를 사용하면 비동기 및 비차단 상태를 유지하면서 동기 코드처럼 읽는 코드를 작성할 수 있습니다.

async 키워드는 함수를 비동기로 표시하고 await 키워드는 Promise이 해결될 때까지 함수 실행을 일시 중지합니다.

예 TypeScript 함수 - 비동기

이 예제에서는 nodejs18.x 런타임에서 사용할 수 있는 fetch를 사용합니다. 유의할 사항:

  • Lambda 함수에서 이 코드를 사용하기 전에 @types/aws-lambda 패키지를 개발 종속 항목으로 추가해야 합니다. 이 패키지에는 Lambda에 대한 유형 정의가 들어 있습니다. @types/aws-lambda가 설치되면 import 문(import ... from 'aws-lambda')이 유형 정의를 가져옵니다. 관련 없는 타사 도구인 aws-lambda NPM 패키지는 가져오지 않습니다. 자세한 내용은 DefinitelyTyped GitHub 리포지토리의 aws-lambda를 참조하세요.

  • 이 예제의 핸들러는 ES 모듈이며 package.json 파일에서 또는 ..mjs 파일 확장명을 사용하여 지정해야 합니다. 자세한 내용은 함수 핸들러를 ES 모듈로 지정을 참조하십시오.

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
const url = 'https://aws.amazon.com/';
export const lambdaHandler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
    try {
        // fetch is available with Node.js 18
        const res = await fetch(url);
        return {
            statusCode: res.status,
            body: JSON.stringify({
                message: await res.text(),
            }),
        };
    } catch (err) {
        console.log(err);
        return {
            statusCode: 500,
            body: JSON.stringify({
                message: 'some error happened',
            }),
        };
    }
};

콜백 사용

콜백을 사용하는 대신 비동기/대기를 사용하여 함수 핸들러를 선언하는 것이 좋습니다. 비동기/대기는 다음과 같은 여러 가지 이유로 더 나은 선택입니다.

  • 가독성: 비동기/대기 코드는 콜백 코드보다 읽기 쉽고 이해하기 쉬우므로 따르기가 금방 어려워지고 콜백 문제가 발생할 수 있습니다.

  • 디버깅 및 오류 처리: 콜백 기반 코드를 디버깅하는 것은 어려울 수 있습니다. 콜 스택은 추적하기 어려워지고 오류는 쉽게 삼킬 수 있습니다. 비동기/대기를 사용하면 try/catch 블록을 사용하여 오류를 처리할 수 있습니다.

  • 효율성: 콜백은 종종 코드의 다른 부분을 전환해야 합니다. 비동기/대기는 컨텍스트 전환 수를 줄여 코드 효율성을 높일 수 있습니다.

핸들러에서 콜백을 사용하는 경우, 이벤트 루프가 비어 있거나 함수 제한 시간을 초과할 때까지 함수가 계속 실행됩니다. 응답은 모든 이벤트 루프 작업이 완료될 때까지 호출자에게 전송되지 않습니다. 함수 제한 시간을 초과하면, 대신 오류가 반환됩니다. context.callbackWaitsForEmptyEventLoop를 false로 설정하여 즉시 응답을 전송하도록 런타임을 구성할 수 있습니다.

콜백 함수는 두 개의 인수, Error 및 응답을 사용합니다. 응답 객체는 JSON.stringify와 호환되어야 합니다.

예 콜백이 있는 TypeScript 함수

이 샘플 함수는 Amazon API Gateway에서 이벤트를 수신하고 이벤트 및 컨텍스트 객체를 로깅한 다음 API Gateway에 응답을 반환합니다. 유의할 사항:

  • Lambda 함수에서 이 코드를 사용하기 전에 @types/aws-lambda 패키지를 개발 종속 항목으로 추가해야 합니다. 이 패키지에는 Lambda에 대한 유형 정의가 들어 있습니다. @types/aws-lambda가 설치되면 import 문(import ... from 'aws-lambda')이 유형 정의를 가져옵니다. 관련 없는 타사 도구인 aws-lambda NPM 패키지는 가져오지 않습니다. 자세한 내용은 DefinitelyTyped GitHub 리포지토리의 aws-lambda를 참조하세요.

  • 이 예제의 핸들러는 ES 모듈이며 package.json 파일에서 또는 ..mjs 파일 확장명을 사용하여 지정해야 합니다. 자세한 내용은 함수 핸들러를 ES 모듈로 지정을 참조하십시오.

import { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';

export const lambdaHandler = (event: APIGatewayEvent, context: Context, callback: APIGatewayProxyCallback): void => {
    console.log(`Event: ${JSON.stringify(event, null, 2)}`);
    console.log(`Context: ${JSON.stringify(context, null, 2)}`);
    callback(null, {
        statusCode: 200,
        body: JSON.stringify({
            message: 'hello world',
        }),
    });
};

이벤트 객체에 대한 유형의 사용

유형을 확인할 수 있는 기능을 잃게 되므로 핸들러 인수 및 반환 유형에 대해 any 유형을 사용하지 않는 것이 좋습니다. 대신 sam local generate-event AWS Serverless Application Model CLI 명령을 사용하여 이벤트를 생성하거나 @types/aws-lambda 패키지에서 제공되는 오픈 소스 정의를 사용합니다.

sam local generate-event 명령을 사용하여 이벤트 생성

  1. Amazon Simple Storage Service(Amazon S3) 프록시 이벤트를 생성합니다.

    sam local generate-event s3 put >> S3PutEvent.json

  2. quicktype 유틸리티를 사용하여 S3PutEvent.json 파일에서 유형 정의를 생성합니다.

    npm install -g quicktype
quicktype S3PutEvent.json -o S3PutEvent.ts

  3. 생성된 유형을 코드에 사용합니다.

    import { S3PutEvent } from './S3PutEvent';

export const lambdaHandler = async (event: S3PutEvent): Promise<void> => {
  event.Records.map((record) => console.log(record.s3.object.key));
};
@types/aws-lambda 패키지에서 오픈 소스 정의를 사용하여 이벤트 생성

  1. @types/aws-lambda 패키지를 개발 종속성으로 추가합니다.

    npm install -D @types/aws-lambda

  2. 해당 유형을 코드에 사용합니다.

    import { S3Event } from "aws-lambda";

export const lambdaHandler = async (event: S3Event): Promise<void> => {
  event.Records.map((record) => console.log(record.s3.object.key));
};