🚀 AWS CDK와 LocalStack을 사용한 완전한 API REST 만들기: 처음부터 로컬 프로덕션까지

Source: Dev.to

📋 소개

이 전체 튜토리얼에서는 AWS CDK, TypeScript, LocalStack을 사용해 주문 관리용 강력한 REST API를 만드는 방법을 보여드립니다. AWS를 완벽히 시뮬레이션하는 로컬 개발 환경을 설정하고, 전체 CRUD를 구현하며, 철저히 테스트하는 과정을 배울 수 있습니다.

🎯 무엇을 만들 건가요?

• 5개의 CRUD 엔드포인트를 갖춘 완전한 REST API
• 각 작업을 담당하는 TypeScript Lambda 함수
• 영속성을 위한 DynamoDB 테이블
• 진입점 역할을 하는 API Gateway
• 비용 없이 로컬에서 AWS를 시뮬레이션하는 LocalStack
• 자동화 및 수동 테스트

🛠️ 기술 스택

• AWS CDK v2.170.0 – 인프라스트럭처 코드(IaC)
• TypeScript 5.x – 주요 프로그래밍 언어
• Node.js 20+ – 런타임
• LocalStack – 로컬 AWS 시뮬레이션
• DynamoDB – NoSQL 데이터베이스
• API Gateway – API 관리
• Lambda – 서버리스 함수

🔧 초기 설정

1. VS Code에서 LocalStack 설치

📦 LocalStack 확장 설치

방법 1: VS Code Marketplace에서

1. VS Code를 엽니다.
2. 확장 탭(Ctrl+Shift+X 또는 Cmd+Shift+X)으로 이동합니다.
3. **“LocalStack”**을 검색합니다.
4. LocalStack 공식 확장을 설치합니다.
5. VS Code를 재시작합니다.

방법 2: 명령줄에서

code --install-extension localstack.localstack

방법 3: 수동 설치
VS Code Marketplace - LocalStack 페이지에 접속해 “Install” 버튼을 클릭합니다.

⚙️ 확장 설정

설정(Ctrl+, Windows, Cmd+, macOS)을 열고 **“LocalStack”**을 검색한 뒤 아래 옵션을 추가합니다:

{
  "localstack.endpoint": "http://localhost:4566",
  "localstack.profile": "default",
  "localstack.region": "us-east-1",
  "localstack.autoStart": true,
  "localstack.dockerFlags": "-d"
}

🎯 확장 기능

• LocalStack 패널: 서비스 상태, 실시간 로그, 서비스 관리, 리소스 탐색기.
• 사용 가능한 명령 (명령 팔레트 Ctrl+Shift+P):
  • LocalStack: Start – LocalStack 시작
  • LocalStack: Stop – LocalStack 중지
  • LocalStack: Restart – LocalStack 재시작
  • LocalStack: Show Logs – 로그 보기
  • LocalStack: Open Web UI – 웹 UI 열기
• AWS CLI와 통합: 엔드포인트 자동 설정, 로컬 프로파일, AWS 명령을 LocalStack으로 라우팅.

🔍 확장 설치 확인

• 사이드 패널: 사이드바에 LocalStack 아이콘이 표시됩니다.
• 명령 팔레트: Ctrl+Shift+P → “LocalStack” 검색.
• 상태 표시줄: 하단에 상태 표시기가 나타납니다.

🚀 첫 사용

1. LocalStack 패널을 엽니다(아이콘 클릭).
2. Start LocalStack 버튼이나 명령을 사용해 LocalStack을 시작합니다.
3. 패널에 Running이 표시되는지 확인합니다.
4. Logs 탭에서 로그를 확인합니다.

2. CDK 프로젝트를 처음부터 만들기

📋 사전 요구사항

다음이 설치되어 있는지 확인합니다:

# Node.js (버전 20 이상)
node --version

# npm
npm --version

# AWS CDK CLI (전역)
npm install -g aws-cdk

# CDK 설치 확인
cdk --version

🏗️ CDK 프로젝트 초기화

# 프로젝트 디렉터리 생성
mkdir cdk-api-localstask
cd cdk-api-localstask

# TypeScript로 CDK 프로젝트 초기화
cdk init app --language typescript

초기 구조 확인

ls -la
# 다음과 같은 파일/디렉터리가 보여야 합니다:
# bin/           # 애플리케이션 진입점
# lib/           # 스택 정의
# test/          # 단위 테스트
# package.json   # 프로젝트 의존성
# tsconfig.json  # TypeScript 설정
# cdk.json       # CDK 설정

추가 의존성 설치

# LocalStack 관련 의존성
npm install aws-cdk-local

# Lambda와 DynamoDB용 의존성
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

# TypeScript용 의존성
npm install @types/aws-lambda @types/uuid uuid

# 개발용 의존성
npm install --save-dev @types/node typescript

⚙️ LocalStack 스크립트 설정

package.json을 열어 다음 스크립트를 추가합니다:

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "synth": "cdk synth",
    "deploy": "cdk deploy",
    "local:synth": "npx cdklocal synth",
    "local:deploy": "npx cdklocal deploy",
    "local:destroy": "npx cdklocal destroy",
    "local:diff": "npx cdklocal diff",
    "local:bootstrap": "npx cdklocal bootstrap"
  }
}

🔧 CDK를 LocalStack에 맞게 설정

cdk.json (CDK 설정 파일):

{
  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "package*.json",
      "yarn.lock",
      "node_modules",
      "test"
    ]
  },
  "context": {
    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
    "@aws-cdk/core:checkSecretUsage": true,
    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
    "@aws-cdk/aws-apigateway:disableCloudWatchRole": false,
    "@aws-cdk/core:enablePartitionLiterals": true,
    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
    "@aws-cdk/aws-iam:minimizePolicies": true,
    "@aws-cdk/core:disableStackTrace": false
  }
}

📁 디렉터리 구조 만들기

# 코드 정리를 위한 디렉터리 생성
mkdir -p lib/lambdas
mkdir -p lib/types

# 기본 파일 생성
touch lib/types/order.ts
touch lib/lambdas/create-order.ts
touch lib/lambdas/get-order.ts
touch lib/lambdas/list-orders.ts
touch lib/lambdas/update-order.ts
touch lib/lambdas/delete-order.ts

🎯 메인 스택 설정

bin/app.ts (애플리케이션 진입점):

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { CdkApiLocalstackStack } from '../lib/cdk-api-localstask-stack';

const app = new cdk.App();
new CdkApiLocalstackStack(app, 'CdkApiLocalstackStack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT || '000000000000', // LocalStack 기본값
    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
  },
});