Definisci il gestore di funzioni Lambda in TypeScript

Il gestore di funzioni Lambda è il metodo nel codice della funzione che elabora gli eventi. Quando viene richiamata la funzione, Lambda esegue il metodo del gestore. La funzione viene eseguita fino a quando il gestore non restituisce una risposta, termina o scade.

Nozioni di base sul gestore Typescript

Esempio TypeScript gestore

La seguente funzione di esempio registra il contenuto dell'oggetto evento e restituisce la posizione dei log. Tieni presente quanto segue:

• Prima di utilizzare questo codice in una funzione Lambda, devi aggiungere il pacchetto @types/aws-lambda come dipendenza di sviluppo. Questo pacchetto contiene le definizioni dei tipi per Lambda. Quando è installato @types/aws-lambda, l’istruzione import (import ... from 'aws-lambda') importa le definizioni dei tipi. Non importa il aws-lambda NPM pacchetto, che è uno strumento di terze parti non correlato. Per ulteriori informazioni, consulta aws-lambda nel repository. DefinitelyTyped GitHub

• Il gestore in questo esempio è un modulo ES e deve essere designato come tale nel file package.json o utilizzando l'estensione del file .mjs. Per ulteriori informazioni, consulta le Impostazione di un gestore di funzioni come modulo ES.

import { Handler } from 'aws-lambda';

export const handler: Handler = async (event, context) => {
    console.log('EVENT: \n' + JSON.stringify(event, null, 2));
    return context.logStreamName;
};

Il runtime trasferisce gli argomenti al metodo del gestore. Il primo argomento è l'oggetto event, che contiene le informazioni sull'invoker. L'invoker passa queste informazioni come una stringa in JSON formato -formattato quando chiama Invoke e il runtime le converte in un oggetto. Quando un AWS servizio richiama la funzione, la struttura degli eventi varia in base al servizio. Con TypeScript, consigliamo di utilizzare annotazioni di tipo per l'oggetto evento. Per ulteriori informazioni, consulta Utilizzo di tipi per l'oggetto evento.

Il secondo argomento è l'oggetto context, che contiene le informazioni sulla chiamata, la funzione, e l'ambiente di esecuzione. In questo esempio, la funzione ottiene il nome del flusso di log dall'oggetto context e lo restituisce all'invoker.

Inoltre puoi utilizzare un argomento di richiamo, ovvero una funzione che puoi richiamare nei gestori non asincroni per inviare una risposta. È consigliato l'utilizzo di async/await, anziché dei richiami. Async/Await fornisce una migliore leggibilità, gestione degli errori ed efficienza. Per ulteriori informazioni sulla differenza tra async/await e richiami, consulta Utilizzo dei richiami.

Utilizzo di async/await

Se il codice esegue un'attività asincrona, usa lo schema aync/await per assicurarti che il gestore termini l'esecuzione. Async/await è un modo conciso e leggibile per scrivere codice asincrono in Node.js, senza la necessità di richiami nidificati o di concatenamento di promesse. Con async/await puoi scrivere codice che si legga come codice sincrono, pur rimanendo asincrono e privo di blocchi.

La parola chiave async contrassegna una funzione come asincrona, mentre la parola chiave await mette in pausa l'esecuzione della funzione fino alla risoluzione di Promise.

Esempio TypeScript funzione: asincrona

In questo esempio viene utilizzato fetch, che è disponibile nel runtime di nodejs18.x. Tieni presente quanto segue:

• Prima di utilizzare questo codice in una funzione Lambda, devi aggiungere il pacchetto @types/aws-lambda come dipendenza di sviluppo. Questo pacchetto contiene le definizioni dei tipi per Lambda. Quando è installato @types/aws-lambda, l’istruzione import (import ... from 'aws-lambda') importa le definizioni dei tipi. Non importa il aws-lambda NPM pacchetto, che è uno strumento di terze parti non correlato. Per ulteriori informazioni, consulta aws-lambda nel repository. DefinitelyTyped GitHub

• Il gestore in questo esempio è un modulo ES e deve essere designato come tale nel file package.json o utilizzando l'estensione del file .mjs. Per ulteriori informazioni, consulta le Impostazione di un gestore di funzioni come modulo ES.

import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
const url = 'https://aws.amazon.com/';
export const lambdaHandler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
    try {
        // fetch is available with Node.js 18
        const res = await fetch(url);
        return {
            statusCode: res.status,
            body: JSON.stringify({
                message: await res.text(),
            }),
        };
    } catch (err) {
        console.log(err);
        return {
            statusCode: 500,
            body: JSON.stringify({
                message: 'some error happened',
            }),
        };
    }
};

