在 Java 中定義 Lambda 函數處理常式

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

此頁面說明如何在 Java 中使用 Lambda 函數處理常式，包括專案設定、命名慣例和最佳實務的選項。此頁面也包含 Java Lambda 函數的範例，該函數會取得訂單的相關資訊、產生文字檔案接收，並將此檔案放入 Amazon Simple Storage Service (Amazon S3) 儲存貯體。如需編寫函數後如何部署函數的詳細資訊，請參閱使用 .zip 或 JAR 封存檔部署 Java Lambda 函數或使用容器映像部署 Java Lambda 函數。

設定您的 Java 處理常式專案

在 Java 中使用 Lambda 函數時，程序涉及編寫程式碼、編譯程式碼，以及將編譯的成品部署至 Lambda。您可以透過各種方式初始化 Java Lambda 專案。例如，您可以使用 Maven Archetype for Lambda 函數、CLI sam init AWS SAM 命令，或甚至是您偏好 IDE 中的標準 Java 專案設定等工具，例如 IntelliJ IDEA 或 Visual Studio Code。 https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-init.html或者，您可以手動建立所需的檔案結構。

典型的 Java Lambda 函數專案遵循此一般結構：

/project-root
    └ src
        └ main
            └ java
                └ example
                    └ OrderHandler.java (contains main handler)
                    └ <other_supporting_classes>
     └ build.gradle OR pom.xml

您可以使用 Maven 或 Gradle 來建置專案並管理相依性。

函數的主要處理常式邏輯位於 src/main/java/example目錄下的 Java 檔案中。在此頁面上的範例中，我們將此檔案命名為 OrderHandler.java。除了此檔案之外，您可以視需要包含其他 Java 類別。將函數部署至 Lambda 時，請務必指定 Java 類別，其中包含 Lambda 應在調用期間調用的主要處理常式方法。

Java Lambda 函數程式碼範例

下列範例 Java 21 Lambda 函數程式碼會取得訂單的相關資訊、產生文字檔案接收，並將此檔案放入 Amazon S3 儲存貯體。

package example;

import com.amazonaws.services.lambda.runtime.Context;
import com.amazonaws.services.lambda.runtime.RequestHandler;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;

import java.nio.charset.StandardCharsets;

/**
 * Lambda handler for processing orders and storing receipts in S3.
 */
public class OrderHandler implements RequestHandler<OrderHandler.Order, String> {

    private static final S3Client S3_CLIENT = S3Client.builder().build();

    /**
     * Record to model the input event.
     */
    public record Order(String orderId, double amount, String item) {}

    @Override
    public String handleRequest(Order event, Context context) {
        try {
            // Access environment variables
            String bucketName = System.getenv("RECEIPT_BUCKET");
            if (bucketName == null || bucketName.isEmpty()) {
                throw new IllegalArgumentException("RECEIPT_BUCKET environment variable is not set");
            }

            // Create the receipt content and key destination
            String receiptContent = String.format("OrderID: %s\nAmount: $%.2f\nItem: %s",
                    event.orderId(), event.amount(), event.item());
            String key = "receipts/" + event.orderId() + ".txt";

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

            context.getLogger().log("Successfully processed order " + event.orderId() +
                    " and stored receipt in S3 bucket " + bucketName);
            return "Success";

        } catch (Exception e) {
            context.getLogger().log("Failed to process order: " + e.getMessage());
            throw new RuntimeException(e);
        }
    }

    private void uploadReceiptToS3(String bucketName, String key, String receiptContent) {
        try {
            PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .build();

            // Convert the receipt content to bytes and upload to S3
            S3_CLIENT.putObject(putObjectRequest, RequestBody.fromBytes(receiptContent.getBytes(StandardCharsets.UTF_8)));
        } catch (S3Exception e) {
            throw new RuntimeException("Failed to upload receipt to S3: " + e.awsErrorDetails().errorMessage(), e);
        }
    }
}

