AWS Lambda Web Functions 사용법: Express·Hono 서버리스 배포 방법

Lambda Web Functions와 기존 Lambda의 차이

AWS는 10월 12일 Web Functions를 발표하면서 기존 Lambda를 Event Functions로 부르는 명칭 변경도 안내했습니다. 기존 함수에 코드 수정이나 재배포를 요구하는 변경은 아닙니다. Web Functions는 HTTP 서버를 실행하고 하나의 실행 환경에서 여러 요청을 처리하는 모델입니다. SQS·S3 같은 이벤트 처리와 웹 서버 배포를 구분해 선택하세요. 근거: AWS 출시 발표

지원 런타임·리전과 배포 전 준비

출시 발표의 리전은 버지니아 북부, 오하이오, 오리건, 도쿄, 아일랜드입니다. 서울은 이 목록에 포함되지 않습니다. 최신 리전 지원과 조직 정책을 확인한 뒤 데이터베이스 위치도 함께 검토하세요. 근거: 출시 리전 목록

Node.js 24 환경, Web Functions 명령을 제공하는 AWS CLI, 인증된 계정·권한을 준비합니다. 기본 진입 파일은 패키지 루트의 index.js이고 다른 파일은 AWS_LAMBDA_NODEJS_ENTRYPOINT로 지정할 수 있습니다. AWS_LAMBDA_HTTP_ENDPOINT는 서버 수신 주소를 제공합니다. 근거: 런타임 문서

node --version
aws --version
aws sts get-caller-identity
aws lambda-web deploy help

조회 결과에서 계정과 역할을 확인하세요. 명령이 없으면 CLI 업데이트와 설치 경로를 점검합니다. 발표에 없는 최소 CLI 번호를 임의로 적용하기보다 사용 중인 버전의 도움말에서 실제 옵션을 확인하는 편이 좋습니다.

Express 최소 서버 만들기

별도 예제 폴더에 index.js를 만들고 package.json에 type: module을 지정합니다. 아래 코드는 로컬에서는 기본 주소를 사용하고 배포 환경에서는 AWS가 제공한 주소를 읽는 편집부 예시입니다.

import express from 'express';
const endpoint = process.env.AWS_LAMBDA_HTTP_ENDPOINT ?? '127.0.0.1:3000';
const [host, portText] = endpoint.split(':');
const port = Number(portText);
if (!host || !Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error('Invalid AWS_LAMBDA_HTTP_ENDPOINT');
}
const app = express();
app.get('/health', (_req, res) => res.json({ ok: true }));
app.get('/', (_req, res) => res.json({ framework: 'express' }));
app.listen(port, host);

Express index.js와 package.json을 같은 폴더에 저장하세요. 예제의 패키지 범위는 설치 시 해석되므로 생성된 lockfile을 보관하고 배포에 사용할 버전을 고정하는 것이 좋습니다.

npm install
AWS_LAMBDA_HTTP_ENDPOINT=127.0.0.1:3000 npm start
# 다른 터미널에서 확인
curl --fail http://127.0.0.1:3000/health

목표 응답은 ok가 true인 JSON입니다. 이는 예상값이며 이 글에서 HTTP 실행을 실측한 결과가 아닙니다. 공식 Express 배포 예시와 주소 설정은 AWS News Blog를 참고했습니다.

Hono는 Node.js HTTP 서버로 실행하기

Web Functions용 Hono 앱에는 기존 이벤트 방식의 hono/aws-lambda 핸들러 대신 Node.js HTTP 서버를 시작하는 형태를 사용합니다. @hono/node-server는 Hono를 Node HTTP 서버에 연결하는 구성 요소로, AWS 이벤트를 HTTP로 변환하는 Lambda 어댑터와 역할이 다릅니다. 근거: Hono Node.js 안내

