콘텐츠로 이동
@aws/nx-plugin
Blog

TypeScript Lambda Function

Filter this guidePick generator option values to hide sections that don't apply.

TypeScript Lambda Function 생성기는 기존 TypeScript 프로젝트에 람다 함수를 추가하는 기능을 제공합니다.

이 생성기는 AWS CDK 또는 Terraform 인프라 설정과 함께 새로운 TypeScript 람다 핸들러를 생성합니다. 생성된 핸들러는 로깅, AWS X-Ray 추적 및 CloudWatch Metrics를 포함한 관찰성을 위해 AWS Lambda Powertools for TypeScript를 사용하며, AWS Lambda Powertools의 Parser를 사용하여 이벤트에 대한 선택적 타입 안전성을 제공합니다.

사용법

섹션 제목: “사용법”

TypeScript 람다 함수 생성

섹션 제목: “TypeScript 람다 함수 생성”

두 가지 방법으로 람다 함수를 생성할 수 있습니다:

Terminal window
pnpm nx g @aws/nx-plugin:ts#lambda-function
어떤 파일이 변경될지 확인하기 위해 드라이 런을 수행할 수도 있습니다
Terminal window
pnpm nx g @aws/nx-plugin:ts#lambda-function --dry-run

옵션

섹션 제목: “옵션”
매개변수타입기본값설명
project 필수string-람다 함수를 추가할 프로젝트
name 필수string-추가할 함수의 이름
functionPath string-함수를 추가할 프로젝트 소스 디렉토리 내의 선택적 하위 디렉토리
event Any | AlbSchema | APIGatewayProxyEventSchema | APIGatewayRequestAuthorizerEventSchema | APIGatewayTokenAuthorizerEventSchema | APIGatewayProxyEventV2Schema | APIGatewayProxyWebsocketEventSchema | APIGatewayRequestAuthorizerEventV2Schema | CloudFormationCustomResourceCreateSchema | CloudFormationCustomResourceUpdateSchema | CloudFormationCustomResourceDeleteSchema | CloudWatchLogsSchema | PreSignupTriggerSchema | PostConfirmationTriggerSchema | CustomMessageTriggerSchema | MigrateUserTriggerSchema | CustomSMSSenderTriggerSchema | CustomEmailSenderTriggerSchema | DefineAuthChallengeTriggerSchema | CreateAuthChallengeTriggerSchema | VerifyAuthChallengeTriggerSchema | PreTokenGenerationTriggerSchemaV1 | PreTokenGenerationTriggerSchemaV2AndV3 | DynamoDBStreamSchema | EventBridgeSchema | KafkaMskEventSchema | KafkaSelfManagedEventSchema | KinesisDataStreamSchema | KinesisFirehoseSchema | KinesisDynamoDBStreamSchema | KinesisFirehoseSqsSchema | LambdaFunctionUrlSchema | S3EventNotificationEventBridgeSchema | S3Schema | S3ObjectLambdaEventSchema | S3SqsEventNotificationSchema | SesSchema | SnsSchema | SqsSchema | TransferFamilySchema | VpcLatticeSchema | VpcLatticeV2SchemaAnyLambda 함수에 사용할 선택적 이벤트 소스 스키마
infra lambda | nonelambdaLambda 함수를 배포할 인프라 유형
iac inherit | cdk | terraforminherit선호하는 IaC 공급자. 기본적으로 초기 선택에서 상속됩니다.
preferInstallDependencies booleantrue생성기 실행 후 의존성 설치를 선호할지 여부입니다. 여러 생성기를 일괄 처리할 때 설치를 연기하려면 false로 설정하세요 (후속 생성기가 Nx 프로젝트 그래프를 계산할 수 있도록 필요한 경우 설치는 여전히 실행됩니다); 마지막에 한 번만 설치합니다.

생성기 출력

섹션 제목: “생성기 출력”

생성기는 프로젝트에 다음 파일을 추가합니다:

  • 디렉터리<project-name>
    • 디렉터리src/
      • <lambda-function>.ts Function implementation

functionPath 옵션이 제공되면, 생성기는 프로젝트 소스 디렉토리 내의 지정된 경로에 핸들러를 추가합니다:

  • 디렉터리<project-name>
    • 디렉터리src/
      • 디렉터리<custom-path>/
        • <function-name>.ts Function implementation

인프라

섹션 제목: “인프라”

이 생성기는 선택한 iac를 기반으로 코드형 인프라를 제공하므로, 관련 CDK constructs 또는 Terraform 모듈을 포함하는 packages/common에 프로젝트를 생성합니다.

공통 코드형 인프라 프로젝트는 다음과 같이 구성됩니다:

  • 디렉터리packages/common/constructs
    • 디렉터리src
      • 디렉터리app/ 프로젝트/생성기에 특정한 인프라를 위한 Constructs
        • …
      • 디렉터리core/ app의 constructs에서 재사용되는 일반 constructs
        • …
      • index.ts app에서 constructs를 내보내는 진입점
    • project.json 프로젝트 빌드 타겟 및 구성

생성기는 선택한 iac에 따라 함수를 배포하기 위한 코드형 인프라를 생성합니다:

생성기는 함수를 배포하는 데 사용할 수 있는 CDK 구성을 생성하며, 이는 packages/common/constructs/src/app/lambda-functions 디렉토리에 위치합니다.

아키텍처

섹션 제목: “아키텍처”

배포된 함수는 다음과 같은 아키텍처를 가집니다:

Event Source(SNS, SQS, ...)LambdaCloudWatch(Logs, Metrics)X-Ray(Traces)

