그전 포스팅 자료에서 그대로 진행합니다.
이전 포스트 글

서버리스(Serverless) 개발 해보기

이번 포스트는, AWS DynamoDb 와 Lambda 를 SAM CLI 를 활용하여 연결하고 저장하도록 구성해보도록 하겠습니다.

DynamoDB 알아보기

DynamoDB 란?

Amazon DynamoDB는 AWS에서 제공하는 완전 관리형(Fully Managed) Key-Value 기반의 NoSQL 데이터베이스 서비스입니다.

서버리스(Serverless) 아키텍처를 구축할 때 Lambda와 가장 궁합이 잘 맞는 DB로 꼽히는데, 그 이유는 우리가 서버를 프로비저닝하거나 패치, 관리할 필요 없이 오직 테이블(Table)만 생성하면 즉시 사용 가능하기 때문입니다.

1. RDBMS와는 다른 '테이블 중심' 구조

우리가 흔히 쓰는 MySQL이나 Oracle 같은 RDBMS는 보통 물리적인 '서버(Instance)'를 띄우고, 그 안에 논리적인 '데이터베이스(Schema)'를 만든 뒤, 그 안에 여러 개의 '테이블'을 생성하여 관리합니다. 즉, 테이블들이 하나의 거대한 DB 인스턴스에 종속되어 있는 구조입니다.

반면, DynamoDB는 '데이터베이스'라는 상위 컨테이너 개념이 존재하지 않습니다. 각각의 테이블(Table)이 독립적인 리소스(Resource)로 존재합니다.

RDBMS: Server > Database > Table A, Table B ... (테이블들이 한 지붕 아래 묶여 있음)
DynamoDB: Table A (독립적), Table B (독립적) ... (각 테이블이 별개의 AWS 리소스)

2. 핵심 특징

NoSQL: 스키마가 고정되어 있지 않아(Schemaless), PK(Primary Key)를 제외한 나머지 필드는 자유롭게 데이터를 저장할 수 있습니다.
고성능: 규모와 관계없이 10밀리초 미만의 지연 시간(Latency)을 제공합니다.
무한한 확장성: 데이터가 늘어나면 알아서 스토리지를 늘리고, 트래픽이 늘어나면 처리량(Throughput)을 자동으로 조절합니다.

📚 더 자세한 내용이 궁금하다면?
Amazon DynamoDB 공식 소개 페이지
DynamoDB 핵심 구성 요소 (Core Components)

DynamoDB 세부

DynamoDB는 NoSQL(Schemaless)이지만, 데이터의 타입(Type) 자체는 명확하게 구분하여 저장합니다.

우리가 Java 코드에서 AttributeValue를 조립할 때 .s()나 .n() 같은 메서드를 사용하는 이유가 바로 이 DynamoDB의 데이터 타입을 명시하기 위함입니다.

AttributeValue 내용은 아래에서 나옵니다!

DynamoDB의 데이터 타입은 크게 스칼라(Scalar), 문서(Document), 집합(Set) 세 가지 카테고리로 나뉩니다.

1. 스칼라 타입 (Scalar Types)

가장 기본이 되는 단일 값입니다.

문자열 (String - S): UTF-8 바이너리 인코딩된 문자열입니다.
- Java SDK: AttributeValue.builder().s("Hello").build()
숫자 (Number - N): 정수, 실수 등을 모두 포함합니다.
- ⚠️ 주의: DynamoDB는 숫자를 네트워크 전송 시 문자열(String) 형태로 주고받습니다. 이는 정밀도(Precision) 손실을 막기 위함입니다.
- Java SDK: AttributeValue.builder().n("123.45").build() (문자열로 넣어야 함!)
이진 값 (Binary - B): 이미지나 압축 데이터 같은 바이너리 데이터입니다.
- Java SDK: AttributeValue.builder().b(SdkBytes.fromByteArray(...)).build()
불리언 (Boolean - BOOL): true 또는 false 값입니다.
- Java SDK: AttributeValue.builder().bool(true).build()
Null (NULL): 값이 없음을 명시적으로 나타냅니다.

2. 문서 타입 (Document Types)

JSON 구조처럼 복잡한 계층 구조를 표현할 때 사용합니다.

