Lambda-Funktionshandler in Node.js definieren

Der Lambda-Funktionshandler ist die Methode in Ihrem Funktionscode, die Ereignisse verarbeitet. Wenn Ihre Funktion aufgerufen wird, führt Lambda die Handler-Methode aus. Ihre Funktion wird so lange ausgeführt, bis der Handler eine Antwort zurückgibt, beendet wird oder ein Timeout auftritt.

Auf dieser Seite wird beschrieben, wie Sie mit Lambda-Funktionshandlern in Node.js arbeiten, einschließlich Optionen für die Projekteinrichtung, Benennungskonventionen und Best Practices. Diese Seite enthält auch ein Beispiel für eine Lambda-Funktion von Node.js, die Informationen über eine Bestellung aufnimmt, eine Textdateiquittung erstellt und diese Datei in einen Amazon Simple Storage Service (Amazon S3) -Bucket legt. Informationen darüber, wie Sie Ihre Funktion nach dem Schreiben einsetzen können, finden Sie unter Bereitstellen von Node.js Lambda-Funktionen mit ZIP-Dateiarchiven oder Bereitstellen von Node.js-Lambda-Funktionen mit Container-Images.

Richten Sie Ihr Node.js Handler-Projekt ein

Es gibt mehrere Möglichkeiten, ein Node.js Lambda-Projekt zu initialisieren. Sie können beispielsweise ein Standardprojekt vom Typ Node.js erstellennpm, indem Sie eine AWS SAM Anwendung erstellen oder eine AWS CDK Anwendung erstellen.

Um das Projekt zu erstellen, verwenden Sienpm:

npm init

Dieser Befehl initialisiert Ihr Projekt und generiert eine package.json Datei, die die Metadaten und Abhängigkeiten Ihres Projekts verwaltet.

Ihr Funktionscode befindet sich in einer .js .mjs JavaScript OR-Datei. Im folgenden Beispiel geben wir dieser Datei einen Namen, index.mjs weil sie einen ES-Modul-Handler verwendet. Lambda unterstützt sowohl ES-Modul- als auch CommonJS-Handler. Weitere Informationen finden Sie unter Designieren eines Funktionshandlers als ES-Modul.

Ein typisches Lambda-Funktionsprojekt von Node.js folgt dieser allgemeinen Struktur:

/project-root
  ├── index.mjs — Contains main handler
  ├── package.json — Project metadata and dependencies
  ├── package-lock.json — Dependency lock file
  └── node_modules/ — Installed dependencies

Beispiel für den Lambda-Funktionscode von Node.js

Das folgende Beispiel für einen Lambda-Funktionscode nimmt Informationen über eine Bestellung auf, erstellt eine Textdateiquittung und platziert diese Datei in einem Amazon S3 S3-Bucket.

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

// Initialize the S3 client outside the handler for reuse
const s3Client = new S3Client();

/**
 * Lambda handler for processing orders and storing receipts in S3.
 * @param {Object} event - Input event containing order details
 * @param {string} event.order_id - The unique identifier for the order
 * @param {number} event.amount - The order amount
 * @param {string} event.item - The item purchased
 * @returns {Promise<string>} Success message
 */
export const handler = async(event) => {
    try {
        // Access environment variables
        const bucketName = process.env.RECEIPT_BUCKET;
        if (!bucketName) {
            throw new Error('RECEIPT_BUCKET environment variable is not set');
        }

        // Create the receipt content and key destination
        const receiptContent = `OrderID: ${event.order_id}\nAmount: $${event.amount.toFixed(2)}\nItem: ${event.item}`;
        const key = `receipts/${event.order_id}.txt`;

        // Upload the receipt to S3
        await uploadReceiptToS3(bucketName, key, receiptContent);

        console.log(`Successfully processed order ${event.order_id} and stored receipt in S3 bucket ${bucketName}`);
        return 'Success';
    } catch (error) {
        console.error(`Failed to process order: ${error.message}`);
        throw error;
    }
};

/**
 * Helper function to upload receipt to S3
 * @param {string} bucketName - The S3 bucket name
 * @param {string} key - The S3 object key
 * @param {string} receiptContent - The content to upload
 * @returns {Promise<void>}
 */
