在 Node.js 中 Lambda 義函數處理常式

Lambda 函數處理常式是您的函數程式碼中處理事件的方法。當有人呼叫您的函數時，Lambda 會執行處理常式方法。函數會執行，直到處理常式傳回回應、結束或逾時為止。

Node.js 處理常式基礎

下列範例函數會記錄事件物件的內容，並傳回記錄檔的位置。

注意

此頁面會顯示 CommonJS 和 ES 模組處理常式的範例。若要了解這兩個處理常式類型之間的差異，請參閱 將函數處理常式指定為 ES 模組。

ES module handler

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

CommonJS module handler

exports.handler = async function (event, context) {
  console.log("EVENT: \n" + JSON.stringify(event, null, 2));
  return context.logStreamName;
};

當您設定函數時，處理常式的設定值就是檔案名稱，以及已匯出之處理常式方法的名稱，並且以點分隔。主控台中的預設值，例如在此指南中為 index.handler。這表示 handler 方法是透過 index.js 檔案匯出的。

執行程序會將引數傳送至處理常式方法。第一個引數是 event 物件，其中包含來自叫用端的資訊。呼叫程式呼叫 Invoke 時，會將這項資訊傳遞為JSON格式化的字串，而執行階段會將它轉換為物件。當 AWS 服務叫用您的函數時，事件結構會因服務而異。

第二個引數為 內容物件，其中包含有關呼叫、函式和執行環境的資訊。在上述範例中，該函式從內容物件取得日誌串流的名稱並傳回給叫用端。

您也可以使用回呼引數 (此引數是您在非同步處理常式中呼叫來傳送回應的函數)。建議您使用非同步/等待 (而不是回呼)。非同步/等待改善了可讀性、錯誤處理及效率。如需有關非同步/等待和回呼之間差異的詳細資訊，請參閱 使用回呼。

命名

當您設定函數時，處理常式的設定值就是檔案名稱，以及已匯出之處理常式方法的名稱，並且以點分隔。在控制台中創建的功能和本指南中的示例的默認值是index.handler。這表示從index.js或index.mjs檔案匯出的handler方法。

如果要在主控台中使用不同檔案名稱或函數處理常式名稱建立函數，您必須編輯預設處理常式名稱。

變更函數處理常式名稱的方式 (主控台)

1. 開啟 Lambda 主控台的函數頁面，然後選擇您的函數。

2. 選擇 程式碼 索引標籤。

3. 向下捲動至執行時間設定窗格，並選擇編輯。

4. 在處理常式中，輸入函數處理常式的新名稱。

5. 選擇 Save (儲存)。

使用 async/await

如果您的程式碼執行非同步任務，請使用非同步/等待模式，以確保處理常式能順利完成執行。非同步/等待是一種在 Node.js 中撰寫非同步程式碼的簡潔可讀模式，無需巢狀回呼或鏈結承諾。您可以透過非同步/等待模式撰寫讀起來像同步程式碼的程式碼，同時仍維持非同步和非封鎖的特性。

async 關鍵字會將函數標記為非同步，且 await 關鍵字會暫停函數的執行，直到 Promise 獲得解決為止。

注意

請務必等待非同步事件完成。如果函數在非同步事件完成之前傳回，則函數可能會失敗或導致應用程式中的非預期行為。當 forEach 迴圈包含非同步事件時，可能會發生這種情況。forEach 迴圈期望一個同步呼叫。如需詳細資訊，請參閱陣列. 原型。 forEach（）在 Mozilla 文檔中。

ES module handler

範例 — HTTP 請求異步/等待

const url = "https://aws.amazon.com/";

export const handler = async(event) => {
    try {
        // fetch is available in Node.js 18 and later runtimes
        const res = await fetch(url);
        console.info("status", res.status);
        return res.status;
    }
    catch (e) {
        console.error(e);
        return 500;
    }
};

CommonJS module handler

範例 — HTTP 請求異步/等待

const https = require("https");
let url = "https://aws.amazon.com/";

exports.handler = async function (event) {
  let statusCode;
  await new Promise(function (resolve, reject) {
    https.get(url, (res) => {
        statusCode = res.statusCode;
        resolve(statusCode);
      }).on("error", (e) => {
        reject(Error(e));
      });
  });
  console.log(statusCode);
  return statusCode;
};

下一個範例會使用非同步/等待來列出您的 Amazon Simple Storage Service 儲存貯體。

注意

使用此範例前，請確定函數的執行角色具有 Amazon S3 讀取許可。

ES module handler

範例 - AWS SDK v3 與異步/等待

此範例使用 AWS SDK for JavaScript v3，它可在以後的執行階段中nodejs18.x使用。

import {S3Client, ListBucketsCommand} from '@aws-sdk/client-s3';
const s3 = new S3Client({region: 'us-east-1'});
   
export const handler = async(event) => {
  const data = await s3.send(new ListBucketsCommand({}));
  return data.Buckets;
        
};

CommonJS module handler

範例 - AWS SDK v3 與異步/等待

此範例使用 AWS SDK for JavaScript v3，它可在以後的執行階段中nodejs18.x使用。

const { S3Client, ListBucketsCommand } = require('@aws-sdk/client-s3');
const s3 = new S3Client({ region: 'us-east-1' });

exports.handler = async (event) => {
  const data = await s3.send(new ListBucketsCommand({}));
  return data.Buckets;
};

使用回呼

建議您使用 非同步/等待 來宣告函數處理常式，而不是使用回呼。非同步/等待是更好的選擇，以下列出幾項原因：

• 可讀性： 非同步/等待程式碼比回呼程式碼更容易閱讀和理解，回呼程式碼可能很快就會變得難以理解，並引發回呼地獄。