import { Hono } from 'hono';
import { serve } from '@hono/node-server';
const endpoint = process.env.AWS_LAMBDA_HTTP_ENDPOINT ?? '127.0.0.1:3000';
const [host, portText] = endpoint.split(':');
const port = Number(portText);
if (!host || !Number.isInteger(port) || port < 1 || port > 65535) {
  throw new Error('Invalid AWS_LAMBDA_HTTP_ENDPOINT');
}
const app = new Hono();
app.get('/health', (c) => c.json({ ok: true }));
app.get('/', (c) => c.json({ framework: 'hono' }));
serve({ fetch: app.fetch, hostname: host, port });

Hono index.js와 package.json을 별도 폴더에 저장하고 같은 방식으로 설치·실행·health 요청을 확인합니다. TypeScript 프로젝트는 실행할 JavaScript 산출물과 시작 경로를 맞추세요. 이 예시는 빌드 단계를 줄이기 위해 JavaScript를 사용합니다.

AWS CLI로 배포하고 HTTPS 응답 확인하기

다음 명령은 클라우드 자원을 만들거나 갱신할 수 있습니다. 계정·리전·권한을 확인하고 준비한 앱 폴더 경로로 바꿔 사용하세요. 로컬 의존성과 패키징 결과에 실행 파일이 포함돼 있는지 먼저 확인합니다.

aws lambda-web deploy --name express-web-demo --code ./express-app
# Hono 예제는 별도 이름과 폴더로 배포
aws lambda-web deploy --name hono-web-demo --code ./hono-app

배포 명령과 폴더 지정 방식은 공식 CLI 예시에 근거합니다. 반환된 실제 HTTPS URL에서 /health와 대표 API를 확인하세요. CLI 완료 메시지만으로 인증·DB 연결·응답 스트리밍까지 정상이라고 판단하면 안 됩니다.

# 반환된 엔드포인트로 바꿔 실행
curl --fail --show-error 'https://[실제 엔드포인트]/health'

변경 배포는 새 revision과 엔드포인트가 가리키는 대상을 확인합니다. 테스트 환경을 먼저 검증하고 업무 데이터에 쓰기를 하는 경로는 되돌리기 방법까지 마련하세요.

동시 요청과 비용: 기존 서버 코드를 점검할 부분

여러 요청이 같은 프로세스에서 실행되므로 사용자별 상태를 전역 변수에 보관하지 마세요. 동기 CPU 작업은 다른 요청의 이벤트 루프도 막을 수 있습니다. 근거: 실행 모델

Web Functions는 요청, 활성 CPU, 실행 환경이 유지되는 동안의 메모리, 데이터 전송에 대해 과금합니다. I/O 대기 CPU를 줄인다는 설명을 전체 비용이 없다는 의미로 해석하지 마세요. 근거: 서비스·과금 개요

다중 리전과 사용자 도메인 적용 전 확인사항

공식 예시는 --regions로 여러 리전을 지정해 코드를 배포하고 지연 기반 라우팅을 구성합니다. 코드를 복제한다고 데이터베이스·세션 데이터까지 자동 복제되는 것은 아니므로 데이터 위치와 일관성 방식을 별도로 설계하세요. 근거: 다중 리전 배포 예시

사용자 도메인이나 AWS WAF를 적용하려면 엔드포인트 앞에 CloudFront를 구성하는 안내를 확인하세요. 근거: Web Functions 안내 캐시에는 사용자별 응답이 섞이지 않도록 인증·쿠키·헤더 처리와 캐시 키를 검토합니다.

실패 증상별 확인 순서

자주 묻는 질문

Lambda Web Adapter가 필요한가요?

Web Functions에서는 AWS 이벤트를 HTTP로 변환하는 어댑터가 필요하지 않습니다. Hono의 Node 서버 구성 요소와 혼동하지 마세요.

기존 Lambda를 바로 바꿔야 하나요?

기존 함수의 명칭 변경은 재배포를 요구하지 않습니다. 이벤트 처리와 웹 앱의 사용 목적을 구분해 이전 필요성을 판단하세요.

서울 리전 배포가 가능한가요?

10월 12일 출시 목록에는 서울이 없습니다. 이후 지원 확대 여부는 공식 리전 목록에서 다시 확인해야 합니다.

관련 서버리스 운영 안내

• Workers CPU·메모리 프로파일링
• Vercel CLI 도메인 검색·구매 승인