此 OrderHandler.java 檔案包含以下程式碼區段：

plugins {
    id 'java'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.amazonaws:aws-lambda-java-core:1.2.3'
    implementation 'software.amazon.awssdk:s3:2.28.29'
    implementation 'org.slf4j:slf4j-nop:2.0.16'
}

task buildZip(type: Zip) {
    from compileJava
    from processResources
    into('lib') {
        from configurations.runtimeClasspath
    }
}

java {
    sourceCompatibility = JavaVersion.VERSION_21
    targetCompatibility = JavaVersion.VERSION_21
}

build.dependsOn buildZip

若要讓此函數正常運作，其執行角色必須允許 s3:PutObject動作。此外，請確保定義 RECEIPT_BUCKET 環境變數。成功調用後，Amazon S3 儲存貯體應包含收據檔案。

Java 處理常式的有效類別定義

若要定義您的類別，aws-lambda-java-core 程式庫會定義兩個處理常式方法的界面。使用提供的界面來簡化處理常式組態，並在編譯時驗證方法簽章。

RequestHandler 介面是一個一般類型，它有兩個參數：輸入類型和輸出類型。兩種類型都必須是物件。在此範例中，我們的 OrderHandler類別實作 RequestHandler<OrderHandler.Order, String>。輸入類型是我們在 類別中定義的Order記錄，輸出類型為 String。

public class OrderHandler implements RequestHandler<OrderHandler.Order, String> {
    ...
}

當您使用此界面時，Java 執行時間會將事件還原序列化為具有輸入類型的物件，並將輸出序列化為文字。當內建序列化與您的輸入和輸出類型一同作業時，請使用此介面。

若要使用您自己的序列化，您可以實作 RequestStreamHandler 界面。透過此介面，Lambda 會將處理常式傳遞給一個輸入串流和輸出串流。處理常式會從輸入串流讀取位元組，寫入到輸出串流，並傳回 void 值。如需使用 Java 21 執行時間的範例，請參閱 HandlerStream.java。

如果您只在 Java 函數 中使用基本和一般類型 （即 String=List、、 Integer或 Map)，則不需要實作 界面。例如，如果您的函數接受Map<String, String>輸入並傳回 String，則類別定義和處理常式簽章可能如下所示：

public class ExampleHandler {
    public String handleRequest(Map<String, String> input, Context context) {
        ...
    }
}

此外，當您不實作界面時，內容物件是選用的。例如，您的類別定義和處理常式簽章可能如下所示：

public class NoContextHandler {
   public String handleRequest(Map<String, String> input) {
        ...
   }
}

處理常式命名慣例

對於 Java 中的 Lambda 函數，如果您實作 RequestHandler或 RequestStreamHandler 介面，您的主要處理常式方法必須命名為 handleRequest。此外，請在您的handleRequest方法上方包含 @Override標籤。當您將函數部署到 Lambda 時，請以下列格式在函數的組態中指定主要處理常式：

對於 Java 中未實作 RequestHandler或 RequestStreamHandler界面的 Lambda 函數，您可以使用處理常式的任何名稱。當您將函數部署到 Lambda 時，請以下列格式在函數的組態中指定主要處理常式：

定義和存取輸入事件物件

JSON 是 Lambda 函數最常見的標準輸入格式。在此範例中，函數預期輸入類似以下內容：

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

在 Java 17 或更新版本中使用 Lambda 函數時，您可以將預期輸入事件的形狀定義為 Java 記錄。在此範例中，我們在 OrderHandler類別中定義記錄來代表Order物件：

public record Order(String orderId, double amount, String item) {}

此記錄符合預期的輸入形狀。定義記錄之後，您可以撰寫處理常式簽章，該簽章採用符合記錄定義的 JSON 輸入。Java 執行時間會自動將此 JSON 還原序列化為 Java 物件。然後，您可以存取物件的欄位。例如，使用 orderId 可以從原始輸入擷取 event.orderId 的值。

其他輸入事件類型

