Tentukan pengendali fungsi Lambda di Node.js

Handler fungsi Lambda Anda adalah metode dalam kode fungsi Anda yang memproses peristiwa. Saat fungsi Anda diaktifkan, Lambda menjalankan metode handler. Fungsi Anda berjalan sampai handler mengembalikan respons, keluar, atau batas waktu.

Halaman ini menjelaskan cara bekerja dengan penangan fungsi Lambda di Node.js, termasuk opsi untuk penyiapan proyek, konvensi penamaan, dan praktik terbaik. Halaman ini juga menyertakan contoh fungsi Node.js Lambda yang mengambil informasi tentang pesanan, menghasilkan tanda terima file teks, dan menempatkan file ini dalam bucket Amazon Simple Storage Service (Amazon S3). Untuk informasi tentang cara menerapkan fungsi Anda setelah menulisnya, lihat Terapkan fungsi Node.js Lambda dengan arsip file.zip atauTerapkan fungsi Node.js Lambda dengan gambar kontainer.

Menyiapkan proyek Node.js handler Anda

Ada beberapa cara untuk menginisialisasi proyek Node.js Lambda. Misalnya, Anda dapat membuat Node.js proyek standar menggunakannpm, membuat AWS SAM aplikasi, atau membuat AWS CDK aplikasi.

Untuk membuat proyek menggunakannpm:

npm init

Perintah ini menginisialisasi proyek Anda dan menghasilkan package.json file yang mengelola metadata dan dependensi proyek Anda.

Kode fungsi Anda berada di .mjs JavaScript file .js atau. Dalam contoh berikut, kami menamai file ini index.mjs karena menggunakan pengendali modul ES. Lambda mendukung modul ES dan penangan CommonJS. Untuk informasi selengkapnya, lihat Modul CommonJS dan ES.

Proyek fungsi Node.js Lambda yang khas mengikuti struktur umum ini:

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

Contoh kode fungsi Node.js Lambda

Contoh kode fungsi Lambda berikut mengambil informasi tentang pesanan, menghasilkan tanda terima file teks, dan menempatkan file ini dalam bucket Amazon S3.

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

index.mjsFile ini berisi bagian-bagian kode berikut:

Agar fungsi ini berfungsi dengan baik, peran pelaksanaannya harus memungkinkan s3:PutObject tindakan. Juga, pastikan Anda mendefinisikan variabel RECEIPT_BUCKET lingkungan. Setelah pemanggilan berhasil, bucket Amazon S3 harus berisi file tanda terima.

Modul CommonJS dan ES

Node.js mendukung dua sistem modul: modul CommonJS dan ECMAScript (modul ES). Lambda merekomendasikan penggunaan modul ES karena mendukung menunggu tingkat atas, yang memungkinkan tugas asinkron diselesaikan selama inisialisasi lingkungan eksekusi.

Node.js memperlakukan file dengan ekstensi nama .cjs file sebagai modul CommonJS sementara .mjs ekstensi menunjukkan modul ES. Secara default, Node.js memperlakukan file dengan ekstensi nama .js file sebagai modul CommonJS. Anda dapat Node.js mengonfigurasi untuk memperlakukan .js file sebagai modul ES dengan menentukan seperti module dalam package.json file fungsi. type Anda dapat mengonfigurasi Node.js di Lambda untuk mendeteksi secara otomatis apakah .js file harus diperlakukan sebagai CommonJS atau sebagai modul ES dengan menambahkan —experimental-detect-module flag ke variabel NODE_OPTIONS lingkungan. Untuk informasi selengkapnya, lihat Node.js Fitur eksperimental.

Contoh berikut menunjukkan penangan fungsi yang ditulis menggunakan modul ES dan modul CommonJS. Contoh yang tersisa di halaman ini semua menggunakan modul ES.

Node.js inisialisasi

Node.js menggunakan I/O model non-pemblokiran yang mendukung operasi asinkron yang efisien menggunakan loop peristiwa. Misalnya, jika Node.js membuat panggilan jaringan, fungsi terus memproses operasi lain tanpa memblokir respons jaringan. Ketika respons jaringan diterima, itu ditempatkan ke dalam antrian panggilan balik. Tugas dari antrian diproses saat tugas saat ini selesai.

Lambda merekomendasikan penggunaan menunggu tingkat atas sehingga tugas asinkron yang dimulai selama inisialisasi lingkungan eksekusi selesai selama inisialisasi. Tugas asinkron yang tidak selesai selama inisialisasi biasanya dijalankan selama pemanggilan fungsi pertama. Hal ini dapat menyebabkan perilaku atau kesalahan yang tidak terduga.

Misalnya, inisialisasi fungsi Anda mungkin membuat panggilan jaringan untuk mengambil parameter dari AWS Parameter Store. Jika tugas ini tidak selesai selama inisialisasi, nilainya mungkin nol selama pemanggilan. Mungkin juga ada penundaan antara inisialisasi dan pemanggilan yang dapat memicu kesalahan dalam operasi yang sensitif terhadap waktu. Secara khusus, panggilan AWS layanan dapat bergantung pada tanda tangan permintaan yang sensitif terhadap waktu, yang mengakibatkan kegagalan panggilan layanan jika panggilan tidak selesai selama fase inisialisasi.