생성기는 함수 자체를 제공하며, 스택에서 이벤트 소스를 연결하여 함수를 호출합니다(예: API Gateway 통합, EventBridge 규칙, S3 알림 또는 SQS 이벤트 소스 매핑).

함수 구현

섹션 제목: “함수 구현”

주요 함수 구현은 <function-name>.ts에 있습니다. 다음은 예시입니다:

import { parser } from '@aws-lambda-powertools/parser/middleware';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
import middy from '@middy/core';
import { Tracer } from '@aws-lambda-powertools/tracer';
import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';
import { Logger } from '@aws-lambda-powertools/logger';
import { Metrics } from '@aws-lambda-powertools/metrics';
import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
import { z } from 'zod';


process.env.POWERTOOLS_METRICS_NAMESPACE = 'MyFunction';
process.env.POWERTOOLS_SERVICE_NAME = 'MyFunction';


const tracer = new Tracer();
const logger = new Logger();
const metrics = new Metrics();


export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  logger.info('Received event', event);


  // TODO: implement
};


export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .use(parser({ schema: EventBridgeSchema }))
  .handler(myFunction);

생성기는 여러 기능을 자동으로 설정합니다:

  1. 향상된 Lambda 기능을 위한 Middy 미들웨어 스택
  2. 관찰성을 위한 AWS Lambda Powertools 통합
  3. CloudWatch를 사용한 메트릭 수집
  4. 파서 미들웨어를 사용한 타입 안전성
  5. 최적화된 배포 패키지를 위한 Rolldown을 사용한 번들링

AWS Lambda Powertools를 사용한 관찰성

섹션 제목: “AWS Lambda Powertools를 사용한 관찰성”

로깅

섹션 제목: “로깅”

생성기는 Middy 미들웨어를 통한 자동 컨텍스트 주입과 함께 AWS Lambda Powertools를 사용하여 구조화된 로깅을 구성합니다.

export const handler = middy()
  .use(injectLambdaContext(logger))
  .handler(myFunction);

추적

섹션 제목: “추적”

AWS X-Ray 추적은 captureLambdaHandler 미들웨어를 통해 자동으로 구성됩니다. 추적에 사용자 정의 하위 세그먼트를 추가할 수 있습니다:

const tracer = new Tracer();


export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  // Creates a new subsegment
  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Your logic here
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};


export const handler = middy()
  .use(captureLambdaHandler(tracer))
  .handler(myFunction);

메트릭

섹션 제목: “메트릭”

CloudWatch 메트릭은 logMetrics 미들웨어를 통해 각 요청마다 자동으로 수집됩니다. 사용자 정의 메트릭을 추가할 수 있습니다:

const metrics = new Metrics();


export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
  metrics.addMetric("ProcessingTime", MetricUnit.Milliseconds, processingTime);
};


export const handler = middy()
  .use(logMetrics(metrics))
  .handler(myFunction);

타입 안전성

섹션 제목: “타입 안전성”
event ≠ Any

람다 함수를 생성할 때 event를 선택한 경우, 함수는 AWS Lambda Powertools의 parser 미들웨어로 계측됩니다. 예를 들어:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- type-safe with IDE autocompletion
};


export const handler = middy()
  .use(parser({ schema: EventBridgeSchema }))
  .handler(myFunction);

이는 Lambda 이벤트에 대한 컴파일 타임 타입 안전성과 런타임 검증을 제공합니다.

event = Any

event에 대해 Any를 선택한 경우, parser 미들웨어가 연결되지 않으며 event 매개변수는 any로 타입이 지정됩니다. 컴파일 타임 타입 안전성과 런타임 검증을 원하는 경우 특정 event로 함수를 다시 생성하세요.

번들링

섹션 제목: “번들링”

제너레이터는 Rolldown을 사용하여 배포 패키지를 생성하는 bundle 타겟을 자동으로 구성합니다:

Terminal window
pnpm nx bundle <project-name>

Rolldown 구성은 rolldown.config.ts에서 찾을 수 있으며, 생성할 번들마다 항목이 있습니다. Rolldown은 정의된 경우 여러 번들을 병렬로 생성하는 것을 관리합니다.

함수 배포

섹션 제목: “함수 배포”

이 생성기는 선택한 iac를 기반으로 CDK 또는 Terraform 인프라 코드를 생성합니다. 이를 사용하여 함수를 배포할 수 있습니다.

이 생성기는 common/constructs 폴더에 함수를 배포하기 위한 CDK 구성을 생성합니다. CDK 애플리케이션에서 다음과 같이 사용할 수 있습니다:

import { MyProjectMyFunction } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the function to your stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');
  }
}

다음과 같이 설정됩니다:

  1. AWS Lambda 함수
  2. CloudWatch 로그 그룹
  3. X-Ray 추적 구성
  4. CloudWatch 메트릭 네임스페이스

이 함수는 모든 람다 이벤트 소스의 대상으로 사용할 수 있습니다:

아래 예제는 EventBridge를 사용하여 일정에 따라 람다 함수를 호출하는 CDK 코드를 보여줍니다:

import { Rule, Schedule } from 'aws-cdk-lib/aws-events';
import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';
import { MyProjectMyFunction } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the function to your stack
    const fn = new MyProjectMyFunction(this, 'MyFunction');


    // Add the function to an EventBridge scheduled rule
    const eventRule = new Rule(this, 'MyFunctionScheduleRule', {
      schedule: Schedule.cron({ minute: '15' }),
      targets: [new LambdaFunction(fn)],
    });
  }
}