Utilizzo dei richiami

Per dichiarare il gestore della funzione è consigliato l'utilizzo di async/await, anziché di quello dei richiami. Async/await rappresenta una scelta migliore per diverse ragioni:

• Leggibilità: il codice async/await è più facile da leggere e comprendere rispetto al codice con richiami, che, invece, può di colpo diventare difficile da seguire e provocare problemi con i richiami.

• Debug e gestione degli errori: il debug del codice basato su richiami può essere difficile. La pila delle chiamate può diventare difficile da seguire e gli errori possono essere facilmente ingeriti. Con async/await, puoi utilizzare i blocchi try/catch per gestire gli errori.

• Efficienza: i richiami richiedono spesso il passaggio tra diverse parti del codice. Async/await può ridurre il numero dei passaggi di contesto, realizzando un codice più efficiente.

Quando utilizzi i richiami nel gestore, la funzione continua ad essere eseguita finché il ciclo di eventi è vuoto o la funzione va in timeout. La risposta non viene inviata all'invoker finché tutte le attività del ciclo di eventi non giungono a termine. Se la funzione va in timeout, viene invece restituito un errore. Puoi configurare il runtime per inviare immediatamente la risposta impostando il contesto. callbackWaitsForEmptyEventLoopa false.

La funzione di callback richiede due argomenti, un Error e una risposta. L'oggetto risposta deve essere compatibile con JSON.stringify.

Esempio TypeScript funzione con callback

Questa funzione di esempio riceve un evento da Amazon API Gateway, registra l'evento e gli oggetti di contesto e quindi restituisce una risposta a API Gateway. Tieni presente quanto segue:

• Prima di utilizzare questo codice in una funzione Lambda, devi aggiungere il pacchetto @types/aws-lambda come dipendenza di sviluppo. Questo pacchetto contiene le definizioni dei tipi per Lambda. Quando è installato @types/aws-lambda, l’istruzione import (import ... from 'aws-lambda') importa le definizioni dei tipi. Non importa il aws-lambda NPM pacchetto, che è uno strumento di terze parti non correlato. Per ulteriori informazioni, consulta aws-lambda nel repository. DefinitelyTyped GitHub

• Il gestore in questo esempio è un modulo ES e deve essere designato come tale nel file package.json o utilizzando l'estensione del file .mjs. Per ulteriori informazioni, consulta le Impostazione di un gestore di funzioni come modulo ES.

import { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';

export const lambdaHandler = (event: APIGatewayEvent, context: Context, callback: APIGatewayProxyCallback): void => {
    console.log(`Event: ${JSON.stringify(event, null, 2)}`);
    console.log(`Context: ${JSON.stringify(context, null, 2)}`);
    callback(null, {
        statusCode: 200,
        body: JSON.stringify({
            message: 'hello world',
        }),
    });
};

Utilizzo di tipi per l'oggetto evento

Consigliamo di non utilizzare il tipo any per gli argomenti del gestore e il tipo return perché si perde la possibilità di controllare i tipi. Genera invece un evento usando il AWS Serverless Application Model CLI comando sam local generate-event o usa una definizione open source dal pacchetto @types /aws-lambda.

Generazione di un evento utilizzando il comando sam local generate-event

1. Generare un evento proxy Amazon Simple Storage Service (Amazon S3).

   sam local generate-event s3 put >> S3PutEvent.json

2. Utilizzate l'utilità quicktype per generare definizioni dei tipi dal file S3 .json. PutEvent

   npm install -g quicktype
   quicktype S3PutEvent.json -o S3PutEvent.ts

3. Usare i tipi generati nel codice.

   import { S3PutEvent } from './S3PutEvent';
   
   export const lambdaHandler = async (event: S3PutEvent): Promise<void> => {
     event.Records.map((record) => console.log(record.s3.object.key));
   };

Generazione di un evento utilizzando una definizione open-source dal pacchetto @types/aws-lambda

1. Aggiungere il pacchetto @types/aws-lambda come dipendenza dallo sviluppo.

   npm install -D @types/aws-lambda

2. Usare i tipi nel codice.

   import { S3Event } from "aws-lambda";
   
   export const lambdaHandler = async (event: S3Event): Promise<void> => {
     event.Records.map((record) => console.log(record.s3.object.key));
   };

Procedure consigliate di codice per le funzioni Lambda di Typescript

Segui le linee guida riportate nell'elenco seguente per utilizzare le migliori pratiche di codifica durante la creazione delle funzioni Lambda:

• Separare il gestore Lambda dalla logica principale. In questo modo è possibile creare una funzione di cui è più semplice eseguire l'unit test. In Node.js, l'aspetto è analogo al seguente:

  exports.myHandler = function(event, context, callback) {
  	var foo = event.foo;
  	var bar = event.bar;
  	var result = MyLambdaFunction (foo, bar);
  
  	callback(null, result);
  }
  
  function MyLambdaFunction (foo, bar) {
  	// MyLambdaFunction logic here
  }

• Controllare le dipendenze nel pacchetto di distribuzione della funzione. L'ambiente di AWS Lambda esecuzione contiene diverse librerie. Per i runtime Node.js e Python, questi includono. AWS SDKs Per abilitare il set di caratteristiche e aggiornamenti della sicurezza più recenti, Lambda aggiorna periodicamente tali librerie. Tali aggiornamenti possono introdurre lievi modifiche al comportamento della funzione Lambda. Per mantenere il controllo completo delle dipendenze utilizzate dalla funzione, inserire tutte le dipendenze nel pacchetto di implementazione.

• Ridurre la complessità delle dipendenze. Preferire framework più semplici che si caricano velocemente all'avvio del contesto di esecuzione.

• Ridurre al minimo le dimensioni del pacchetto di implementazione al fine di soddisfare le esigenze di runtime. In questo modo viene ridotta la quantità di tempo necessaria per il download del pacchetto e per la relativa decompressione prima dell'invocazione.

• Sfruttare il riutilizzo del contesto di esecuzione per migliorare le prestazioni della funzione. Inizializza SDK i client e le connessioni al database all'esterno del gestore delle funzioni e memorizza nella cache le risorse statiche localmente nella directory. /tmp Le chiamate successive elaborate dalla stessa istanza della funzione possono riutilizzare queste risorse. Ciò consente di risparmiare sui costi riducendo i tempi di esecuzione delle funzioni.

  Per evitare potenziali perdite di dati tra le chiamate, non utilizzare il contesto di esecuzione per archiviare dati utente, eventi o altre informazioni con implicazioni di sicurezza. Se la funzione si basa su uno stato mutabile che non può essere archiviato in memoria all'interno del gestore, considerare la possibilità di creare una funzione separata o versioni separate di una funzione per ogni utente.

• Utilizzare una direttiva keep-alive per mantenere le connessioni persistenti. Lambda elimina le connessioni inattive nel tempo. Se si tenta di riutilizzare una connessione inattiva quando si richiama una funzione, si verificherà un errore di connessione. Per mantenere la connessione persistente, utilizzare la direttiva keep-alive associata al runtime. Per un esempio, vedere Riutilizzo delle connessioni con Keep-Alive in Node.js.

• Utilizzare le variabili di ambiente per passare i parametri operativi alla funzione. Se ad esempio si scrive in un bucket Amazon S3 anziché impostare come hard-coded il nome del bucket in cui si esegue la scrittura, configurare tale nome come una variabile di ambiente.

• Evita di usare invocazioni ricorsive nella tua funzione Lambda, in cui la funzione si richiama da sola o avvia un processo che potrebbe richiamare nuovamente la funzione. Ciò potrebbe provocare un volume non desiderato di invocazioni della funzione e un aumento dei costi. Se vedi un volume involontario di chiamate, imposta la concorrenza riservata alla funzione su «0immediate» per limitare tutte le chiamate alla funzione mentre aggiorni il codice.

• Non utilizzare documenti non documentati e non pubblici APIs nel codice della funzione Lambda. Per i runtime AWS Lambda gestiti, Lambda applica periodicamente aggiornamenti di sicurezza e funzionalità all'interno di Lambda. APIs Questi API aggiornamenti interni possono essere incompatibili con le versioni precedenti e portare a conseguenze indesiderate, come errori di chiamata se la funzione dipende da questi aggiornamenti non pubblici. APIs Vedi il riferimento per un elenco di quelli disponibili al pubblico. API APIs

• Scrivi un codice idempotente. La scrittura di un codice idempotente per le tue funzioni garantisce che gli eventi duplicati vengano gestiti allo stesso modo. Il tuo codice dovrebbe convalidare correttamente gli eventi e gestire con garbo gli eventi duplicati. Per ulteriori informazioni, consulta Come posso rendere idempotente la mia funzione Lambda?.