定义采用 Java 的 Lambda 函数处理程序

Lambda 函数处理程序是函数代码中处理事件的方法。当调用函数时，Lambda 运行处理程序方法。您的函数会一直运行，直到处理程序返回响应、退出或超时。

本页介绍如何使用 Java Lambda 函数处理程序，包括项目设置选项、命名约定和最佳实践。本页还包括 Java Lambda 函数的示例，该函数接收订单信息，生成文本文件收据，然后将此文件放入 Amazon Simple Storage Service（S3）存储桶中。有关如何在编写函数后部署函数的信息，请参阅使用 .zip 或 JAR 文件归档部署 Java Lambda 函数或使用容器镜像部署 Java Lambda 函数。

设置 Java 处理程序项目

使用 Java Lambda 函数时，该过程涉及编写代码、对其进行编译，以及将编译后的构件部署到 Lambda。您可以通过多种方式初始化 Java Lambda 项目。例如，您可以使用 Lambda 函数的 Maven Archetype 等工具、AWS SAM CLI sam init 命令，甚至可以在您首选的 IDE（如 IntelliJ IDEA 或 Visual Studio Code）中使用标准 Java 项目设置。或者，您也可以手动创建所需的文件结构。

典型的 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 时，请务必指定包含 Lambda 在调用过程中应调用的主处理程序方法的 Java 类。

示例 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、Integer、=List 或 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 时，请按以下格式在函数配置中指定主处理程序：

对于未实现 RequestHandler 或 RequestStreamHandler 接口的 Java Lambda 函数，您可以使用任何处理程序名称。将函数部署到 Lambda 时，请按以下格式在函数配置中指定主处理程序：

定义和访问输入事件对象

JSON 是 Lambda 函数最常用且最标准的输入格式。在此示例中，该函数需要类似于下方的输入：

{
    "order_id": "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 对象。然后，您可以访问该对象的字段。例如，event.orderId 从原始输入中检索 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 函数信息。

在处理程序中使用 AWS SDK for Java v2

通常，您将使用 Lambda 函数与其他 AWS 资源进行交互或对其进行更新。与此类资源最简单的交互方法是使用 AWS SDK for Java v2。

要向函数添加 SDK 依赖项，请将其添加到 build.gradle（Gradle）或 pom.xml 文件（Maven）。建议仅添加函数所需的库。在上述示例代码中，我们使用了 software.amazon.awssdk.services.s3 库。在 Gradle 中，您可以通过在 build.gradle 的依赖项部分添加以下行来添加此依赖项：

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

在 Maven 中，在 pom.xml 的 <dependencies> 部分添加以下行：

    <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 客户端初始化代码位于主处理程序方法之外。运行时会在函数处理其第一个事件之前初始化客户端，这可能会导致更长的处理时间。后续事件的处理速度则要快得多，因为 Lambda 不需要再次初始化客户端。

Java Lambda 函数的代码最佳实践

在构建 Lambda 函数时，请遵循以下列表中的指南，采用最佳编码实践：