# 定义采用 Java 的 Lambda 函数处理程序
Lambda 函数*处理程序*是函数代码中处理事件的方法。当调用函数时，Lambda 运行处理程序方法。您的函数会一直运行，直到处理程序返回响应、退出或超时。
本页介绍如何使用 Java Lambda 函数处理程序，包括项目设置选项、命名约定和最佳实践。本页还包括 Java Lambda 函数的示例，在示例中该函数接收订单信息，生成文本文件收据，然后将此文件放入 Amazon Simple Storage Service（Amazon S3）存储桶中。有关如何在编写函数后部署函数的信息，请参阅[使用 .zip 或 JAR 文件归档部署 Java Lambda 函数](java-package.md)或[使用容器镜像部署 Java Lambda 函数](java-image.md)。
**Topics**
+ [
## 设置 Java 处理程序项目
](#java-handler-setup)
+ [
## 示例 Java Lambda 函数代码
](#java-example-code)
+ [
## Java 处理程序的有效类定义
](#java-handler-signatures)
+ [
## 处理程序命名约定
](#java-example-naming)
+ [
## 定义和访问输入事件对象
](#java-handler-input)
+ [
## 访问和使用 Lambda 上下文对象
](#java-example-context)
+ [
## 在处理程序中使用 AWS SDK for Java v2
](#java-example-sdk-usage)
+ [
## 评估环境变量
](#java-example-envvars)
+ [
## 使用全局状态
](#java-handler-state)
+ [
## Java Lambda 函数的代码最佳实践
](#java-best-practices)
## 设置 Java 处理程序项目
使用 Java Lambda 函数时，该过程涉及编写代码、对其进行编译，以及将编译后的构件部署到 Lambda。您可以通过多种方式初始化 Java Lambda 项目。例如，您可以使用 [Lambda 函数的 Maven Archetype](https://github.com/aws/aws-sdk-java-v2/tree/master/archetypes/archetype-lambda) 等工具、AWS SAM CLI [sam init 命令](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-init.html)，甚至可以在您首选的 IDE（如 IntelliJ IDEA 或 Visual Studio Code）中使用标准 Java 项目设置。或者，您也可以手动创建所需的文件结构。
典型的 Java Lambda 函数项目遵循以下一般结构：
```
/project-root
└ src
└ main
└ java
└ example
└ OrderHandler.java (contains main handler)
└
└ 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 存储桶中。
**Example `OrderHandler.java` Lambda 函数**
```
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 {
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` 文件包含以下代码部分：
+ `package example`：在 Java 中，此部分可以是任何内容，但必须与项目的目录结构相匹配。在这里，我们之所以使用 `package example`，是因为目录结构是 `src/main/java/example`。
+ `import` 语句：使用这些语句可导入 Lambda 函数所需的 Java 类。
+ `public class OrderHandler ...`：此部分定义您的 Java 类，并且必须是[有效的类定义](#java-handler-signatures)。
+ `private static final S3Client S3_CLIENT ...`：此部分在类的任何方法外部初始化 S3 客户端。这会导致 Lambda 在[初始化阶段](lambda-runtime-environment.md#runtimes-lifecycle-ib)运行此代码。
+ `public record Order ...`：在此自定义 Java [记录](https://openjdk.org/jeps/395)中定义预期输入事件的形状。
+ `public String handleRequest(Order event, Context context)`：这是包含主应用程序逻辑的**主处理程序方法**。
+ `private void uploadReceiptToS3(...) {}`：这是主 `handleRequest` 处理程序方法引用的帮助程序方法。
### 示例 build.gradle 和 pom.xml 文件
此函数随附以下 `build.gradle` 或 `pom.xml` 文件。
------
#### [ build.gradle ]
```
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
```
------
#### [ pom.xml ]
```
4.0.0
com.example
example-java
jar
1.0-SNAPSHOT
example-java-function
UTF-8
21
21
com.amazonaws
aws-lambda-java-core
1.2.3
software.amazon.awssdk
s3
2.28.29
org.slf4j
slf4j-nop
2.0.16
maven-surefire-plugin
3.5.2
org.apache.maven.plugins
maven-shade-plugin
3.4.1
false
*:*
META-INF/*
META-INF/versions/**
package
shade
org.apache.maven.plugins
maven-compiler-plugin
3.13.0
21
```
------
要使此函数正常运行，其[执行角色](lambda-intro-execution-role.md)必须允许 `s3:PutObject` 操作。此外，请确保您定义了 `RECEIPT_BUCKET` 环境变量。成功调用后，Amazon S3 存储桶应包含接收文件。
**注意**
此函数可能需要额外的配置设置才能成功运行而不会超时。建议配置 256 MB 的内存和 10 秒的超时时间。由于是[冷启动](lambda-runtime-environment.md#cold-start-latency)，第一次调用可能需要额外的时间。由于重复使用执行环境，后续调用的运行速度应该会快得多。
## Java 处理程序的有效类定义
为了定义您的类，[aws-lambda-java-core](https://github.com/aws/aws-lambda-java-libs/tree/master/aws-lambda-java-core) 库为处理程序方法定义了两个接口。使用提供的接口简化处理程序配置，并在编译时验证方法签名。
+ [ com.amazonaws.services.lambda.runtime.RequestHandler](https://github.com/aws/aws-lambda-java-libs/blob/master/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestHandler.java)
+ [ com.amazonaws.services.lambda.runtime.RequestStreamHandler](https://github.com/aws/aws-lambda-java-libs/blob/master/aws-lambda-java-core/src/main/java/com/amazonaws/services/lambda/runtime/RequestStreamHandler.java)
`RequestHandler` 接口是一个泛型类型，它采用两个参数：输入类型和输出类型。这两种类型都必须是对象。在此示例中，我们的 `OrderHandler` 类实现 `RequestHandler`。输入类型是我们在类中定义的 `Order` 记录，输出类型是 `String`。
```
public class OrderHandler implements RequestHandler {
...
}
```
使用此接口时，Java 运行时会将事件反序列化为具有输入类型的对象，并将输出序列化为文本。当内置序列化与输入和输出类型配合使用时，请使用此接口。
要使用您自己的序列化，您可以实现 `RequestStreamHandler` 接口。使用此接口，Lambda 将向您的处理程序传递输入流和输出流。处理程序从输入流读取字节，写到输出流，并返回 void。有关使用 Java 21 运行时的示例，请参阅 [HandlerStream.java](https://github.com/awsdocs/aws-lambda-developer-guide/tree/main/sample-apps/java-basic/src/main/java/example/HandlerStream.java)。
如果您在 Java 函数中只使用基本类型和泛型类型（即 `String`、`Integer`、`List` 或 `Map`），则无需实现接口。例如，如果您的函数接受 `Map` 输入并返回 `String`，则您的类定义和处理程序签名可能如下所示：
```
public class ExampleHandler {
public String handleRequest(Map input, Context context) {
...
}
}
```
此外，当您不实现接口时，[上下文](java-context.md)对象是可选的。例如，您的类定义和处理程序签名可能如下所示：
```
public class NoContextHandler {
public String handleRequest(Map input) {
...
}
}
```
## 处理程序命名约定
对于 Java Lambda 函数，如果您要实现 `RequestHandler` 或 `RequestStreamHandler` 接口，则主处理程序方法必须命名为 `handleRequest`。此外，请在 `handleRequest` 方法上方添加 `@Override` 标签。将函数部署到 Lambda 时，请按以下格式在函数配置中指定主处理程序：
+ **.**：例如，`example.OrderHandler`。
对于未实现 `RequestHandler` 或 `RequestStreamHandler` 接口的 Java Lambda 函数，您可以使用任何处理程序名称。将函数部署到 Lambda 时，请按以下格式在函数配置中指定主处理程序：
+ **.**::**：例如，`example.Handler::mainHandler`。
## 定义和访问输入事件对象
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 对象。然后，您可以访问该对象的字段。例如，`event.orderId` 从原始输入中检索 `orderId` 的值。
**注意**
Java 记录是 Java 17 运行时及更高版本独有的一项功能。在所有 Java 运行时系统中，您可以使用类来表示事件数据。在这种情况下，您可以使用如 [jackson](https://github.com/FasterXML/jackson) 之类的库来反序列化 JSON 输入。
### 其他输入事件类型
Java Lambda 函数有许多可能的输入事件：
+ `Integer``Long` 、`Double`、等 – 事件是一个没有其他格式的数字（例如，`3.5`）。Java 运行时将该值转换为指定类型的对象。
+ `String` – 事件是一个 JSON 字符串，包括引号（例如，）`“My string”`。运行时将该值转换为 `String` 对象（不带引号）。
+ `List``List` 、`List