Hàm Lambda TypeScript

Trình tạo Hàm Lambda TypeScript cung cấp khả năng thêm một hàm lambda vào một dự án TypeScript hiện có.

Trình tạo này tạo một handler lambda TypeScript mới với cấu hình cơ sở hạ tầng AWS CDK hoặc Terraform. Handler được tạo sử dụng AWS Lambda Powertools for TypeScript để quan sát, bao gồm ghi log, truy vết AWS X-Ray và CloudWatch Metrics, cũng như tùy chọn type-safety cho sự kiện bằng cách sử dụng Parser from AWS Lambda Powertools

Cách sử dụng

Tạo một hàm lambda TypeScript

Bạn có thể tạo một hàm lambda theo hai cách:

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#lambda-function

yarn

yarn nx g @aws/nx-plugin:ts#lambda-function

npm

npx nx g @aws/nx-plugin:ts#lambda-function

bun

bunx nx g @aws/nx-plugin:ts#lambda-function

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

pnpm

pnpm nx g @aws/nx-plugin:ts#lambda-function --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#lambda-function --dry-run

npm

npx nx g @aws/nx-plugin:ts#lambda-function --dry-run

bun

bunx nx g @aws/nx-plugin:ts#lambda-function --dry-run

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - ts#lambda-function
5. Điền các tham số bắt buộc
6. Nhấp Generate

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án để thêm hàm lambda vào
name Bắt buộc	string	-	Tên của function cần thêm
functionPath	string	-	Thư mục con tùy chọn trong thư mục nguồn của dự án để thêm hàm vào
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 | VpcLatticeV2Schema	Any	Schema nguồn sự kiện tùy chọn để sử dụng cho lambda function
infra	lambda | none	lambda	Loại hạ tầng để triển khai Lambda function của bạn.
iac	inherit | cdk | terraform	inherit	Nhà cung cấp IaC ưu tiên. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Trình tạo

Trình tạo sẽ thêm các tệp sau vào dự án của bạn:

• Thư mục<project-name>

  • Thư mụcsrc/

    • <lambda-function>.ts Function implementation

Nếu tùy chọn functionPath được cung cấp, trình tạo sẽ thêm handler vào đường dẫn được chỉ định trong thư mục nguồn của dự án:

• Thư mục<project-name>

  • Thư mụcsrc/

    • Thư mục<custom-path>/

      • <function-name>.ts Function implementation

Cơ sở hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iac bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Thư mụccore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Thư mụccore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Trình tạo tạo mã cơ sở hạ tầng để triển khai hàm của bạn dựa trên iac đã chọn:

CDK

Trình tạo tạo một construct CDK có thể được sử dụng để triển khai hàm của bạn, nằm trong thư mục packages/common/constructs/src/app/lambda-functions.

Terraform

Trình tạo tạo một module Terraform có thể được sử dụng để triển khai hàm của bạn, nằm trong thư mục packages/common/terraform/src/app/lambda-functions/<function-name>.

Kiến trúc

Hàm được triển khai có kiến trúc như sau:

Generator tạo ra chính hàm đó; bạn kết nối nguồn sự kiện trong stack của mình để gọi nó (ví dụ: tích hợp API Gateway, quy tắc EventBridge, thông báo S3 hoặc ánh xạ nguồn sự kiện SQS).

Triển khai Hàm của bạn

Triển khai hàm chính nằm trong <function-name>.ts. Đây là một ví dụ:

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);

Trình tạo thiết lập một số tính năng tự động:

1. Middy middleware stack để tăng cường chức năng Lambda
2. Tích hợp AWS Lambda Powertools để quan sát
3. Thu thập số liệu với CloudWatch
4. Type-safety sử dụng parser middleware
5. Đóng gói với Rolldown để tối ưu hóa các gói triển khai

Khả năng quan sát với AWS Lambda Powertools

Ghi log

Trình tạo cấu hình ghi log có cấu trúc bằng cách sử dụng AWS Lambda Powertools với tự động chèn ngữ cảnh thông qua Middy middleware.

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

Truy vết

Truy vết AWS X-Ray được cấu hình tự động thông qua middleware captureLambdaHandler. Bạn có thể thêm các subsegment tùy chỉnh vào các trace của mình:

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);

Số liệu

Số liệu CloudWatch được thu thập tự động cho mỗi yêu cầu thông qua middleware logMetrics. Bạn có thể thêm các số liệu tùy chỉnh:

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);

Type Safety

event ≠ Any

Nếu bạn đã chọn một event khi tạo hàm lambda của mình, hàm của bạn được trang bị parser middleware from AWS Lambda Powertools. Ví dụ:

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);

