Next.js로 회복 탄력성 있는 시스템 구축하기
모던 웹 애플리케이션에서 고가용성과 성능을 보장하는 베스트 프랙티스.
TL;DR5
- 도구보다 아키텍처가 먼저: 회복 탄력성은 설계의 속성이다
- stale-while-revalidate가 붙은 ISR은 백엔드 장애에도 페이지를 살린다
- 재시도에는 백오프와 지터가 필요 — 서킷 브레이커가 연쇄 장애를 차단
- 에러 바운더리는 장애를 페이지가 아닌 위젯 단위로 격리한다
- 폴백 UI와 오프라인 내성은 패치가 아닌 일급 기능

아키텍처가 먼저
Next.js는 종종 모던 웹 애플리케이션의 백본 역할을 한다. 회복 탄력성을 확보하려면 좋은 아키텍처적 결정과 적절한 툴링이 함께 필요하다.
Server Components와 제대로 된 에러 바운더리를 활용하면, 전체가 다운되는 대신 우아하게 저하되는 극도로 탄탄한 웹 애플리케이션을 만들 수 있다.
정적 생성 vs SSR
가능하면 Incremental Static Regeneration(ISR)을 기본으로 한다. 백엔드 API가 일시적으로 다운되어도 사용자는 마지막으로 성공적으로 빌드된 버전을 계속 보게 된다.
트레이드오프는 실제로 존재한다. ISR은 신선함을 대가로 탄력성을 준다. SSR은 신선함을 주는 대신 백엔드에 대한 강한 의존성을 만든다.
// app/blog/[slug]/page.tsx
export const revalidate = 300; // 5분
export default async function Post({ params }) {
const post = await fetchPost(params.slug); // 캐시 + 재검증
return <Article post={post} />;
}
작년 Cloudflare 인시던트로 오리진 API가 40분간 다운됐을 때, y7.hk의 모든 ISR 페이지는 낡았지만 유효한 HTML을 계속 서빙했다. 같은 사이트의 SSR 페이지는 500을 뱉었다. 이 실험은 월 트래픽의 4%를 잃게 했고, 내 렌더링 전략을 영구히 바꿔 놓았다.
경험 법칙: 5~60분 정도 낡아도 되는 콘텐츠(블로그 포스트, 제품 페이지, 마케팅)는 ISR. 낡음이 제품을 깨뜨릴 때만 SSR(실시간 대시보드, 인증 상태, 실시간 데이터).
에러 바운더리는 격벽이다
바운더리가 없으면 실패한 위젯 하나가 페이지 전체를 무너뜨린다. 바운더리가 있으면 각 섹션이 독립적으로 실패한다.
// app/components/Section.tsx
'use client';
import { Component, ReactNode } from 'react';
export class Section extends Component<
{ children: ReactNode; fallback?: ReactNode },
{ hasError: boolean }
> {
state = { hasError: false };
static getDerivedStateFromError() {
return { hasError: true };
}
render() {
if (this.state.hasError) {
return this.props.fallback ?? <div className="opacity-50">이 섹션을 사용할 수 없습니다</div>;
}
return this.props.children;
}
}
사이드바 위젯, 댓글 영역, 분석 대시보드 등 독립적인 단위마다 각자의 바운더리로 감싼다. 사용자는 빈 화면 대신 위젯이 있던 자리의 회색 박스를 본다.
Web3 대시보드에서 RPC 타임아웃 하나가 포트폴리오 뷰 전체를 죽인 경험이 있다. 가격 티커를 감싸는 바운더리 하나가 세션을 살렸을 것이다.
재시도에는 백오프가 필요하다
무작정 재시도하면 장애가 커진다. 지수 백오프와 지터가 부하를 분산시키고 업스트림에 회복 시간을 준다.
async function fetchWithRetry<T>(
fn: () => Promise<T>,
attempts = 3,
baseDelay = 300
): Promise<T> {
for (let i = 0; i < attempts; i++) {
try {
return await fn();
} catch (err) {
if (i === attempts - 1) throw err;
const jitter = Math.random() * baseDelay;
await new Promise(r => setTimeout(r, baseDelay * 2 ** i + jitter));
}
}
throw new Error('unreachable');
}
내가 지키는 두 가지 규칙:
- 4xx는 절대 재시도하지 않는다. 404는 재시도해도 200이 되지 않는다.
- 총 대기 시간을 제한한다. 스피너를 8초 이상 보고 있으면 폴백 UI를 보여주고 사용자가 계속 진행하게 한다.
서킷 브레이커가 연쇄 장애를 차단한다
재시도는 일시적 에러를 해결한다. 서킷 브레이커는 지속적인 장애를 해결한다. 백엔드가 30초째 실패 중이라면 더 이상 두드리지 말고 회로를 열어 즉시 저하된 응답을 내놓는다.
class Breaker {
private failures = 0;
private openUntil = 0;
constructor(private threshold = 5, private cooldown = 30_000) {}
async call<T>(fn: () => Promise<T>): Promise<T> {
if (Date.now() < this.openUntil) throw new Error('Circuit open');
try {
const result = await fn();
this.failures = 0;
return result;
} catch (e) {
if (++this.failures >= this.threshold) {
this.openUntil = Date.now() + this.cooldown;
}
throw e;
}
}
}
브레이커가 없으면 느린 업스트림이 멈춘 Node 프로세스들을 양산한다. 있으면 빠른 실패를 얻고, 업스트림이 돌아오는 순간 회복된다.
stale-while-revalidate를 활용한 엣지 캐싱
Cache-Control 헤더는 가장 저렴한 회복 탄력성 레이어다. stale-while-revalidate는 엣지가 마지막 캐시를 서빙하면서 백그라운드에서 새 버전을 가져오게 한다.
Cache-Control: public, s-maxage=60, stale-while-revalidate=600
“API 다운 = 사이트 다운”과 “API 다운 = 일부 사용자가 최대 10분 전 데이터를 봄”의 차이다.
폴백 UI는 기능이다
폴백은 무언가 고장 났을 때 보여주는 것이 아니라 설계의 일부다. 모든 비동기 섹션에는 세 가지 상태가 있다:
- 로딩: 최종 레이아웃과 일치하는 스켈레톤(레이아웃 시프트 없음).
- 성공: 실제 콘텐츠.
- 에러: 사용자가 여전히 작업을 할 수 있는 저하된 버전.
가격 위젯이 실패하면 빨간 에러 대신 마지막으로 캐시된 가격에 “12분 전 업데이트” 배지를 붙여 보여준다. 댓글 시스템이 다운되면 읽기 전용 스레드를 보여주고 입력창은 숨긴다.
오프라인 내성
Service Worker는 PWA만을 위한 것이 아니다. 앱 셸과 최근 방문한 페이지 5개를 캐시하는 최소한의 SW가 불안정한 호텔 와이파이와 3만 피트 상공에서 진짜 오프라인 내성을 준다. 나 같은 사람에게 이건 브라우징의 꽤 큰 비중이다.
// sw.ts — 정적 파일은 cache-first, 페이지는 network-first
self.addEventListener('fetch', (e) => {
const url = new URL(e.request.url);
if (url.pathname.startsWith('/_next/static/')) {
e.respondWith(caches.match(e.request).then(r => r ?? fetch(e.request)));
}
});
실제로 겪은 장애들
- Cloudflare 엣지 KV 장애: KV에 의존하는 모든 페이지가 500을 반환했다. ISR 페이지는 살아남았다.
- 트래픽 스파이크 중 업스트림 CMS가 나를 레이트 리밋했다. 브레이커가 없었고 Next.js가 CMS를 계속 두드리다가 IP가 하드 밴 됐다. 이제 모든 외부 호출은 30초 쿨다운이 있는 브레이커를 거친다.
<PriceTicker>하나가 WebSocket 끊김으로 대시보드 전체를 죽였다. 바운더리 추가 후 나머지 UI는 살아 있고 티커만 조용히 재연결했다.
회복 탄력성 체크리스트
- 5분 이상 낡아도 되는 콘텐츠에는 ISR/SSG
- 캐시 가능한 모든 라우트에
stale-while-revalidate - 독립적인 위젯마다 에러 바운더리
- 재시도에 지수 백오프 + 지터; 4xx는 재시도 금지
- 모든 외부 서비스 호출에 서킷 브레이커
- 모든 비동기 UI에 스켈레톤 + 폴백 + 에러 상태
- 앱 셸을 캐시하는 Service Worker
- 비중요 기능(분석, 추천)용 문서화된 킬 스위치
요점
회복 탄력성은 마지막에 볼트로 끼우는 기능이 아니다. 그것 자체가 아키텍처다. 렌더링, 캐싱, 페칭, UI — 모든 레이어에 실패 모드를 미리 설계한다. 일찍 심어 두면 장애가 될 뻔한 인시던트가 아무도 알아차리지 못하는 조용한 저하로 바뀐다.
블로그 더 보기
y7.hk의 모던 엔지니어링 아티클 해부
y7 읽기 엔진 스트레스 테스트: 콜아웃, diff 블록, KaTeX 수식, 원형 아바타 비디오, figure 갤러리, 스포일러, 폰트 스위처.
시차 사이에서 살아가기
67개국과 네 개의 생활 거점이 가르쳐준 것들 — 딥 워크, 시차, 그리고 아무도 요청하지 않은 프로덕트 만들기.