async function uploadReceiptToS3(bucketName, key, receiptContent) {
    try {
        const command = new PutObjectCommand({
            Bucket: bucketName,
            Key: key,
            Body: receiptContent
        });

        await s3Client.send(command);
    } catch (error) {
        throw new Error(`Failed to upload receipt to S3: ${error.message}`);
    }
}

Diese index.mjs-Datei enthält die folgenden Abschnitte des Codes:

Damit diese Funktion ordnungsgemäß funktioniert, muss ihre Ausführungsrolle die s3:PutObject Aktion zulassen. Stellen Sie außerdem sicher, dass Sie die RECEIPT_BUCKET-Umgebungsvariable definieren. Nach einem erfolgreichen Aufruf sollte der Amazon-S3-Bucket eine Empfangsdatei enthalten.

Namenskonventionen für Handler

Wenn Sie eine Funktion konfigurieren, entspricht der Wert der Handler-Einstellung dem Dateinamen und dem Namen der exportierten Handler-Methode, getrennt durch einen Punkt. Der Standardwert für Funktionen, die in der Konsole erstellt werden und für die Beispiele in diesem Handbuch ist index.handler. Dies deutet auf die handler-Methode hin, die aus der index.js- oder index.mjs-Datei wurde.

Wenn Sie eine Funktion in der Konsole mit einem anderen Dateinamen oder Funktionshandlernamen erstellen, müssen Sie den Standardhandlernamen bearbeiten.

Definieren Sie das Eingabeereignisobjekt und greifen Sie darauf zu

JSON ist das gebräuchlichste und standardmäßigste Eingabeformat für Lambda-Funktionen. In diesem Beispiel erwartet die Funktion eine Eingabe ähnlich der folgenden:

{
    "order_id": "12345",
    "amount": 199.99,
    "item": "Wireless Headphones"
}

Wenn Sie mit Lambda-Funktionen in Node.js arbeiten, können Sie die erwartete Form des Eingabeereignisses mithilfe von JSDoc Anmerkungen definieren. In diesem Beispiel definieren wir die Eingabestruktur im Kommentar des Handlers JSDoc :

/**
 * Lambda handler for processing orders and storing receipts in S3.
 * @param {Object} event - Input event containing order details
 * @param {string} event.order_id - The unique identifier for the order
 * @param {number} event.amount - The order amount
 * @param {string} event.item - The item purchased
 * @returns {Promise<string>} Success message
 */

Nachdem Sie diese Typen in Ihrem JSDoc Kommentar definiert haben, können Sie direkt in Ihrem Code auf die Felder des Event-Objekts zugreifen. Zum Beispiel holt event.order_id den Wert von order_id aus der ursprünglichen Eingabe.

Gültige Handlermuster für Funktionen von Node.js

Wir empfehlen, dass Sie async/await verwenden, um den Funktionshandler zu deklarieren, anstatt Callbacks zu verwenden. Async/await is a concise and readable way to write asynchronous code, without the need for nested callbacks or chaining promises. With async/await, Sie können Code schreiben, der sich wie synchroner Code liest, aber trotzdem asynchron und nicht blockierend ist.

Verwenden von async/await (empfohlen)

Das async-Schlüsselwort kennzeichnet eine Funktion als asynchron, und das await-Schlüsselwort unterbricht die Ausführung der Funktion, bis Promise aufgelöst ist. Der Handler akzeptiert die folgenden Argumente:

Hier sind die gültigen Signaturen für das Async/Await-Muster:

Callbacks verwenden

Callback-Handler können die Argumente Event, Kontext und Callback verwenden. Hier sind die gültigen Signaturen:

Die Callback-Funktion erwartet eine Antwort Error und eine Antwort, die JSON-Serialisierbar sein muss. Die Funktion wird so lange ausgeführt, bis die Ereignisschleife leer ist oder das Timeout der Funktion überschritten wird. Die Antwort wird erst an den Aufrufer gesendet, wenn alle Ereignisschleifenaufgaben abgeschlossen sind. Wenn eine Zeitüberschreitung der Funktion auftritt, wird stattdessen ein Fehler zurückgegeben. Sie können die Laufzeit so konfigurieren, dass die Antwort sofort gesendet wird, indem Sie den Kontext festlegen. callbackWaitsForEmptyEventLoopauf „Falsch“ setzen.