리스트 (List - L): 순서가 있는 값들의 모음입니다. 서로 다른 데이터 타입을 담을 수 있습니다. (JSON의 Array []와 유사)
- Java SDK: AttributeValue.builder().l(...)
맵 (Map - M): 키-값 쌍의 모음입니다. (JSON의 Object {}와 유사)
- Java SDK: AttributeValue.builder().m(...)

3. 집합 타입 (Set Types)

스칼라 타입의 값들을 중복 없이 저장합니다. (순서 보장 안 됨)

문자열 집합 (String Set - SS): 중복 없는 문자열들의 집합.
숫자 집합 (Number Set - NS): 중복 없는 숫자들의 집합.
이진 집합 (Binary Set - BS): 중복 없는 바이너리들의 집합.

📚 공식 문서 (Reference)
더 자세한 스펙과 제약 사항(크기 제한 등)은 아래 공식 문서에서 확인할 수 있습니다.
AWS 공식 가이드: 지원되는 데이터 형식 및 명명 규칙
AWS SDK for Java v2: AttributeValue Class

DynamoDB 실습

DynamoDB 생성하기

마찬가지로, DynamoDB 또한, SAM CLI 의 입장에서는 자원입니다.

따라서 template.yaml 에 다음과 같이 테이블과 PrimaryKey 를 등록하여 사용할 수 있습니다.

Resources:
  # 1. DynamoDB 테이블 (이름 명시)
  MyUserTable:
    Type: AWS::Serverless::SimpleTable
    DeletionPolicy: Retain
    Properties:
      TableName: MyUserTable
      PrimaryKey:
        Name: userId
        Type: String

이 상태로 배포를 진행해보면, 실제로 데이터가 생성됨을 확인할 수 있습니다.

이때, DeletionPolicy: Retain 는, 만약 sam delete 명령어를 통해 리소스 자원을 모두 정리하여도, 해당 하는 리소스는 남기겠다는 의미입니다.

데이터베이스는 서비스를 닫더라도, 영속성 적으로 저장하는 것이 좋기 때문에, 이러한 DB 는 해당 옵션을 주는 것을 추천합니다.

실제로, sam delete 를 진행한 후에는 다음과 같이 table 은 남아 있는 상태가 됩니다.

$ sam delete
        Are you sure you want to delete the stack sam-cli-lambda-serverless-test in the region ap-northeast-2 ? [y/N]: y
        Are you sure you want to delete the folder sam-cli-lambda-serverless-test in S3 which contains the artifacts? [y/N]: y
        - Deleting S3 object with key sam-cli-lambda-serverless-test/a9a945ab3648ef46330744d19dd57f38                                                                                      
        - Deleting S3 object with key sam-cli-lambda-serverless-test/eb8ce7d6a7f9027b23d84250fe045c91.template                                                                             
        - Deleting Cloudformation stack sam-cli-lambda-serverless-test

Deleted successfully

실제 운영 환경에서는, 데이터 보호를 위해 Retain 옵션을 자주 사용합니다.
다만, 저희처럼 하나의 템플릿에서 테스트 할 경우, delete 후 재배포를 하면 리소스 이름 충돌로 배포가 실패할 수 있습니다.

Error: Failed to create changeset for the stack: sam-cli-lambda-serverless-test, ex: Waiter ChangeSetCreateComplete failed: Waiter encountered a terminal failure state: For expression "Status" we matched expected path: "FAILED" Status: FAILED. Reason: The following hook(s)/validation failed: [AWS::EarlyValidation::ResourceExistenceCheck]. To troubleshoot Early Validation errors, use the DescribeEvents API for detailed failure information.

따라서 저희는 만약 재배포를 진행할 경우, 기존의 DynamoDb 를 삭제 후 실행하시거나, 저 Retain 옵션을 아예 제거한 상태로 진행하시기 바랍니다.

❗ 만약 Retain 옵션을 주고 진행하고 싶다면, 2개의 sam-cli 템플릿을 구성하여 db 와 같이 긴 생명주기를 가진 template 하나
❗ 언제든 변경이 가능한 API 스펙을 가지고 있는 템플릿 하나
이렇게 구성하는 것을 추천합니다.

다음으로는 이렇게 생성된 DB 에 접근할 수 있는 권한을 부여해줍니다.