• 偵錯和錯誤處理： 回呼型程式碼的偵錯工作難度可能不低。呼叫堆疊可能會變得難以理解，且可能會很容易接受錯誤。您可以透過非同步/等待使用 try/catch 區塊來處理錯誤。

• 效率： 回呼通常需要在程式碼的不同部分之間進行切換。非同步/等待可以減少切換環境的次數，進而產生更有效率的程式碼。

在處理常式中使用回呼時，函數將繼續執行，直到 事件迴圈 清空或函數逾時為止。直到完成所有的事件迴圈任務，回應才會傳送到叫用端。如果函式逾時，便會傳回錯誤。您可以設定內容，將執行階段設定為立即傳送回應。 callbackWaitsForEmptyEventLoop假的。

回乎函式需要兩個引數，一個 Error 和回應。回應物件必須與 JSON.stringify 相容。

下列範例函數會檢查 a，URL並將狀態碼傳回給呼叫者。

ES module handler

範例 -HTTP 請求與回調

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

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

CommonJS module handler

範例 -HTTP 請求與回調

const https = require("https");
let url = "https://aws.amazon.com/";

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

在下一個範例中，Amazon S3 的回應會在可用時立即傳回給啟動程式。逾時的事件迴圈已凍結，並繼續執行下一個時間叫用的函式。

注意

使用此範例前，請確定函數的執行角色具有 Amazon S3 讀取許可。

ES module handler

範例 AWS SDK— 與 callbackWaitsFor EmptyEventLoop

此範例使用 AWS SDK for JavaScript v3，它可在以後的執行階段中nodejs18.x使用。

import AWS from "@aws-sdk/client-s3";
const s3 = new AWS.S3({});

export const handler = function (event, context, callback) {
  context.callbackWaitsForEmptyEventLoop = false;
  s3.listBuckets({}, callback);
  setTimeout(function () {
    console.log("Timeout complete.");
  }, 5000);
};

CommonJS module handler

範例 AWS SDK— 與 callbackWaitsFor EmptyEventLoop

此範例使用 AWS SDK for JavaScript v3，它可在以後的執行階段中nodejs18.x使用。

const AWS = require("@aws-sdk/client-s3");
const s3 = new AWS.S3({});

exports.handler = function (event, context, callback) {
  context.callbackWaitsForEmptyEventLoop = false;
  s3.listBuckets({}, callback);
  setTimeout(function () {
    console.log("Timeout complete.");
  }, 5000);
};

Node.js 函數的程式碼最佳實務

在建置 Lambda 函數時，請遵循下列清單中的準則，以使用最佳程式碼撰寫實務：

• 區隔 Lambda 處理常式與您的核心邏輯。能允許您製作更多可測單位的函式。在 Node.js 時，看起來會是這個樣子：

  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
  }

• 控制函數部署套件內的相依性。 AWS Lambda 執行環境包含許多程式庫。對於 Node.js 和 Python 執行階段，這些執行階段包括. AWS SDKs 若要啟用最新的一組功能與安全更新，Lambda 會定期更新這些程式庫。這些更新可能會為您的 Lambda 函數行為帶來細微的變更。若要完全掌控您函式所使用的相依性，請利用部署套件封裝您的所有相依性。

• 最小化依存項目的複雜性。偏好更簡易的框架，其可快速在執行環境啟動時載入。

• 將部署套件最小化至執行時間所必要的套件大小。這能減少您的部署套件被下載與呼叫前解壓縮的時間。

• 請利用執行環境重新使用來改看函式的效能。初始化函數處理常式之外的SDK用戶端和資料庫連線，並在/tmp目錄本機快取靜態資產。由您函式的相同執行個體處理的後續叫用可以重複使用這些資源。這可藉由減少函數執行時間來節省成本。

  若要避免叫用間洩漏潛在資料，請不要使用執行環境來儲存使用者資料、事件，或其他牽涉安全性的資訊。如果您的函式依賴無法存放在處理常式內記憶體中的可變狀態，請考慮為每個使用者建立個別函式或個別函式版本。

• 使用 Keep-Alive 指令維持持續連線的狀態。Lambda 會隨著時間的推移清除閒置連線。叫用函數時嘗試重複使用閒置連線將導致連線錯誤。若要維護持續連線，請使用與執行階段相關聯的 keep-alive (保持啟用) 指令。如需範例，請參閱在 Node.js 中重複使用 Keep-Alive 的連線。

• 使用環境變數將操作參數傳遞給您的函數。例如，如果您正在寫入到 Amazon S3 儲存貯體，而非對您正在寫入的儲存貯體名稱進行硬式編碼，請將儲存貯體名稱設定為環境變數。

• 避免在 Lambda 函數中使用遞迴叫用，函數會自行叫用或啟動可能再次叫用函數的程序。這會導致意外的函式呼叫量與升高的成本。如果您看到非預期的叫用量，請在更新程式碼時0立即將保留並行的函數設定為限制函數的所有叫用。

• 請勿在 Lambda 函數程式碼中使用非公開APIs的非公開文件。對於 AWS Lambda 受管執行階段，Lambda 會定期將安全性和功能更新套用至 Lambda 的內部APIs。這些內部API更新可能向後不兼容，導致意外後果，例如，如果您的函數依賴於這些非公共功能，則會導致調用失敗。APIs如需公開可用的清單，請API參閱參考資料APIs。

• 撰寫等冪程式碼。為函數撰寫等冪程式碼可確保採用相同方式來處理重複事件。程式碼應正確驗證事件並正常處理重複的事件。如需詳細資訊，請參閱 How do I make my Lambda function idempotent? (如何讓 Lambda 函數等冪？)。