Java에서 Lambda 함수 핸들러 정의

Lambda 함수의 핸들러는 이벤트를 처리하는 함수 코드의 메서드입니다. 함수가 간접 호출되면 Lambda는 핸들러 메서드를 실행합니다. 함수는 핸들러가 응답을 반환하거나 종료하거나 제한 시간이 초과될 때까지 실행됩니다.

이 페이지에서는 프로젝트 설정, 이름 지정 규칙, 모범 사례를 포함하여 Java에서 Lambda 함수 핸들러를 사용하는 방법을 설명합니다. 이 페이지에는 주문에 대한 정보를 가져와서 텍스트 파일 영수증을 생성하고 해당 파일을 Amazon Simple Storage Service(S3) 버킷에 넣는 Java Lambda 함수의 예제도 포함되어 있습니다. 함수를 작성한 후 배포하는 방법에 대한 자세한 내용은 .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 파일은 다음 코드 섹션을 포함하고 있습니다.

이 함수가 제대로 작동하려면 실행 역할이 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 레코드로 정의할 수 있습니다. 이 예제에서는 Order 객체를 나타내는 OrderHandler 클래스 내의 레코드를 정의합니다.

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 종속성을 추가하려면 Gradle용 build.gradle 또는 Maven용 pom.xml 파일에 추가합니다. 함수에 필요한 라이브러리만 추가하는 것이 좋습니다. 이전의 예제 코드에서는 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 함수를 구축할 때 코딩 모범 사례를 사용하려면 다음 목록의 지침을 준수하세요.