AWS 에서는, 이를 Policy 라고 합니다.

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: HelloWorldFunction
      Handler: helloworld.App::handleRequest
      Runtime: java21
      Architectures:
      - x86_64
      MemorySize: 512
      Environment:
        Variables:
          PARAM1: VALUE
      # DB 연결 권한 부여.
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref MyUserTable
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /hello
            Method: get

Java 코드 작성 - DB 연결

자바 코드로 작성되며, 빌드 도구는 maven 입니다.
js, ts 나 python 은 공식 예제 github 를 통해서 학습하시길 바랍니다.

먼저, dynamodb 와 연결하기 위해 의존성을 추가해줍니다.

        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>dynamodb</artifactId>
            <version>2.41.24</version>
        </dependency>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>url-connection-client</artifactId>
            <version>2.41.24</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.21.0</version>
            <scope>compile</scope>
        </dependency>

AWS SDK는 기본 Http 클라이언트가 Netty 입니다.
Netty 는 비동기 처리에 강력하고 성능이 좋지만, 무겁고, 느려(로딩) Lambda 환경에서 매우 치명적입니다.
따라서, 가벼운 HttpUrlConnection 을 기반으로 Serverless 의 주된 적인 Cold Start 의 지연을 조금이나마 개선할 수 있습니다.

이제 새로운 Lambda 용 Handler 를 하나 생성해줍니다.

CreateUserHandler

public class CreateUserHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

	private static final ObjectMapper objectMapper = new ObjectMapper();

	private static final DynamoDbClient client = DynamoDbClient.builder()
		.httpClient(UrlConnectionHttpClient.builder().build())
		.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
		.region(Region.AP_NORTHEAST_2)
		.build();

	private static final String TABLE_NAME = System.getenv("TABLE_NAME");

	@Override
	public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
		context.getLogger().log("Handler started. Input Body: " + input.getBody());

		try {
			UserRequestDto userRequest = objectMapper.readValue(input.getBody(), UserRequestDto.class);

			String generatedUserId = UUID.randomUUID().toString();
			String generatedDate = LocalDateTime.now().toString();

			Map<String, AttributeValue> item = new HashMap<>();
			item.put("userId", AttributeValue.builder().s(generatedUserId).build());
			item.put("name", AttributeValue.builder().s(userRequest.getName()).build());
			item.put("date", AttributeValue.builder().s(generatedDate).build());

			PutItemRequest request = PutItemRequest.builder()
				.tableName(TABLE_NAME)
				.item(item)
				.build();

			client.putItem(request);

			Map<String, String> responseBody = new HashMap<>();
			responseBody.put("message", "User saved successfully!");
			responseBody.put("userId", generatedUserId);
			responseBody.put("savedName", userRequest.getName());
			responseBody.put("createDate", generatedDate);

			return new APIGatewayProxyResponseEvent()
				.withStatusCode(200)
				.withBody(objectMapper.writeValueAsString(responseBody));

		} catch (Exception e) {
			context.getLogger().log("Error: " + e.getMessage());
			return new APIGatewayProxyResponseEvent()
				.withStatusCode(500)
				.withBody("{ \"error\": \"Failed to create user: " + e.getMessage() + "\" }");
		}
	}

	public static class UserRequestDto {
		private String name;
		private String date;

		public UserRequestDto() {
		}

		public String getName() {
			return name;
		}

		public String getDate() {
			return date;
		}
	}
}

전반적으로 데이터를 받아서, Map에 저장해서 db 에 저장하는 로직입니다.

DB 에 저장할 때는, 다음과 같이 PutItemRequest 객체를 생성해서 저장합니다.

이때 table 명은, 환경 변수로 등록되어 System.getenv("TABLE_NAME"); 을 통해 가져오게 됩니다.

저장할 데이터는, Key-Value 타입의 Map 으로 구성되며, Value 에는 AttributeValue 타입으로 진행합니다.

AttributeValue 타입에는 흔한 RDBMS 처럼, DateTime 형식이나, TEXT 등이 없습니다.

template.yaml 업데이트 - CreateUserHandler 함수 등록

이제 Handler (API) 를 작성 완료하였으니, template 에 등록해 해당 함수를 lambda 에 등록하도록 하겠습니다.

Resources:
  CreateUserFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: HelloWorldFunction
      Handler: helloworld.CreateUserHandler::handleRequest
      Runtime: java21
      Architectures:
        - x86_64
      MemorySize: 512
      Environment:
        Variables:
          TABLE_NAME: !Ref MyUserTable
      # DB 연결 권한 부여.
      Policies:
        - DynamoDBCrudPolicy:
            TableName: !Ref MyUserTable
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /user
            Method: post