Điều này cung cấp type safety tại thời điểm biên dịch và xác thực thời gian chạy cho các sự kiện Lambda của bạn.

Xử lý Lỗi

Nếu bạn không muốn handler của mình ném ra lỗi khi sự kiện không tuân theo schema, bạn có thể sử dụng tùy chọn safeParse.

Dữ liệu Sự kiện Tùy chỉnh

Nếu bạn có dữ liệu tùy chỉnh lồng trong một sự kiện, ví dụ như một luồng DynamoDB hoặc sự kiện EventBridge, bạn có thể được hưởng lợi từ việc sử dụng Envelopes để cung cấp type-safety cho dữ liệu tùy chỉnh đó.

event = Any

Nếu bạn đã chọn Any cho event của mình, middleware parser không được kết nối và tham số event được gõ là any. Tạo lại hàm với một event cụ thể nếu bạn muốn type safety tại thời điểm biên dịch và xác thực thời gian chạy.

Đóng gói

Generator tự động cấu hình một target bundle sử dụng Rolldown để tạo gói triển khai:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Cấu hình Rolldown có thể được tìm thấy trong rolldown.config.ts, với một entry cho mỗi bundle cần tạo. Rolldown quản lý việc tạo nhiều bundle song song nếu được định nghĩa.

Cấu hình Tùy chỉnh

Bạn có thể điều chỉnh cấu hình cho Rolldown trong rolldown.config.ts, ví dụ nếu bạn có các dependency dựa vào đường dẫn file và không thể được đóng gói, bạn có thể thêm chúng vào danh sách các module external.

Triển khai Hàm của bạn

Generator này tạo ra mã cơ sở hạ tầng CDK hoặc Terraform dựa trên iac bạn đã chọn. Bạn có thể sử dụng nó để triển khai function của mình.

CDK

Generator này tạo ra một CDK construct để triển khai function của bạn trong thư mục common/constructs. Bạn có thể sử dụng nó trong một ứng dụng 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');
  }
}

Điều này thiết lập:

1. AWS Lambda function
2. CloudWatch log group
3. X-Ray tracing configuration
4. CloudWatch metrics namespace

Function này sau đó có thể được sử dụng làm target cho bất kỳ lambda event source nào:

Event Source Matching

Đảm bảo event source khớp với tùy chọn event đã chọn để đảm bảo event được xử lý đúng cách trong handler function của bạn.

Ví dụ dưới đây minh họa mã CDK để gọi lambda function của bạn theo lịch trình sử dụng EventBridge:

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)],
    });
  }
}

Terraform

Generator này tạo ra một Terraform module để triển khai function của bạn trong thư mục common/terraform. Khởi tạo module core/asset-bucket được chia sẻ một lần cho mỗi lần triển khai và truyền bucket_name của nó vào input asset_bucket_name:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_project_my_function" {
  source = "../../common/terraform/src/app/lambda-functions/my-project-my-function"

  asset_bucket_name = module.asset_bucket.bucket_name

  env = {
    SOME_VARIABLE = "some value"
  }

  additional_iam_policy_statements = [
    # Add any additional permissions your function needs
  ]
}

Điều này thiết lập:

1. AWS Lambda function
2. CloudWatch log group
3. X-Ray tracing configuration
4. CloudWatch metrics namespace

Function này sau đó có thể được sử dụng làm target cho bất kỳ lambda event source nào. Ví dụ dưới đây minh họa mã Terraform để gọi lambda function của bạn theo lịch trình sử dụng EventBridge:

# EventBridge rule for scheduled execution
resource "aws_cloudwatch_event_rule" "my_function_schedule" {
  name                = "my-function-schedule"
  description         = "Trigger my function every 15 minutes"
  schedule_expression = "cron(15 * * * ? *)"
}

# EventBridge target
resource "aws_cloudwatch_event_target" "lambda_target" {
  rule      = aws_cloudwatch_event_rule.my_function_schedule.name
  target_id = "MyFunctionTarget"
  arn       = module.my_project_my_function.function_arn
}

# Permission for EventBridge to invoke the Lambda function
resource "aws_lambda_permission" "allow_eventbridge" {
  statement_id  = "AllowExecutionFromEventBridge"
  action        = "lambda:InvokeFunction"
  function_name = module.my_project_my_function.function_name
  principal     = "events.amazonaws.com"
  source_arn    = aws_cloudwatch_event_rule.my_function_schedule.arn
}

Event Source Matching

Đảm bảo event source khớp với tùy chọn event đã chọn để đảm bảo event được xử lý đúng cách trong handler function của bạn.