Java 中的 Lambda 函數有許多可能的輸入事件：

存取和使用 Lambda 內容物件

Lambda 內容物件 包含有關調用、函數以及執行環境的資訊。在此範例中，內容物件的類型為 com.amazonaws.services.lambda.runtime.Context，且是主要處理常式函數的第二個引數。

public String handleRequest(Order event, Context context) {
    ...
}

如果您的類別實作 RequestHandler 或 RequestStreamHandler 介面，則內容物件是必要的引數。否則，內容物件是選用的。如需有效接受處理常式簽章的詳細資訊，請參閱 Java 處理常式的有效類別定義。

如果您使用 AWS SDK 呼叫其他 服務，在幾個關鍵區域中需要內容物件。例如，若要產生 Amazon CloudWatch 的函數日誌，您可以使用 context.getLogger()方法取得LambdaLogger物件以供記錄。在此範例中，如果處理因任何原因失敗，我們可以使用記錄器記錄錯誤訊息：

context.getLogger().log("Failed to process order: " + e.getMessage());

在記錄之外，您也可以使用內容物件進行函數監控。如需內容物件的詳細資訊，請參閱使用 Lambda 內容物件擷取 Java 函數資訊。

在處理常式中使用適用於 Java 的 AWS SDK v2

通常，您將使用 Lambda 函數與其他 AWS 資源互動或進行更新。與這些資源互動的最簡單方法是使用適用於 Java v2 的 AWS 開發套件。

若要將 SDK 相依性新增至函數，請在 build.gradle Gradle 的 中新增這些相依性，或將它們新增至 Maven 的 pom.xml 檔案。建議您只新增函數所需的程式庫。在先前的範例程式碼中，我們使用 software.amazon.awssdk.services.s3程式庫。在 Gradle 中，您可以在 的相依性區段中新增以下行，以新增此相依性build.gradle：

implementation 'software.amazon.awssdk:s3:2.28.29'

在 Maven 中，在 的 <dependencies>區段中新增下列行pom.xml：

    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.28.29</version>
    </dependency>

然後，直接在您的 Java 類別中匯入相依性：

import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.PutObjectRequest;
import software.amazon.awssdk.services.s3.model.S3Exception;

然後，範例程式碼會初始化 Amazon S3 用戶端，如下所示：

private static final S3Client S3_CLIENT = S3Client.builder().build();

在此範例中，我們在主要處理常式函數之外初始化了 Amazon S3 用戶端，以避免每次叫用函數時都要初始化它。初始化 SDK 用戶端之後，您就可以使用它來與其他 AWS 服務互動。此範例程式碼會呼叫 Amazon S3 PutObject API，如下所示：

PutObjectRequest putObjectRequest = PutObjectRequest.builder()
    .bucket(bucketName)
    .key(key)
    .build();

// Convert the receipt content to bytes and upload to S3
S3_CLIENT.putObject(putObjectRequest, RequestBody.fromBytes(receiptContent.getBytes(StandardCharsets.UTF_8)));

存取環境變數

在處理常式程式碼中，您可以使用 System.getenv()方法參考任何環境變數。在此範例中，我們使用以下程式碼來參考定義的 RECEIPT_BUCKET 環境變數：

String bucketName = System.getenv("RECEIPT_BUCKET");
if (bucketName == null || bucketName.isEmpty()) {
    throw new IllegalArgumentException("RECEIPT_BUCKET environment variable is not set");
}

使用全域狀態

在首次調用函數之前，Lambda 會在初始化階段執行靜態程式碼和類別建構函數。在初始化期間建立的資源會在叫用之間保留在記憶體中，因此您可以避免每次叫用函數時都必須建立它們。

在範例程式碼中，S3 用戶端初始化程式碼位於主要處理常式方法之外。執行時間會在函數處理其第一個事件之前初始化用戶端，而且用戶端仍然可用於所有調用。

Java Lambda 函數的程式碼最佳實務

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