# 프로젝트 디렉토리 구조

my-serverless-app/

├── serverless.yml          # 서버리스 설정 파일

├── package.json

├── src/

│   ├── functions/           # Lambda 함수들

│   │   ├── users/

│   │   │   ├── create.js    # 유저 생성

│   │   │   ├── get.js       # 유저 조회

│   │   │   ├── update.js    # 유저 수정

│   │   │   └── delete.js    # 유저 삭제

│   │   ├── orders/

│   │   │   ├── create.js

│   │   │   └── list.js

│   │   └── products/

│   │       └── search.js

│   ├── lib/                 # 공통 유틸리티

│   │   ├── dynamodb.js      # DynamoDB 클라이언트

│   │   ├── response.js      # HTTP 응답 헬퍼

│   │   └── validator.js     # 입력값 검증

│   └── models/              # 데이터 모델

│       ├── user.js

│       └── order.js

└── tests/                   # 테스트 파일

// Single Table Design 예시

// 테이블명: MyApp

// PK: pk (Partition Key), SK: sk (Sort Key)



// 유저 프로필

{

"pk": "USER#user001",

"sk": "PROFILE",

"name": "홍길동",

"email": "hong@email.com",

"createdAt": "2024-01-15T09:00:00Z"

}



// 유저의 주문 (같은 파티션에 저장!)

{

"pk": "USER#user001",

"sk": "ORDER#2024-001",

"productName": "노트북",

"amount": 1500000,

"status": "DELIVERED"

}



// 유저의 모든 주문 조회 (단 한 번의 쿼리로!)

const params = {

TableName: 'MyApp',

KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',

ExpressionAttributeValues: {

':pk': 'USER#user001',

':prefix': 'ORDER#'

}

}

// GSI 설정 예시 (serverless.yml)

resources:

Resources:

MyAppTable:

Type: AWS::DynamoDB::Table

Properties:

TableName: MyApp

BillingMode: PAY_PER_REQUEST  # 온디맨드 과금

AttributeDefinitions:

- AttributeName: pk

AttributeType: S

- AttributeName: sk

AttributeType: S

- AttributeName: email  # GSI용 속성

AttributeType: S

- AttributeName: gsi1pk  # GSI 파티션 키

AttributeType: S

KeySchema:

- AttributeName: pk

KeyType: HASH

- AttributeName: sk

KeyType: RANGE

GlobalSecondaryIndexes:

- IndexName: EmailIndex

KeySchema:

- AttributeName: email

KeyType: HASH

Projection:

ProjectionType: ALL  # 모든 속성 복사

- IndexName: GSI1

KeySchema:

- AttributeName: gsi1pk

KeyType: HASH

- AttributeName: sk

KeyType: RANGE

Projection:

ProjectionType: ALL

// src/lib/dynamodb.js

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';



// 클라이언트 생성 (Lambda 컨테이너 재사용을 위해 모듈 레벨에서 생성)

const client = new DynamoDBClient({

region: process.env.AWS_REGION || 'ap-northeast-2'

});



// DocumentClient: JS 객체를 자동으로 DynamoDB 타입으로 변환

export const dynamoDB = DynamoDBDocumentClient.from(client, {

marshallOptions: {

removeUndefinedValues: true,  // undefined 값 자동 제거

convertEmptyValues: false

}

});



export const TABLE_NAME = process.env.TABLE_NAME || 'MyApp';

// src/functions/users/create.js - 유저 생성

import { PutCommand } from '@aws-sdk/lib-dynamodb';

import { dynamoDB, TABLE_NAME } from '../../lib/dynamodb.js';

import { v4 as uuidv4 } from 'uuid';



export const handler = async (event) => {

try {

const body = JSON.parse(event.body);

const userId = uuidv4();

const now = new Date().toISOString();



const item = {

pk: `USER#${userId}`,

sk: 'PROFILE',

userId,

name: body.name,

email: body.email,

createdAt: now,

updatedAt: now,

// GSI용 속성

gsi1pk: `EMAIL#${body.email}`

};



await dynamoDB.send(new PutCommand({

TableName: TABLE_NAME,

Item: item,

// 이미 존재하면 에러 발생 (멱등성 보장)

ConditionExpression: 'attribute_not_exists(pk)'

}));



return {

statusCode: 201,

headers: { 'Content-Type': 'application/json' },

body: JSON.stringify({ userId, message: '유저 생성 완료!' })

};

} catch (error) {

if (error.name === 'ConditionalCheckFailedException') {

return { statusCode: 409, body: JSON.stringify({ message: '이미 존재하는 유저' }) };

}

return { statusCode: 500, body: JSON.stringify({ message: error.message }) };

}

};