import https from "https";
let url = "https://aws.amazon.com/";

export const handler = (event, context, callback) => {
  https.get(url, (res) => {
    callback(null, res.statusCode);
  }).on("error", (e) => {
    callback(Error(e));
  });
};

Verwenden Sie das SDK für JavaScript v3 in Ihrem Handler

Oft verwenden Sie Lambda-Funktionen, um mit anderen AWS Ressourcen zu interagieren oder diese zu aktualisieren. Die einfachste Art, eine Schnittstelle zu diesen Ressourcen herzustellen, ist die AWS SDK für JavaScript Verwendung von. Alle unterstützten Lambda Node.js Runtimes enthalten das SDK für JavaScript Version 3. Wir empfehlen jedoch dringend, dass Sie die benötigten AWS SDK-Clients in Ihr Bereitstellungspaket aufnehmen. Dadurch wird die Abwärtskompatibilität bei future Lambda-Runtime-Updates maximiert. Verlassen Sie sich nur dann auf das von der Laufzeit bereitgestellte SDK, wenn Sie keine zusätzlichen Pakete hinzufügen können (z. B. wenn Sie den Code-Editor der Lambda-Konsole oder Inline-Code in einer AWS CloudFormation Vorlage verwenden).

Um Ihrer Funktion SDK-Abhängigkeiten hinzuzufügen, verwenden Sie den npm install-Befehl für die spezifischen SDK-Clients, die Sie benötigen. Im Beispielcode haben wir den Amazon S3 S3-Client verwendet. Fügen Sie diese Abhängigkeit hinzu, indem Sie den folgenden Befehl in dem Verzeichnis ausführen, das Ihre package.json Datei enthält:

npm install @aws-sdk/client-s3

Importieren Sie im Funktionscode den Client und die Befehle, die Sie benötigen, wie die Beispielfunktion zeigt:

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';

Initialisieren Sie dann einen Amazon S3 S3-Client:

const s3Client = new S3Client();

In diesem Beispiel haben wir unseren Amazon S3 S3-Client außerhalb der Haupthandlerfunktion initialisiert, um zu vermeiden, dass wir ihn jedes Mal initialisieren müssen, wenn wir unsere Funktion aufrufen. Nachdem Sie Ihren SDK-Client initialisiert haben, können Sie ihn verwenden, um API-Aufrufe für diesen Service zu tätigen. AWS Der Beispielcode ruft die Amazon S3 PutObjectS3-API-Aktion wie folgt auf:

const command = new PutObjectCommand({
    Bucket: bucketName,
    Key: key,
    Body: receiptContent
});

Zugriff auf Umgebungsvariablen

In Ihrem Handler-Code können Sie auf beliebige Umgebungsvariablen verweisen, indem Sie process.env In diesem Beispiel verweisen wir mit den folgenden Codezeilen auf die definierte RECEIPT_BUCKET Umgebungsvariable:

// Access environment variables
const bucketName = process.env.RECEIPT_BUCKET;
if (!bucketName) {
    throw new Error('RECEIPT_BUCKET environment variable is not set');
}

Verwenden des globalen Zustands

Lambda führt Ihren statischen Code während der Initialisierungsphase aus, bevor Ihre Funktion zum ersten Mal aufgerufen wird. Ressourcen, die während der Initialisierung erstellt wurden, bleiben zwischen Aufrufen im Speicher, sodass Sie sie nicht jedes Mal neu erstellen müssen, wenn Sie Ihre Funktion aufrufen.

Im Beispielcode befindet sich der S3-Client-Initialisierungscode außerhalb des Handlers. Die Laufzeitumgebung initialisiert den Client, bevor die Funktion ihr erstes Ereignis verarbeitet, und der Client bleibt für die Wiederverwendung bei allen Aufrufen verfügbar.

Bewährte Codemethoden für Node.js-Lambda-Funktionen

Beachten Sie beim Erstellen von Lambda-Funktionen die folgenden Richtlinien: