TypeScript Lambda 函数

TypeScript Lambda 函数生成器提供了向现有 TypeScript 项目添加 lambda 函数的能力。

此生成器创建一个新的 TypeScript lambda 处理程序，并配置 AWS CDK 或 Terraform 基础设施。生成的处理程序使用 AWS Lambda Powertools for TypeScript 进行可观测性，包括日志记录、AWS X-Ray 追踪和 CloudWatch 指标，以及使用 AWS Lambda Powertools 的 Parser 为事件提供可选的类型安全。

用法

生成 TypeScript lambda 函数

您可以通过两种方式生成 lambda 函数：

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

您还可以执行试运行以查看哪些文件会被更改

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. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#lambda-function
5. 填写必需参数
6. 点击 Generate

选项

参数	类型	默认值	描述
project 必需	string	-	要添加 Lambda 函数的项目
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 | VpcLatticeV2Schema	Any	用于 lambda 函数的可选事件源架构
infra	lambda | none	lambda	用于部署 Lambda 函数的基础设施类型。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下，这继承自您的初始选择。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器将向您的项目添加以下文件：

• 文件夹<project-name>

  • 文件夹src/

    • <lambda-function>.ts Function implementation

如果提供了 functionPath 选项，生成器将在项目源目录中的指定路径添加处理程序：

• 文件夹<project-name>

  • 文件夹src/

    • 文件夹<custom-path>/

      • <function-name>.ts Function implementation

基础设施

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ Constructs for infrastructure specific to a project/generator

      • …
    • 文件夹core/ 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

此项目使用 ts#project 生成器生成，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ Terraform modules for infrastructure specific to a project/generator

      • …
    • 文件夹core/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

此项目使用 terraform#project 生成器生成，因此配置了相同的构建目标。

生成器根据您选择的 iac 创建用于部署函数的基础设施即代码：

CDK

生成器创建一个 CDK 构造，可用于部署您的函数，该构造位于 packages/common/constructs/src/app/lambda-functions 目录中。

Terraform

生成器创建一个 Terraform 模块，可用于部署您的函数，该模块位于 packages/common/terraform/src/app/lambda-functions/<function-name> 目录中。

架构

已部署的函数具有以下架构：

生成器提供函数本身；您需要在堆栈中连接事件源以调用它（例如，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. Middy 中间件栈，用于增强 Lambda 功能
2. AWS Lambda Powertools 集成，用于可观测性
3. 指标收集，使用 CloudWatch
4. 类型安全，使用解析器中间件
5. 使用 Rolldown 打包，用于优化部署包

使用 AWS Lambda Powertools 实现可观测性

日志记录

生成器使用 AWS Lambda Powertools 配置结构化日志记录，并通过 Middy 中间件自动注入上下文。

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

如果您在生成 lambda 函数时选择了 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 事件提供了编译时类型安全和运行时验证。

错误处理

如果您不希望处理程序在事件不符合架构时抛出错误，可以使用 safeParse 选项。

自定义事件数据

如果您在事件中嵌套了自定义数据，例如 DynamoDB 流或 EventBridge 事件，您可能会受益于使用 Envelopes 为该自定义数据提供类型安全。

event = Any

如果您为 event 选择了 Any，则不会连接 parser 中间件，并且 event 参数的类型为 any。如果您想要编译时类型安全和运行时验证，请使用特定的 event 重新生成函数。

打包

生成器会自动配置一个 bundle 目标，它使用 Rolldown 来创建部署包：

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Rolldown 配置可以在 rolldown.config.ts 中找到，每个要生成的包都有一个入口。Rolldown 会管理并行创建多个包（如果已定义）。

自定义配置

您可以在 rolldown.config.ts 中调整 Rolldown 的配置，例如，如果您有依赖于文件路径且无法打包的依赖项，可以将它们添加到 external 模块列表中。

部署您的函数

此生成器会根据您选择的 iac 创建 CDK 或 Terraform 基础设施即代码。您可以使用它来部署您的函数。

CDK

此生成器会在 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 指标命名空间

然后，此函数可以用作任何 lambda 事件源的目标：

事件源匹配

确保事件源与所选的 event 选项匹配，以确保事件在处理程序函数中得到正确处理。

下面的示例演示了使用 EventBridge 按计划调用 lambda 函数的 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)],
    });
  }
}

Terraform

此生成器会在 common/terraform 文件夹中创建一个用于部署函数的 Terraform 模块。为每个部署实例化一次共享的 core/asset-bucket 模块，并将其 bucket_name 传递到 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
  ]
}

这将设置：

1. AWS Lambda 函数
2. CloudWatch 日志组
3. X-Ray 跟踪配置
4. CloudWatch 指标命名空间

然后，此函数可以用作任何 lambda 事件源的目标。下面的示例演示了使用 EventBridge 按计划调用 lambda 函数的 Terraform 代码：

# 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 选项匹配，以确保事件在处理程序函数中得到正确处理。