Handler 에서 TableName 환경 변수가 필요했습니다.

따라서 이번에 생성되는 MyUserTable 의 정보를 !Ref 로 전달해 줍니다.

!Ref 란?
!Ref (Reference)는 CloudFormation의 내장 함수로, 템플릿 내의 다른 리소스나 파라미터를 '참조'할 때 사용합니다.

이제 sam build 후 sam deploy를 진행해 실제 배포를 하여 정상적으로 MyUserTable 에 저장되는지 확인합니다.

배포 후 테스트

아쉬운 포인트 - 로컬 테스트 불가

현재 코드는, 스프링 개발자 입장에서 매우 로우 합니다.

입력에 대한 검증이 없음 (유효성 검사, null 검사 등등)
비즈니스 로직이 포함 될 경우, Handler 의 함수가 너무 길어짐
함수가 많아 질 경우, 공통적으로 사용할 함수들의 부재

이러한 문제는 보일러플레이트 코드를 개발하고, 다양한 내부용 라이브러리 도입 등을 진행한다면 충분히 해결이 가능합니다. (시간만 많이 들 뿐...)

Q) 그럼 Spring 을 띄우면 되는거 아닌가요? 가능한 걸로 알고 있습니다.
A) 네 가능합니다. 다만 문제점은 Cold Start 에 있습니다.
사용하지 않던 Lambda자원은 정리되고 새로운 요청이 접수되면 신규 인스턴스를 생성하게 됩니다.
이때, Spring 유저라면 Spring Context 가 뜨는 과정이 얼마나 무거운지 알고 계실껍니다.
즉, 하나의 API 를 받기위해서 처음부터 Spring Context 를 띄워서 API 응답이 10초 이상 지연되거나 Timeout 되는 끔찍한 일이 발생하게 됩니다.

A2) 추가적으로, SnapStart 기능을 사용하면 전반적으로 스프링 프레임워크을 통한 콜드스타트 문제를 해결할 수 있다고 합니다. (LG CNS - 관련글)
그런데 이것 보다 차라리 node.js 환경 혹은 python 같은 가벼운 환경을 통해 개발해서 실행하는게 콜드스타트 문제를 해결하기 더 유리하지 않을까? 싶습니다.

현재 가장 큰 문제는 로컬에서 테스트 할 수가 없다는 것 입니다.

현재 배포가 완료 되어야지 테스트가 가능합니다.

이전 포스트 에서는 로컬 환경으로 실행하여 테스트를 진행하였으나, 현재 sam local start-api 을 진행해보면 오류가 발생할 것 입니다.

{"timestamp":"2026-02-10T14:02:56.328Z","message":"Error: Requested resource not found (Service: DynamoDb, Status Code: 400, Request ID: 1LFNKRP5LUK6H2QKKALS1J61H7VV4KQNSO5AEMVJF66Q9ASUAAJG) (SDK Attempt Count: 1)","level":"UNDEFINED","AWSRequestId":"61821ace-5b7f-4582-87a2-955ceeea762e"}
END RequestId: 61821ace-5b7f-4582-87a2-955ceeea762e
REPORT RequestId: 61821ace-5b7f-4582-87a2-955ceeea762e  Init Duration: 0.02 ms  Duration: 3217.03 ms    Billed Duration: 3218 ms        Memory Size: 512 MB     Max Memory Used: 512 MB

이유는 간단합니다. 연결된 DB 가 없습니다.

따라서 개발 환경에서는 별도로 연결을 진행할 LocalDB 가 필요합니다.

LocalDB 생성 - Docker-compose 및 profile 활용

다행히(?) 방법은 있습니다.

dynamoDb 를 Docker 로 로컬로 띄워서 활용하는 방법입니다. ~~AWS 는 참 친절해~~

docker-compose.yml 파일을 작성해서 로컬 환경에서 접속 가능하도록 db 를 구성해 줍니다.

/docker/docker-compose.yml

