Função Lambda TypeScript

O gerador de Função Lambda TypeScript fornece a capacidade de adicionar uma função lambda a um projeto TypeScript existente.

Este gerador cria um novo manipulador lambda TypeScript com configuração de infraestrutura AWS CDK ou Terraform. O manipulador gerado usa AWS Lambda Powertools for TypeScript para observabilidade, incluindo logging, rastreamento AWS X-Ray e CloudWatch Metrics, bem como segurança de tipo opcional para o evento usando o Parser from AWS Lambda Powertools

Uso

Gerar uma função lambda TypeScript

Você pode gerar uma função lambda de duas maneiras:

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#lambda-function
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	O projeto ao qual adicionar a função lambda
name Obrigatório	string	-	O nome da função a adicionar
functionPath	string	-	Subdiretório opcional dentro do diretório de origem do projeto para adicionar a funçã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	Esquema de origem de evento opcional para usar na função lambda
infra	lambda | none	lambda	O tipo de infraestrutura para implantar sua função Lambda.
iac	inherit | cdk | terraform	inherit	O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto:

• Directory<project-name>

  • Directorysrc/

    • <lambda-function>.ts Function implementation

Se a opção functionPath for fornecida, o gerador adicionará o manipulador ao caminho especificado dentro do diretório de origem do projeto:

• Directory<project-name>

  • Directorysrc/

    • Directory<custom-path>/

      • <function-name>.ts Function implementation

Infraestrutura

Como este gerador fornece infraestrutura como código baseada no seu iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK relevantes ou módulos Terraform.

O projeto comum de infraestrutura como código é estruturado da seguinte forma:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

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

Projeto Gerado

Este projeto é gerado usando o gerador ts#project e, portanto, configura os mesmos alvos de build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projeto Gerado

Este projeto é gerado usando o gerador terraform#project e, portanto, configura os mesmos alvos de build.

O gerador cria infraestrutura como código para implantar sua função com base no iac selecionado:

CDK

O gerador cria um construto CDK que pode ser usado para implantar sua função, que reside no diretório packages/common/constructs/src/app/lambda-functions.

Terraform

O gerador cria um módulo Terraform que pode ser usado para implantar sua função, que reside no diretório packages/common/terraform/src/app/lambda-functions/<function-name>.

Arquitetura

A função implantada possui a seguinte arquitetura:

O gerador fornece a função em si; você conecta a origem do evento em sua stack para invocá-la (por exemplo, uma integração com API Gateway, uma regra do EventBridge, uma notificação do S3 ou um mapeamento de origem de eventos do SQS).

Implementando sua Função

A implementação principal da função está em <function-name>.ts. Aqui está um exemplo:

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

O gerador configura vários recursos automaticamente:

1. Pilha de middleware Middy para funcionalidade Lambda aprimorada
2. Integração com AWS Lambda Powertools para observabilidade
3. Coleta de métricas com CloudWatch
4. Segurança de tipo usando middleware parser
5. Empacotamento com Rolldown para pacotes de implantação otimizados

Observabilidade com AWS Lambda Powertools

Logging

O gerador configura logging estruturado usando AWS Lambda Powertools com injeção automática de contexto via middleware Middy.

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

Rastreamento

O rastreamento AWS X-Ray é configurado automaticamente via middleware captureLambdaHandler. Você pode adicionar subsegmentos personalizados aos seus rastreamentos:

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

Métricas

As métricas do CloudWatch são coletadas automaticamente para cada solicitação via middleware logMetrics. Você pode adicionar métricas personalizadas:

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

Segurança de Tipo

event ≠ Any

Se você escolheu um event ao gerar sua função lambda, sua função é instrumentada com o parser middleware from AWS Lambda Powertools. Por exemplo:

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

Isso fornece segurança de tipo em tempo de compilação e validação em tempo de execução para seus eventos Lambda.

Tratamento de Erros

Se você não quiser que seu manipulador lance um erro quando o evento não estiver em conformidade com o esquema, você pode usar a opção safeParse.

Dados de Evento Personalizados

Se você tiver dados personalizados aninhados dentro de um evento, por exemplo, um stream DynamoDB ou evento EventBridge, você pode se beneficiar do uso de Envelopes para fornecer segurança de tipo para esses dados personalizados.

event = Any

Se você selecionou Any para seu event, o middleware parser não é conectado e o parâmetro event é tipado como any. Regenere a função com um event específico se você quiser segurança de tipo em tempo de compilação e validação em tempo de execução.

Empacotamento

O gerador configura automaticamente um target bundle que usa Rolldown para criar um pacote de implantação:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

A configuração do Rolldown pode ser encontrada em rolldown.config.ts, com uma entrada por pacote a ser gerado. O Rolldown gerencia a criação de múltiplos pacotes em paralelo, se definidos.

Configuração Personalizada

Você pode ajustar a configuração do Rolldown em rolldown.config.ts, por exemplo, se você tiver dependências que dependem de caminhos de arquivo e não podem ser empacotadas, você pode adicioná-las à lista de módulos external.

Implantando sua Função

Este gerador cria infraestrutura como código CDK ou Terraform com base no seu iac selecionado. Você pode usar isso para implantar sua função.

CDK

Este gerador cria um construct CDK para implantar sua função na pasta common/constructs. Você pode usar isso em uma aplicação 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');
  }
}

Isso configura:

1. Função AWS Lambda
2. Grupo de logs CloudWatch
3. Configuração de rastreamento X-Ray
4. Namespace de métricas CloudWatch

Esta função pode então ser usada como destino para qualquer fonte de evento lambda:

Correspondência de Fonte de Evento

Certifique-se de que a fonte de evento corresponda à opção event selecionada para garantir que o evento seja tratado adequadamente dentro da sua função handler.

O exemplo abaixo demonstra o código CDK para invocar sua função lambda em um cronograma usando 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

Este gerador cria um módulo Terraform para implantar sua função na pasta common/terraform. Instancie o módulo compartilhado core/asset-bucket uma vez por implantação e passe seu bucket_name para a entrada 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
  ]
}

Isso configura:

1. Função AWS Lambda
2. Grupo de logs CloudWatch
3. Configuração de rastreamento X-Ray
4. Namespace de métricas CloudWatch

Esta função pode então ser usada como destino para qualquer fonte de evento lambda. O exemplo abaixo demonstra o código Terraform para invocar sua função lambda em um cronograma usando 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
}

Correspondência de Fonte de Evento

Certifique-se de que a fonte de evento corresponda à opção event selecionada para garantir que o evento seja tratado adequadamente dentro da sua função handler.