Lambda 프록시 통합 vs 표준 통합: API Gateway 이벤트 객체 구조 완전 분석
API Gateway를 처음 설정할 때 'Lambda 프록시 통합' 체크박스 하나가 이벤트 객체 구조 전체를 바꾼다는 사실을 모르고 넘어가면, Lambda 핸들러에서 event.body 가 undefined 로 찍히는 상황을 마주하게 된다. 이 글은 두 통합 방식의 내부 동작 차이와 그로 인한 이벤트 포맷 변화를 실제 운영 관점에서 정리한다. TL;DR — Lambda 프록시 통합 핵심 요약 항목 Lambda 프록시 통합 Lambda 표준 통합 이벤트 구조 API Gateway가 고정 포맷으로 전달 매핑 템플릿으로 개발자가 직접 정의 요청 매핑 템플릿 불필요 (자동 처리) 필수 작성 응답 매핑 템플릿 불필요 (Lambda 반환값 그대로) 필수 작성 HTTP 상태코드 제어 Lambda 반환 객체 내 statusCode 필드 API Gateway 매핑 규칙 헤더 접근 event.headers 로 직접 접근 매핑 템플릿에서 명시적으로 추출 필요 설정 복잡도 낮음 높음 (VTL 템플릿 작성) 유연성 포맷 고정 완전한 변환 제어 가능 Lambda 프록시 통합이란 무엇인가 API Gateway에서 Lambda를 백엔드로 사용할 때 두 가지 통합 방식을 선택할 수 있다. Lambda 프록시 통합(Lambda Proxy Integration) 은 API Gateway가 HTTP 요청 전체 — 메서드, 경로, 쿼리스트링, 헤더, 바디 — 를 하나의 표준화된 JSON 이벤트 객체로 패키징해서 Lambda에 그대로 전달하는 방식이다. 반대로 Lambda 표준 통합(Lambda Non-Proxy Integration) 은 개발자가 Velocity Template Language(VTL)로 작성한 매핑 템플릿을 통해 요청과 응답을 변환하는 방식이다. 프록시 통합에서 'Pro...