NestJS 분산 통신

API 게이트웨이 패턴 구현: 라우팅 정책과 upstream 장애 점검

API 게이트웨이는 단순 프록시가 아니라 외부 계약의 관문입니다. 라우팅, 인증, 제한, 집계, 장애 전파 기준을 한곳에서 검증합니다.

client 외부 계약 gateway auth / limit policy timeout / retry upstream 502 / 504 timeout -> fallback + trace
01

Route map과 외부 계약

공개 경로, upstream 서비스, 인증 스코프, rate limit 정책을 route 단위로 맞춥니다.

route 계약
02

Policy middleware와 upstream client

NestJS guard/middleware는 인증과 제한을 담당하고 provider client는 timeout, retry, circuit breaker 로그를 남깁니다.

policy 경계
03

Timeout과 장애 전파

upstream이 느리거나 죽었을 때 gateway가 무한 대기하지 않고 504/502, fallback, trace id를 일관되게 반환합니다.

장애 전파
04

정책 테스트와 timeout 로그

route map diff, auth/rate limit 테스트, upstream timeout 로그, trace id 샘플을 운영 기록으로 남깁니다.

trace 증거
책임
게이트웨이는 외부 계약, 인증 위임, rate limit의 단일 관문이다 서비스별로 권한 정책이 갈라지지 않도록 route map과 guard 적용 범위를 먼저 고정합니다.
route
경계
NestJS gateway module은 upstream client와 policy middleware를 분리한다 라우팅은 module/controller에서 드러내고 timeout, retry, circuit breaker 설정은 provider client에 붙여 추적합니다.
policy
Gateway E2E
upstream 장애와 정책 우회는 E2E 요청으로 재현한다 인증 누락, rate limit 초과, downstream timeout을 Supertest 또는 계약 테스트로 확인하고 trace id를 로그에 남깁니다.
timeout

API 게이트웨이 라우팅과 upstream 장애 검증 지점

Route와 auth 통과 요청이 route map, guard, rate limiter, upstream client, trace id 응답으로 이어지는지 확인합니다.
Upstream timeout 분기 인증 우회, rate limit 누락, upstream timeout을 재현하지 않으면 gateway가 장애를 정상 응답처럼 숨길 수 있습니다.
Gateway telemetry route map diff, latency percentile, 4xx/5xx 비율, timeout 로그를 배포 기록과 함께 남깁니다.

Gateway 운영 점검

질문: gateway가 인증, rate limit, upstream timeout을 같은 route 계약으로 처리하는가
순서: route map 작성 -> guard/middleware 정책 적용 -> upstream timeout과 fallback 테스트
위험: timeout과 circuit breaker가 없으면 downstream 장애가 gateway worker를 점유해 정상 route까지 느려집니다.