Menyelesaikan tugas selama inisialisasi biasanya meningkatkan kinerja cold start, dan pertama kali memanggil kinerja saat menggunakan Provisioned Concurrency. Untuk informasi lebih lanjut, lihat posting blog kami Menggunakan modul Node.js ES dan menunggu tingkat atas. AWS Lambda

Konvensi penamaan handler

Saat Anda mengonfigurasi fungsi, nilai pengaturan Handler adalah nama file dan nama metode handler yang diekspor, dipisahkan oleh titik. Default untuk fungsi yang dibuat di konsol dan untuk contoh dalam panduan ini adalahindex.handler. Ini menunjukkan handler metode yang diekspor dari index.mjs file index.js atau.

Jika Anda membuat fungsi di konsol menggunakan nama file atau nama pengendali fungsi yang berbeda, Anda harus mengedit nama handler default.

Mendefinisikan dan mengakses objek peristiwa input

JSON adalah format input yang paling umum dan standar untuk fungsi Lambda. Dalam contoh ini, fungsi mengharapkan input yang mirip dengan berikut ini:

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

Saat bekerja dengan fungsi Lambda di Node.js, Anda dapat menentukan bentuk yang diharapkan dari peristiwa input menggunakan anotasi JSDoc. Dalam contoh ini, kita mendefinisikan struktur input dalam komentar JSDoc handler:

/**
 * 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
 */

Setelah Anda menentukan jenis ini dalam komentar JSDoc Anda, Anda dapat mengakses bidang objek acara langsung dalam kode Anda. Misalnya, event.order_id mengambil nilai order_id dari input asli.

Pola handler yang valid untuk Node.js fungsi

Sebaiknya gunakan untuk mendeklar async/await asikan pengendali fungsi alih-alih menggunakan callback. Async/await adalah cara ringkas dan mudah dibaca untuk menulis kode asinkron, tanpa perlu panggilan balik bersarang atau janji rantai. Dengan async/await, Anda dapat menulis kode yang dibaca seperti kode sinkron, sementara masih asinkron dan non-pemblokiran.

penangan fungsi asinkron (disarankan)

asyncKata kunci menandai fungsi sebagai asinkron, dan await kata kunci menjeda eksekusi fungsi sampai a Promise diselesaikan. Handler menerima argumen berikut:

Berikut adalah tanda tangan yang valid untuk async/await pola:

export const handler = async (event) => { };

export const handler = async (event, context) => { };

Penangan fungsi sinkron

Jika fungsi Anda tidak melakukan tugas asinkron apa pun, Anda dapat menggunakan pengendali fungsi sinkron, menggunakan salah satu tanda tangan fungsi berikut:

export const handler = (event) => { };

export const handler = (event, context) => { };

Penangan fungsi streaming respons

Lambda mendukung streaming respons dengan Node.js. Penangan fungsi streaming respons menggunakan awslambda.streamifyResponse() dekorator dan mengambil 3 parameter:event,responseStream, dan. context Tanda tangan fungsi adalah:

export const handler = awslambda.streamifyResponse(async (event, responseStream, context) => { });

Untuk informasi selengkapnya, lihat Streaming Respons untuk Fungsi Lambda.

Callback-based penangan fungsi

Callback-based function handler harus menggunakan argumen event, context, dan callback. Contoh:

export const handler = (event, context, callback) => { };

Fungsi callback mengharapkan respon Error dan respon, yang harus JSON-serializable ada. Fungsi terus dijalankan sampai event loop kosong atau fungsi habis waktu. Respons tidak dikirimkan ke invoker hingga semua tugas loop peristiwa selesai. Jika waktu fungsi habis, kesalahan akan dikembalikan. Anda dapat mengonfigurasi runtime untuk mengirim respons segera dengan menyetel context.call WaitsForEmptyEventLoop back ke false.

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

Menggunakan SDK untuk JavaScript v3 di handler Anda

Seringkali, Anda akan menggunakan fungsi Lambda untuk berinteraksi dengan atau membuat pembaruan ke AWS sumber daya lain. Cara paling sederhana untuk berinteraksi dengan sumber daya ini adalah dengan menggunakan AWS SDK for JavaScript. Semua runtime Lambda Node.js yang didukung termasuk SDK untuk JavaScript versi 3.

Namun, kami sangat menyarankan Anda menyertakan klien AWS SDK yang Anda butuhkan dalam paket penerapan Anda. Ini memaksimalkan kompatibilitas mundur selama pembaruan runtime Lambda di masa mendatang. Hanya mengandalkan SDK yang AWS CloudFormation disediakan runtime ketika Anda tidak dapat menyertakan paket tambahan (misalnya, saat menggunakan editor kode konsol Lambda atau kode sebaris dalam template).

Untuk menambahkan dependensi SDK ke fungsi Anda, gunakan npm install perintah untuk klien SDK tertentu yang Anda butuhkan. Dalam kode contoh, kami menggunakan klien Amazon S3. Tambahkan dependensi ini dengan menjalankan perintah berikut di direktori yang berisi package.json file Anda:

