Hàm Lambda TypeScript

Generator TypeScript Lambda Function cung cấp khả năng thêm một lambda function vào dự án TypeScript hiện có.

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

Cách sử dụng

Tạo một TypeScript lambda function

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

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#lambda-function
5. Fill in the required parameters
6. Click Generate

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

You can also perform a dry-run to see what files would be changed

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

Tùy chọn

Parameter	Type	Default	Description
project Required	string	-	The project to add the lambda function to
functionName Required	string	-	The name of the function to add
functionPath	string	-	Optional subdirectory within the project source directory to add the function to
eventSource	string	Any	Optional event source schema to use for the lambda function
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Kết quả của Generator

Generator sẽ thêm các file sau vào dự án của bạn:

• Thư mục<project-name>

  • Thư mụcsrc/

    • <lambda-function>.ts Triển khai Function

Nếu tùy chọn functionPath được cung cấp, generator 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 Triển khai Function

Cơ sở hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iacProvider 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 cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Ghi chú

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 cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Ghi chú

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.

Generator tạo infrastructure as code để triển khai function của bạn dựa trên iacProvider đã chọn:

CDK

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

Terraform

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

Triển khai Function của bạn

Triển khai function 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);

Generator tự động thiết lập một số tính nă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 Metrics với CloudWatch
4. Type-safety sử dụng parser middleware
5. Bundling với Rolldown cho các gói triển khai được tối ưu hóa

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

Logging

Generator cấu hình structured logging sử dụng AWS Lambda Powertools với tự động inject context thông qua Middy middleware.

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

Tracing

AWS X-Ray tracing đượ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 traces của mình:

const tracer = new Tracer();

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  // Tạo một subsegment mới
  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Logic của bạn ở đây
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

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

Metrics

CloudWatch metrics được thu thập tự động cho mỗi request thông qua middleware logMetrics. Bạn có thể thêm các metric 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

Nếu bạn đã chọn một eventSource khi tạo lambda function, function của bạn sẽ được trang bị parser middleware từ AWS Lambda Powertools. Ví dụ:

export const myFunction = async (
  event: z.infer<typeof EventBridgeSchema>,
): Promise<void> => {
  event.detail // <- type-safe với tự động hoàn thành IDE
};

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 runtime cho các Lambda events của bạn.

Chú ý

Nếu bạn không muốn handler của mình throw error khi event không tuân thủ schema, bạn có thể sử dụng tùy chọn safeParse.

Mẹo

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

Nếu bạn không muốn type cho event của mình, bạn có thể chọn Any cho eventSource, điều này sẽ dẫn đến kiểu any cho tham số event.

Bundling

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 run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

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.

Mẹo

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 phụ thuộc vào đường dẫn file và không thể được bundle, bạn có thể thêm chúng vào danh sách các module external.

Triển khai Function của bạn

Generator này tạo ra mã infrastructure as code bằng CDK hoặc Terraform dựa trên iacProvider 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. Cấu hình X-Ray tracing
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:

Ghi chú

Đảm bảo event source khớp với tùy chọn eventSource đã 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. Bạn có thể sử dụng nó trong cấu hình Terraform:

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

  # Environment variables for the Lambda function
  env = {
    SOME_VARIABLE = "some value"
  }

  # Additional IAM policies if needed
  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. Cấu hình X-Ray tracing
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
}

Ghi chú

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