version: '3.8'
services:
  # 1. 로컬 DynamoDB (가짜 AWS DB)
  dynamodb-local:
    command: "-jar DynamoDBLocal.jar -sharedDb -dbPath ./data"
    image: "amazon/dynamodb-local:latest"
    container_name: dynamodb-local
    ports:
      - "8000:8000"
    volumes:
      - "./data:/home/dynamodblocal/data" # 데이터 영구 저장 (껐다 켜도 유지)
    working_dir: /home/dynamodblocal

  # 2. DynamoDB Admin (GUI 툴 - http://localhost:8001)
  dynamodb-admin:
    image: aaronshaf/dynamodb-admin
    ports:
      - "8001:8001"
    environment:
      DYNAMO_ENDPOINT: "http://dynamodb-local:8000"
      AWS_REGION: "ap-northeast-2"
      AWS_ACCESS_KEY_ID: "local"
      AWS_SECRET_ACCESS_KEY: "local"
    depends_on:
      - dynamodb-local

Q) Admin 은 왜 생성하나요?
A) DB 에 접속할 수 있는 GUI 용 서버입니다.

http://localhost:8001/에 접속해서, 새로운 테이블을 만들어 줍니다.

저희가 사용하는 테이블은, MyUserTable 입니다.

다음으로는 로컬 환경에서 실행할 때는, AWS 의 DynamoDB 가 아닌, 저희 로컬 Docker 환경의 DynamoDb 로 연결되어야 합니다.

따라서, CreateUserHandler의 내용을 일부 수정합니다.

public class CreateUserHandler implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {

	private static final ObjectMapper objectMapper = new ObjectMapper();

	private static final DynamoDbClient client = createClient();

	// DynamoDbClient 생성 함수.
	// 프로파일에 따라 연결 대상이 달라짐
	private static  DynamoDbClient createClient() {
		String profile = System.getenv("PROFILE");

		if ("dev".equals(profile)) {
			return DynamoDbClient.builder()
				.endpointOverride(URI.create("http://host.docker.internal:8000"))
				.region(Region.AP_NORTHEAST_2)
				.credentialsProvider(StaticCredentialsProvider.create(
					AwsBasicCredentials.create("local", "local")))
				.build();
		}

		return DynamoDbClient.builder()
			.httpClient(UrlConnectionHttpClient.builder().build())
			.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
			.region(Region.AP_NORTHEAST_2)
			.build();
	}

기존 비즈니스와 프리젠테이션 계층의 코드는 동일하고, DynamoDbClient 를 생성하는 부분만 변경되었습니다.

핵심 변경 사항은 PROFILE 이라는 환경 변수 기반으로 연결되는 DB 를 따로 관리하도록 구성한 내용 입니다.

스프링의 profile 기반의 환경 분리의 개념과 유사합니다.
물론 스프링의 도움없이 진행하는 만큼 많은 부분이 부족하지만..

이제 이 환경 주입을 위해서 루트 경루에 env-local.json 파일을 만들어 줍니다.

env-local.json

{
  "CreateUserFunction": {
    "PROFILE": "dev",
    "TABLE_NAME": "MyUserTable"
  }
}

또한 template.yaml 에서 기본 프로파일을 "prod" 로 지정해줍니다. (환경 변수)

Q) 왜 기본 프로파일을 지정하나요? 코드 상 프로파일 지정이 되어있지 않으면 기본적으로 배포 환경 아닌가요?
A) 맞습니다. 다만, SAM CLI 특성 상, 외부에서 아무리 환경 변수를 주입하여도, 정의 되지 않은 환경 변수는 무시해버립니다.

Globals:
  Function:
    Timeout: 20
    MemorySize: 512
    Environment:
      Variables:
        PROFILE: prod

이제, 다시 sam build 후 실행을 합니다.

이때, 명령어는 기존의 sam local start-api 에서 환경 변수가 들어있는 json 파일을 포함하여 다음과 같이 진행합니다.

sam local start-api --env-vars env-local.json

정상적으로 매우 잘되는 모습을 확인할 수 있습니다.

배포 또한 현재 구성에서는 문제 없이 잘 진행 될 것 입니다.

정리

이제 DB 와의 연결도 구성하였습니다.

간단한 CRUD 를 통해서 조금 더 친숙해지도록 하겠습니다.

베스트 프렉티스 까지는 못만들겠지만, 최대한 Layered Architecture 처럼 구성해보도록 하겠습니다.

AWS SAM CLI로 시작하는 서버리스: Lambda와 DynamoDB #2