npm install @aws-sdk/client-s3

Dalam kode fungsi, impor klien dan perintah yang Anda butuhkan, seperti contoh fungsi menunjukkan:

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

Kemudian, inisialisasi klien Amazon S3:

const s3Client = new S3Client();

Dalam contoh ini, kami menginisialisasi klien Amazon S3 kami di luar fungsi handler utama untuk menghindari keharusan menginisialisasi setiap kali kami memanggil fungsi kami. Setelah menginisialisasi klien SDK, Anda kemudian dapat menggunakannya untuk membuat panggilan API untuk AWS layanan tersebut. Kode contoh memanggil tindakan Amazon S3 PutObject API sebagai berikut:

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

Mengakses variabel lingkungan

Dalam kode handler Anda, Anda dapat mereferensikan variabel lingkungan apa pun dengan menggunakanprocess.env. Dalam contoh ini, kita mereferensi RECEIPT_BUCKET kan variabel lingkungan yang ditentukan menggunakan baris kode berikut:

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

Menggunakan status global

Lambda menjalankan kode statis Anda selama fase inisialisasi sebelum memanggil fungsi Anda untuk pertama kalinya. Sumber daya yang dibuat selama inisialisasi tetap berada di memori di antara pemanggilan, sehingga Anda dapat menghindari keharusan membuatnya setiap kali Anda memanggil fungsi Anda.

Dalam kode contoh, kode inisialisasi klien S3 berada di luar handler. Runtime menginisialisasi klien sebelum fungsi menangani peristiwa pertamanya, dan klien tetap tersedia untuk digunakan kembali di semua pemanggilan.

Praktik terbaik kode untuk fungsi Node.js Lambda

Ikuti panduan ini saat membangun fungsi Lambda:

Manfaatkan penggunaan kembali lingkungan eksekusi untuk meningkatkan kinerja fungsi Anda. Inisialisasi klien SDK dan koneksi basis data di luar fungsi handler, dan lakukan caching aset statis secara lokal di direktori /tmp. Invokasi selanjutnya yang diproses oleh instans yang sama dari fungsi Anda dapat menggunakan kembali sumber daya ini. Ini menghemat biaya dengan mengurangi waktu pengoperasian fungsi.

Untuk menghindari potensi kebocoran data di seluruh invokasi, jangan menggunakan lingkungan eksekusi untuk menyimpan data pengguna, peristiwa, atau informasi lainnya implikasi keamanan. Jika fungsi Anda bergantung pada status yang dapat disenyapkan yang tidak dapat disimpan dalam memori di dalam handler, pertimbangkan untuk membuat fungsi terpisah atau versi terpisah dari fungsi untuk setiap pengguna.

Gunakan direktif keep-alive untuk mempertahankan koneksi yang persisten. Lambda membersihkan koneksi idle dari waktu ke waktu. Mencoba menggunakan ulang koneksi idle saat mengidentifikasi suatu fungsi akan menyebabkan kesalahan koneksi. Untuk mempertahankan koneksi yang persisten, gunakan arahan tetap aktif yang berkaitan dengan runtime Anda. Sebagai contoh, lihat Menggunakan Kem bali Koneksi dengan Keep-Alive in Node.js.

Gunakan variabel lingkungan untuk meneruskan parameter operasional ke fungsi Anda. Misalnya, jika Anda ingin menulis ke bucket Amazon S3 alih-alih melakukan hard-coding nama bucket yang Anda tulis, konfigurasikan nama bucket sebagai variabel lingkungan.

Hindari menggunakan pemanggilan rekursif dalam fungsi Lambda Anda, di mana fungsi memanggil dirinya sendiri atau memulai proses yang dapat memanggil fungsi lagi. Hal ini dapat menyebabkan volume invokasi fungsi yang tidak diinginkan dan peningkatan biaya. Jika Anda melihat volume pemanggilan yang tidak diinginkan, setel fungsi reservasi konkurensi ke 0 segera untuk membatasi semua pemanggilan ke fungsi, saat Anda memperbarui kode.

Jangan gunakan API non-publik yang tidak terdokumentasi dalam kode fungsi Lambda Anda. Untuk runtime AWS Lambda terkelola, Lambda secara berkala menerapkan pembaruan keamanan dan fungsional ke API internal Lambda. Pembaruan API internal ini mungkin tidak kompatibel ke belakang, yang menyebabkan konsekuensi yang tidak diinginkan seperti kegagalan pemanggilan jika fungsi Anda memiliki ketergantungan pada API non-publik ini. Lihat referensi API untuk daftar API yang tersedia untuk umum.

Tulis kode idempotent. Menulis kode idempotent untuk fungsi Anda memastikan bahwa peristiwa duplikat ditangani dengan cara yang sama. Kode Anda harus memvalidasi peristiwa dengan benar dan menangani peristiwa duplikat dengan anggun. Untuk informasi lebih lanjut, lihat Bagaimana cara membuat fungsi Lambda saya idempoten? .