本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 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)
+ [在處理常式中使用適用於 Java v2 的 AWS SDK](#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`。
對於 Java 中未實作 `RequestHandler` 或 `RequestStreamHandler` 介面的 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 物件。然後，您可以存取該物件的欄位。例如，使用 `orderId` 可以從原始輸入擷取 `event.orderId` 的值。
**注意**
僅 Java 17 及更新版本的執行時期支援 Java 記錄功能。在所有 Java 執行期中，可以使用類別來表示事件資料。在此類案例中，您可以使用 [jackson](https://github.com/FasterXML/jackson) 之類的程式庫來反序列化 JSON 輸入。
### 其他輸入事件類型
Java 中的 Lambda 函式支援多種可能的輸入事件：
+ `Integer` `Long`、`Double`、等等 - 事件是沒有其他格式的數字，例如 `3.5`。Java 執行時期會將值轉換為指定類型的物件。
+ `String` - 事件是 JSON 字串，包括引號，例如 。`“My string”`執行時期會將值轉換為不含引號的 `String` 物件。
+ `List` `List`、`List