[Cloud] API 게이트웨이 — 모든 요청이 지나는 관문

인증, 요청 제한, 라우팅, 캐싱, 로깅/지표는 거의 모든 API가 공통으로 필요로 합니다. 이를 각 백엔드가 따로 구현하면 중복되고, 한 곳이라도 빠뜨리면 사고가 납니다.

API 게이트웨이는 모든 클라이언트 요청이 거치는 단일 관문에서 이 횡단 관심사를 중앙 처리합니다. 백엔드는 비즈니스 로직에만 집중하고, 클라이언트는 단일 진입점을 갖습니다. MSA(모놀리식 vs 마이크로서비스)에서 특히 중요한 패턴입니다.

한 클라이언트의 폭주나 공격이 백엔드를 마비시키지 않도록, 게이트웨이는 단위 시간당 요청 수를 제한합니다. 초과분은 429 Too Many Requests로 거절하고 정상 사용자를 보호합니다.

서버리스(서버리스(Lambda))처럼 호출당 과금되는 백엔드에서는 요청 제한이 비용 방어이기도 합니다 — 무한 호출로 청구서가 폭증하는 것을 막습니다(클라우드 비용 최적화). 정상 트래픽과 남용을 가르는 임계값 설정이 핵심입니다.

• 동기 — API 게이트웨이: 사용자가 결과를 즉시 기다리는 요청(로그인·조회·결제 승인). 받아서 응답을 돌려줌.
• 비동기 — 메시지 큐: 결과를 당장 안 기다려도 되는 후속(알림·집계·정산). 큐로 흘려 백엔드가 자기 속도로(메시지 큐와 이벤트).

흔한 패턴: 게이트웨이가 요청을 받아 즉시 응답하고, 무거운 후속 작업은 큐에 넣어 비동기로 처리합니다. "모든 걸 동기로"는 느리고 취약하고, "모든 걸 비동기로"는 즉시성이 필요한 곳에서 어색합니다.

웹훅은 외부 시스템(결제사·깃허브 등)이 우리 엔드포인트로 보내는 이벤트 알림입니다. 공개 엔드포인트라 누구나 위조 요청을 보낼 수 있으므로:

• 서명 검증: 발신자가 준 시크릿(시크릿·키 관리)으로 만든 서명을 확인해 진짜인지 검증
• 멱등 처리: 외부는 보통 재시도하므로 같은 이벤트가 중복 도착 → 두 번 처리해도 결과가 같게(메시지 큐와 이벤트의 멱등성)

검증 없는 웹훅 수신은 위조·재생 공격에 그대로 노출됩니다.

클라이언트가 POST /v1/orders 한 번을 보내면, 게이트웨이 안에서 요청 수신 → 인증 → 레이트리밋 → 요청 검증·변환 → 백엔드 라우팅 → 응답·캐시가 순서대로 일어납니다. 이 순서가 곧 진단 순서입니다 — 클라이언트가 받은 상태코드(401인지 429인지 502인지)가 게이트웨이 어느 단계에서 튕겨 나왔는지를 가리키기 때문입니다. 게이트웨이는 요청을 그냥 백엔드로 흘려보내는 게 아니라 아래 6단계의 관문을 통과시킵니다.

[클라이언트]  POST /v1/orders   (Authorization: Bearer …)
   │
   ① 요청 수신 + 경로 매칭          (/v1/orders → 라우트·메서드 결정, CORS 프리플라이트)
   │
   ② 인증(API키·JWT)                (authorizer가 토큰 검증 → 신원 확립)
   │
   ③ 레이트리밋·쿼터                (토큰 버킷 — 초과분은 여기서 429)
   │
   ④ 요청 검증·변환                 (스키마 검증, 헤더·경로·본문 매핑)
   │
   ⑤ 백엔드 라우팅                  (람다·서비스로 전달, 통합 타임아웃 적용)
   │
   ⑥ 응답 반환 + 캐시               (상태코드·본문 반환, 캐시 가능하면 저장)
   ▼
[클라이언트]  200 OK  (다음 동일 GET은 ⑥ 캐시로 즉시 응답 가능)

각 단계에서 무슨 일이 일어나고, 막히면 어떤 상태코드가 나오나:

즉 이 순서가 곧 진단의 지도입니다 — 401/403이면 ②인증, 429면 ③레이트리밋, 400이면 ④검증, 502/504면 ⑤백엔드까지 갔다가 실패한 것입니다. 그래서 4XX가 늘면 429(한도)인지 401(인증)인지부터 분해하고, 5XX면 게이트웨이가 아니라 뒷단을 봐야 합니다. 인증이 ②에서 라우트 단위로 붙는다는 사실은, 라우트 하나만 authorizer를 빠뜨려도 그 경로가 통째로 무인증으로 열린다는 뜻이기도 합니다 — 중앙 처리 구조의 강점이자 한 구멍의 대가입니다.

게이트웨이를 지나는 요청에는 타임아웃이 여러 층 걸려 있습니다. 클라이언트 → 게이트웨이(관리형은 통합 타임아웃 상한이 고정된 경우가 많습니다 — 예: 29초) → 백엔드/함수 → DB 순입니다. 이 층들의 관계를 설계하지 않으면 두 가지 사고가 납니다.

• 바깥이 먼저 끊기는 문제: 백엔드 타임아웃이 게이트웨이보다 길면, 클라이언트는 504를 받았는데 백엔드 작업은 계속 돌아갑니다. 사용자는 실패로 알고 재시도 → 같은 작업이 중복 실행됩니다. 규칙은 '안쪽으로 갈수록 짧게'(백엔드 < 게이트웨이 < 클라이언트), 그리고 게이트웨이 상한을 넘길 수 있는 작업은 애초에 동기로 받지 않는 것입니다(202 + 큐 — 본문의 비동기 분리가 필요한 진짜 이유가 여기에 있습니다).
• 재시도 폭풍(retry storm): 장애가 나면 클라이언트 재시도 × 백엔드 SDK 재시도 × 큐 재전달이 곱해져 원래 트래픽의 수 배가 몰리고, 회복하려는 시스템을 다시 눕힙니다(메시지 큐와 이벤트). 재시도는 한 층에서만, 지수 백오프 + 횟수 상한으로 겁니다. 그리고 쓰기 API에는 Idempotency-Key를 받아 같은 키의 중복 요청을 한 번만 처리합니다 — 웹훅에서 배운 멱등을 이번엔 우리 API가 제공하는 쪽이 되는 것입니다.