// src/functions/users/get.js - 유저 조회

import { GetCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';

import { dynamoDB, TABLE_NAME } from '../../lib/dynamodb.js';



// 유저 ID로 조회

export const getById = async (event) => {

const { userId } = event.pathParameters;



const result = await dynamoDB.send(new GetCommand({

TableName: TABLE_NAME,

Key: {

pk: `USER#${userId}`,

sk: 'PROFILE'

}

}));



if (!result.Item) {

return { statusCode: 404, body: JSON.stringify({ message: '유저 없음' }) };

}



return { statusCode: 200, body: JSON.stringify(result.Item) };

};



// 유저의 모든 주문 조회 (Sort Key 범위 쿼리)

export const getUserOrders = async (event) => {

const { userId } = event.pathParameters;



const result = await dynamoDB.send(new QueryCommand({

TableName: TABLE_NAME,

KeyConditionExpression: 'pk = :pk AND begins_with(sk, :prefix)',

ExpressionAttributeValues: {

':pk': `USER#${userId}`,

':prefix': 'ORDER#'

},

ScanIndexForward: false  // 최신 주문부터 (내림차순)

}));



return { statusCode: 200, body: JSON.stringify(result.Items) };

};

// src/functions/users/update.js - 유저 수정

import { UpdateCommand } from '@aws-sdk/lib-dynamodb';

import { dynamoDB, TABLE_NAME } from '../../lib/dynamodb.js';



export const handler = async (event) => {

const { userId } = event.pathParameters;

const body = JSON.parse(event.body);



const result = await dynamoDB.send(new UpdateCommand({

TableName: TABLE_NAME,

Key: {

pk: `USER#${userId}`,

sk: 'PROFILE'

},

// 동적으로 업데이트할 필드 설정

UpdateExpression: 'SET #name = :name, updatedAt = :updatedAt',

ExpressionAttributeNames: {

'#name': 'name'  // 예약어 충돌 방지

},

ExpressionAttributeValues: {

':name': body.name,

':updatedAt': new Date().toISOString()

},

// 존재하는 아이템만 업데이트

ConditionExpression: 'attribute_exists(pk)',

ReturnValues: 'ALL_NEW'  // 업데이트 후 값 반환

}));



return { statusCode: 200, body: JSON.stringify(result.Attributes) };

};

# serverless.yml

service: my-serverless-app



provider:

name: aws

runtime: nodejs20.x

region: ap-northeast-2

stage: ${opt:stage, 'dev'}

environment:

TABLE_NAME: ${self:service}-${self:provider.stage}

iam:

role:

statements:

- Effect: Allow

Action:

- dynamodb:GetItem

- dynamodb:PutItem

- dynamodb:UpdateItem

- dynamodb:DeleteItem

- dynamodb:Query

- dynamodb:BatchGetItem

- dynamodb:BatchWriteItem

Resource:

- !GetAtt MyAppTable.Arn

- !Sub '${MyAppTable.Arn}/index/*'  # GSI 포함



functions:

createUser:

handler: src/functions/users/create.handler

events:

- httpApi:

path: /users

method: POST



getUser:

handler: src/functions/users/get.getById

events:

- httpApi:

path: /users/{userId}

method: GET



getUserOrders:

handler: src/functions/users/get.getUserOrders

events:

- httpApi:

path: /users/{userId}/orders

method: GET



updateUser:

handler: src/functions/users/update.handler

events:

- httpApi:

path: /users/{userId}

method: PUT

# JWT Authorizer 설정 (serverless.yml)

provider:

httpApi:

authorizers:

jwtAuthorizer:

type: jwt

identitySource: $request.header.Authorization

issuerUrl: https://cognito-idp.ap-northeast-2.amazonaws.com/{userPoolId}

audience:

- {clientId}



functions:

getUser:

handler: src/functions/users/get.getById

events:

- httpApi:

path: /users/{userId}

method: GET

authorizer:

name: jwtAuthorizer  # 인증 적용!

// ❌ 나쁜 예 - Scan 사용 (전체 테이블 스캔, 비용 폭탄!)

const badQuery = await dynamoDB.send(new ScanCommand({

TableName: TABLE_NAME,

FilterExpression: 'email = :email',

ExpressionAttributeValues: { ':email': 'user@email.com' }

}));



// ✅ 좋은 예 - GSI를 활용한 Query (특정 파티션만 조회)

const goodQuery = await dynamoDB.send(new QueryCommand({

TableName: TABLE_NAME,

IndexName: 'EmailIndex',  // GSI 사용!

KeyConditionExpression: 'email = :email',

ExpressionAttributeValues: { ':email': 'user@email.com' }

}));



// ✅ 프로젝션으로 필요한 속성만 가져오기

const projectedQuery = await dynamoDB.send(new GetCommand({

TableName: TABLE_NAME,

Key: { pk: 'USER#user001', sk: 'PROFILE' },

ProjectionExpression: 'userId, #name, email',  // 필요한 것만!

ExpressionAttributeNames: { '#name': 'name' }

}));

// DynamoDB Streams 트리거 Lambda 함수

export const streamHandler = async (event) => {

for (const record of event.Records) {

const { eventName, dynamodb } = record;



if (eventName === 'INSERT') {

// 새 유저 생성 시 환영 이메일 발송

const newItem = dynamodb.NewImage;

if (newItem.sk.S === 'PROFILE') {

await sendWelcomeEmail(newItem.email.S);

}

}



if (eventName === 'MODIFY') {

// 주문 상태 변경 시 알림 발송

const oldItem = dynamodb.OldImage;

const newItem = dynamodb.NewImage;

if (newItem.sk.S.startsWith('ORDER#') &&

oldItem.status?.S !== newItem.status?.S) {

await sendOrderStatusNotification(newItem);

}

}



if (eventName === 'REMOVE') {

// 데이터 삭제 시 감사 로그 기록

await logDeletion(dynamodb.OldImage);

}

}

};



# serverless.yml에 Streams 트리거 설정

functions:

streamProcessor:

handler: src/functions/stream.streamHandler

events:

- stream:

type: dynamodb

arn: !GetAtt MyAppTable.StreamArn

batchSize: 100

startingPosition: LATEST

bisectBatchOnFunctionError: true

// TTL 설정 예시 - 세션 데이터 (24시간 후 자동 삭제)

const sessionItem = {

pk: `SESSION#${sessionId}`,

sk: 'DATA',

userId: userId,

token: accessToken,

createdAt: new Date().toISOString(),

// TTL: Unix timestamp (초 단위)

// 현재 시간 + 24시간

ttl: Math.floor(Date.now() / 1000) + (24 * 60 * 60)

};



// serverless.yml에서 TTL 속성 지정

TimeToLiveSpecification:

AttributeName: ttl

Enabled: true

# serverless.yml - Auto Scaling 설정

resources:

Resources:

MyAppTable:

Type: AWS::DynamoDB::Table

Properties:

BillingMode: PROVISIONED

ProvisionedThroughput:

ReadCapacityUnits: 5   # 최소값

WriteCapacityUnits: 5  # 최소값



ReadScalingTarget:

Type: AWS::ApplicationAutoScaling::ScalableTarget

Properties:

MaxCapacity: 100   # 최대 RCU

MinCapacity: 5     # 최소 RCU

ResourceId: !Sub 'table/${MyAppTable}'

ScalableDimension: dynamodb:table:ReadCapacityUnits

ServiceNamespace: dynamodb



ReadScalingPolicy:

Type: AWS::ApplicationAutoScaling::ScalingPolicy

Properties:

PolicyType: TargetTrackingScaling

TargetTrackingScalingPolicyConfiguration:

TargetValue: 70  # 70% 사용률 유지

PredefinedMetricSpecification:

PredefinedMetricType: DynamoDBReadCapacityUtilization

# 함수별 세밀한 권한 설정 예시

functions:

readOnlyFunction:

handler: src/functions/users/get.handler

iamRoleStatements:  # 함수별 IAM 역할

- Effect: Allow

Action:

- dynamodb:GetItem

- dynamodb:Query

Resource:

- !GetAtt MyAppTable.Arn

- !Sub '${MyAppTable.Arn}/index/*'



writeFunction:

handler: src/functions/users/create.handler

iamRoleStatements:

- Effect: Allow

Action:

- dynamodb:PutItem

- dynamodb:UpdateItem

Resource: !GetAtt MyAppTable.Arn

# serverless.yml - SSM Parameter Store 활용

provider:

environment:

TABLE_NAME: ${self:service}-${self:provider.stage}

# SSM에서 값 가져오기

JWT_SECRET: ${ssm:/myapp/${self:provider.stage}/jwt-secret}

SMTP_PASSWORD: ${ssm:/myapp/${self:provider.stage}/smtp-password~true}  # ~true: 암호화된 값



// Lambda 코드에서 Secrets Manager 사용

import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';



const secretsClient = new SecretsManagerClient({ region: 'ap-northeast-2' });



// 캐싱으로 매 요청마다 Secrets Manager 호출 방지

let cachedSecret = null;

const getSecret = async () => {

if (cachedSecret) return cachedSecret;

const response = await secretsClient.send(new GetSecretValueCommand({

SecretId: 'myapp/production/api-keys'

}));

cachedSecret = JSON.parse(response.SecretString);

return cachedSecret;

};

// src/lib/logger.js - 구조화된 로깅 유틸리티

export const logger = {

info: (message, data = {}) => {

console.log(JSON.stringify({

level: 'INFO',

message,

timestamp: new Date().toISOString(),

requestId: process.env.AWS_REQUEST_ID,

...data

}));

},

error: (message, error, data = {}) => {

console.error(JSON.stringify({

level: 'ERROR',

message,

errorMessage: error.message,

errorStack: error.stack,

timestamp: new Date().toISOString(),

...data

}));

}

};



// 사용 예시

logger.info('유저 생성 완료', { userId, email });

logger.error('DynamoDB 쓰기 실패', error, { userId, operation: 'createUser' });

# serverless.yml - X-Ray 활성화

provider:

tracing:

lambda: true      # Lambda X-Ray 활성화

apiGateway: true  # API Gateway X-Ray 활성화



// Lambda 코드에서 X-Ray SDK 사용

import AWSXRay from 'aws-xray-sdk-core';

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';



// X-Ray로 DynamoDB 호출 추적

const client = AWSXRay.captureAWSv3Client(new DynamoDBClient({

region: 'ap-northeast-2'

}));

// tests/users/create.test.js

import { mockClient } from 'aws-sdk-client-mock';

import { DynamoDBDocumentClient, PutCommand } from '@aws-sdk/lib-dynamodb';

import { handler } from '../../src/functions/users/create.js';



// DynamoDB 클라이언트 모킹

const ddbMock = mockClient(DynamoDBDocumentClient);



describe('유저 생성 Lambda', () => {

beforeEach(() => {

ddbMock.reset();

});



it('유저를 성공적으로 생성해야 함', async () => {

ddbMock.on(PutCommand).resolves({});



const event = {

body: JSON.stringify({ name: '홍길동', email: 'hong@test.com' })

};



const result = await handler(event);



expect(result.statusCode).toBe(201);

const body = JSON.parse(result.body);

expect(body.userId).toBeDefined();

});



it('중복 유저 생성 시 409 반환해야 함', async () => {

ddbMock.on(PutCommand).rejects({

name: 'ConditionalCheckFailedException'

});



const result = await handler({ body: JSON.stringify({ name: '홍길동', email: 'hong@test.com' }) });

expect(result.statusCode).toBe(409);

});

});

// 주문 생성 - 트랜잭션으로 원자성 보장

import { TransactWriteCommand } from '@aws-sdk/lib-dynamodb';



export const createOrder = async (userId, productId, quantity) => {

const orderId = uuidv4();

const now = new Date().toISOString();



// 트랜잭션: 주문 생성 + 재고 감소를 원자적으로 처리

await dynamoDB.send(new TransactWriteCommand({

TransactItems: [

{

// 1. 주문 아이템 생성

Put: {

TableName: TABLE_NAME,

Item: {

pk: `USER#${userId}`,

sk: `ORDER#${orderId}`,

orderId, productId, quantity,

status: 'PENDING',

createdAt: now

},

ConditionExpression: 'attribute_not_exists(pk)'

}

},

{

// 2. 재고 감소 (재고 부족 시 트랜잭션 전체 롤백)

Update: {

TableName: TABLE_NAME,

Key: { pk: `PRODUCT#${productId}`, sk: 'INFO' },

UpdateExpression: 'SET stock = stock - :qty',

ConditionExpression: 'stock >= :qty',  // 재고 체크!

ExpressionAttributeValues: { ':qty': quantity }

}

}

]

}));



return orderId;

};

// DynamoDB Streams → Lambda → SNS → 사용자 알림

import { SNSClient, PublishCommand } from '@aws-sdk/client-sns';



const snsClient = new SNSClient({ region: 'ap-northeast-2' });



export const notificationHandler = async (event) => {

for (const record of event.Records) {

if (record.eventName !== 'MODIFY') continue;



const newImage = record.dynamodb.NewImage;

const oldImage = record.dynamodb.OldImage;



// 주문 상태 변경 감지

if (newImage.sk?.S?.startsWith('ORDER#') &&

oldImage.status?.S !== newImage.status?.S) {



const message = {

userId: newImage.pk.S.replace('USER#', ''),

orderId: newImage.sk.S.replace('ORDER#', ''),

oldStatus: oldImage.status?.S,

newStatus: newImage.status.S,

timestamp: new Date().toISOString()

};



// SNS로 알림 발행

await snsClient.send(new PublishCommand({

TopicArn: process.env.ORDER_NOTIFICATION_TOPIC_ARN,

Message: JSON.stringify(message),

MessageAttributes: {

eventType: {

DataType: 'String',

StringValue: 'ORDER_STATUS_CHANGED'

}

}

}));

}

}

};

// 지수 백오프 재시도 유틸리티

export const withRetry = async (fn, maxRetries = 3) => {

let lastError;

for (let attempt = 0; attempt < maxRetries; attempt++) {

try {

return await fn();

} catch (error) {

lastError = error;

// 재시도 가능한 에러인지 확인

const retryableErrors = [

'ProvisionedThroughputExceededException',

'ThrottlingException',

'RequestLimitExceeded',

'ServiceUnavailable'

];



if (!retryableErrors.includes(error.name)) {

throw error;  // 재시도 불가능한 에러는 즉시 throw

}



// 지수 백오프: 100ms, 200ms, 400ms...

const delay = Math.pow(2, attempt) * 100;

await new Promise(resolve => setTimeout(resolve, delay));

}

}

throw lastError;

};



// 사용 예시

const result = await withRetry(() =>

dynamoDB.send(new PutCommand({ TableName, Item }))

);

import { ExecuteStatementCommand } from '@aws-sdk/client-dynamodb';



// PartiQL로 조회

const result = await dynamoDB.send(new ExecuteStatementCommand({

Statement: "SELECT * FROM MyApp WHERE pk = 'USER#user001'"

}));



// 조건부 업데이트

await dynamoDB.send(new ExecuteStatementCommand({

Statement: "UPDATE MyApp SET status = 'SHIPPED' WHERE pk = 'USER#user001' AND sk = 'ORDER#001'"

}));

// DynamoDB Export 설정 (AWS CLI)

aws dynamodb export-table-to-point-in-time \

--table-arn arn:aws:dynamodb:ap-northeast-2:123456789:table/MyApp \

--s3-bucket my-backup-bucket \

--s3-prefix dynamodb-exports/ \

--export-format DYNAMODB_JSON



# 내보낸 데이터를 Athena로 분석

CREATE EXTERNAL TABLE dynamodb_export (

Item struct<pk:struct<S:string>, sk:struct<S:string>, name:struct<S:string>>

)

ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'

LOCATION 's3://my-backup-bucket/dynamodb-exports/';

# .github/workflows/deploy.yml

name: Deploy Serverless App



on:

push:

branches: [main]

pull_request:

branches: [main]



jobs:

test:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

- uses: actions/setup-node@v3

with:

node-version: '20'

- run: npm ci

- run: npm test



deploy-dev:

needs: test

runs-on: ubuntu-latest

if: github.event_name == 'pull_request'

steps:

- uses: actions/checkout@v3

- uses: actions/setup-node@v3

with:

node-version: '20'

- run: npm ci

- name: Configure AWS credentials

uses: aws-actions/configure-aws-credentials@v2

with:

aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}

aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

aws-region: ap-northeast-2

- name: Deploy to dev

run: npx serverless deploy --stage dev



deploy-prod:

needs: test

runs-on: ubuntu-latest

if: github.ref == 'refs/heads/main'

steps:

- uses: actions/checkout@v3

- uses: actions/setup-node@v3

with:

node-version: '20'

- run: npm ci

- name: Configure AWS credentials

uses: aws-actions/configure-aws-credentials@v2

with:

aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}

aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

aws-region: ap-northeast-2

- name: Deploy to production

run: npx serverless deploy --stage prod