Fonction Lambda TypeScript

Le générateur de fonction Lambda TypeScript offre la possibilité d’ajouter une fonction lambda à un projet TypeScript existant.

Ce générateur crée un nouveau gestionnaire lambda TypeScript avec une configuration d’infrastructure AWS CDK ou Terraform. Le gestionnaire généré utilise AWS Lambda Powertools for TypeScript pour l’observabilité, incluant la journalisation, le traçage AWS X-Ray et les métriques CloudWatch, ainsi qu’une sécurité de type optionnelle pour l’événement en utilisant le Parser from AWS Lambda Powertools

Usage

Générer une fonction lambda TypeScript

Vous pouvez générer une fonction lambda de deux manières :

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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - ts#lambda-function
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	Le projet auquel ajouter la fonction lambda
name Requis	string	-	Le nom de la fonction à ajouter
functionPath	string	-	Sous-répertoire optionnel dans le répertoire source du projet où ajouter la fonction
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	Schéma de source d'événement optionnel à utiliser pour la fonction lambda
infra	lambda | none	lambda	Le type d'infrastructure pour déployer votre fonction Lambda.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, ceci est hérité de votre sélection initiale.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur ajoutera les fichiers suivants à votre projet :

• Répertoire<project-name>

  • Répertoiresrc/

    • <lambda-function>.ts Function implementation

Si l’option functionPath est fournie, le générateur ajoutera le gestionnaire au chemin spécifié dans le répertoire source du projet :

• Répertoire<project-name>

  • Répertoiresrc/

    • Répertoire<custom-path>/

      • <function-name>.ts Function implementation

Infrastructure

Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.

Le projet d’infrastructure en tant que code commun est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans app

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

Projet généré

Ce projet est généré en utilisant le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Répertoirecore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projet généré

Ce projet est généré en utilisant le générateur terraform#project et configure donc les mêmes cibles de build.

Le générateur crée une infrastructure en tant que code pour déployer votre fonction en fonction de votre iac sélectionné :

CDK

Le générateur crée une construction CDK qui peut être utilisée pour déployer votre fonction, qui réside dans le répertoire packages/common/constructs/src/app/lambda-functions.

Terraform

Le générateur crée un module Terraform qui peut être utilisé pour déployer votre fonction, qui réside dans le répertoire packages/common/terraform/src/app/lambda-functions/<function-name>.

Architecture

La fonction déployée a l’architecture suivante :

Le générateur fournit la fonction elle-même ; vous connectez la source d’événements dans votre stack pour l’invoquer (par exemple, une intégration API Gateway, une règle EventBridge, une notification S3 ou un mappage de source d’événements SQS).

Implémenter votre fonction

L’implémentation principale de la fonction se trouve dans <function-name>.ts. Voici un exemple :

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

Le générateur configure automatiquement plusieurs fonctionnalités :

1. Pile de middleware Middy pour une fonctionnalité Lambda améliorée
2. Intégration AWS Lambda Powertools pour l’observabilité
3. Collecte de métriques avec CloudWatch
4. Sécurité de type en utilisant le middleware parser
5. Bundling avec Rolldown pour des packages de déploiement optimisés

Observabilité avec AWS Lambda Powertools

Journalisation

Le générateur configure la journalisation structurée en utilisant AWS Lambda Powertools avec injection automatique de contexte via le middleware Middy.

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

Traçage

Le traçage AWS X-Ray est configuré automatiquement via le middleware captureLambdaHandler. Vous pouvez ajouter des sous-segments personnalisés à vos traces :

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étriques

Les métriques CloudWatch sont collectées automatiquement pour chaque requête via le middleware logMetrics. Vous pouvez ajouter des métriques personnalisées :

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

Sécurité de type

event ≠ Any

Si vous avez choisi un event lors de la génération de votre fonction lambda, votre fonction est instrumentée avec le parser middleware from AWS Lambda Powertools. Par exemple :

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

Cela fournit une sécurité de type à la compilation et une validation à l’exécution pour vos événements Lambda.

Gestion des erreurs

Si vous ne voulez pas que votre gestionnaire lève une erreur lorsque l’événement ne correspond pas au schéma, vous pouvez utiliser l’option safeParse.

Données d’événement personnalisées

Si vous avez des données personnalisées imbriquées dans un événement, par exemple un flux DynamoDB ou un événement EventBridge, vous pouvez bénéficier de l’utilisation des Envelopes pour fournir une sécurité de type pour ces données personnalisées.

event = Any

Si vous avez sélectionné Any pour votre event, le middleware parser n’est pas connecté et le paramètre event est typé comme any. Régénérez la fonction avec un event spécifique si vous souhaitez une sécurité de type à la compilation et une validation à l’exécution.

Bundling

Le générateur configure automatiquement une cible bundle qui utilise Rolldown pour créer un package de déploiement :

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

La configuration de Rolldown se trouve dans rolldown.config.ts, avec une entrée par bundle à générer. Rolldown gère la création de plusieurs bundles en parallèle s’ils sont définis.

Configuration personnalisée

Vous pouvez ajuster la configuration de Rolldown dans rolldown.config.ts, par exemple si vous avez des dépendances qui reposent sur des chemins de fichiers et ne peuvent pas être bundlées, vous pouvez les ajouter à la liste des modules external.

Déployer votre fonction

Ce générateur crée du code d’infrastructure CDK ou Terraform en fonction de votre iac sélectionné. Vous pouvez l’utiliser pour déployer votre fonction.

CDK

Ce générateur crée une construction CDK pour déployer votre fonction dans le dossier common/constructs. Vous pouvez l’utiliser dans une application 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');
  }
}

Cela configure :

1. Fonction AWS Lambda
2. Groupe de journaux CloudWatch
3. Configuration du traçage X-Ray
4. Espace de noms des métriques CloudWatch

Cette fonction peut ensuite être utilisée comme cible pour n’importe quelle source d’événements lambda :

Correspondance de la source d’événements

Assurez-vous que la source d’événements correspond à l’option event sélectionnée pour garantir que l’événement est correctement géré dans votre fonction de gestionnaire.

L’exemple ci-dessous démontre le code CDK pour invoquer votre fonction lambda selon un calendrier en utilisant 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

Ce générateur crée un module Terraform pour déployer votre fonction dans le dossier common/terraform. Instanciez le module partagé core/asset-bucket une fois par déploiement et transmettez son bucket_name dans l’entrée 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
  ]
}

Cela configure :

1. Fonction AWS Lambda
2. Groupe de journaux CloudWatch
3. Configuration du traçage X-Ray
4. Espace de noms des métriques CloudWatch

Cette fonction peut ensuite être utilisée comme cible pour n’importe quelle source d’événements lambda. L’exemple ci-dessous démontre le code Terraform pour invoquer votre fonction lambda selon un calendrier en utilisant 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
}

Correspondance de la source d’événements

Assurez-vous que la source d’événements correspond à l’option event sélectionnée pour garantir que l’événement est correctement géré dans votre fonction de gestionnaire.