💥 16. 비동기 UX의 패러다임 전환 (Suspense & ErrorBoundary)

🎯 이 섹션을 읽고 나면:

• if (isLoading)과 if (isError)로 도배된 문제가 큰 컴포넌트를 구출할 수 있다.
• 컴포넌트의 책임을 "데이터 렌더링" 하나로만 극단적으로 좁히는 선언적(Declarative) 비동기 처리의 마법을 이해한다.
• 앱 어디서 에러가 발생하든 앱 전체가 하얗게 사라지지 않고(화이트아웃), 우아하게 부분 에러 화면을 띄워주는 아키텍처를 설계할 수 있다.

📋 목차

• 🤔 왜 알아야 하는가: 명령형 로딩/에러 처리의 장애
• 🏗️ 비유로 먼저 이해하기
• 🧩 극의 체득: 선언적 비동기 UX 설계하기
  • ✅ 1단계: 영호의 선언적 컴포넌트 설계
  • ✅ 2단계: 매니저(Suspense)와 점장(ErrorBoundary) 배치
  • ✅ 3단계: 기획 변경? 레고 조립하듯 쓱싹!
• 🌟 (심화 보너스) Next.js App Router와의 만남

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 12분 / 핵심 파트: 7분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영수(PM):"영철 님, 유저 프로필 페이지 들어갔을 때 로딩 빙글빙글 도는 스피너 말이에요. 지금은 전체 화면을 가리는데, 프로필 사진 쪽만 따로 돌고, 작성한 글 목록 쪽 따로 돌게 스무스하게 만들어주실 수 있나요? 아참, 글 목록 불러오다 에러 나면 거긴 '다시 시도' 버튼 달아주시고요!"
• 영철(신입):"네? 그럼 ProfileAvatar 컴포넌트 안에도 isLoading, isError 상태 만들고... PostList 컴포넌트 안에도 isLoading, isError 상태 만들어서 다 if (isLoading) return <Spinner/>를 넣어야겠네요... 코드가 3배로 불어날 텐데 ㅠㅠ"
• 영호(리드): "영철 님, 로딩과 에러 조건문이 컴포넌트 안에 많이 흩어져 있군요. 컴포넌트는 '데이터가 오면 어떻게 예쁘게 그릴까?' 단 하나에만 집중해야 합니다. 에러와 로딩 처리는 상위 경계로 올리세요. Suspense 와 ErrorBoundary 로 정리해 보겠습니다."

🤔 왜 알아야 하는가: 명령형 로딩/에러 처리의 장애

1~3년 차 프론트엔드 개발자들의 코드를 보면 십중팔구 아래와 같은 형태를 띕니다.

// ❌ 영철이의 흔한 명령형 비동기 컴포넌트 (관심사 혼재)
function UserProfile({ userId }) {
  const [data, setData] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  const [error, setError] = useState(null);
 
  useEffect(() => {
    fetchUserData(userId)
      .then(res => setData(res))
      .catch(err => setError(err))
      .finally(() => setIsLoading(false));
  }, [userId]);
 
  // 🚨 UI를 그리는 본연의 임무 전에 방어막(조건문)이 너무나도 많다!
  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage message={error.message} />;
 
  // 여기까지 살아남아야 겨우 진짜 목적(UI 렌더링) 달성 가능
  return <div>환영합니다, {data.name} 님!</div>;
}

이 방식의 치명적인 문제점은 다음과 같습니다.

1. 관심사 오염: 컴포넌트의 본질은 "데이터를 예쁘게 UI로 맵핑하는 것"인데, 데이터를 어떻게 가져올지, 실패하면 어떡할지 온갖 잡일에 시달립니다.
2. **"이 데이터는 진짜 있는가?":**TypeScript로 달아봐도 data는 초기에 null입니다. 따라서 밑에서 data.name을 쓸 때마다 불안증세(Optional Chaining data?.name)에 시달리게 됩니다.
3. UI 기획 변경 대응 불가: PM이 "로딩 바를 저 위쪽 헤더로 합쳐주세요"라고 하면, 로딩 상태를 또 부모로 끌어올리며(Lifting State Up) 대공사를 해야 합니다.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면?

1. **기존 방식 (영철이 햄버거 가게):**요리사(컴포넌트)가 패티를 굽다가 고기가 떨어지면(로딩), 자기가 직접 요리를 멈추고 홀에 나가 "손님, 고기 오는 중 ㅠㅠ" 팻말을 듭니다. 고기가 상했으면(에러) "손님 고기 상함!" 팻말을 들고요. 요리에 집중할 수가 없죠.
2. Suspense & ErrorBoundary 방식 (영호의 고급 레스토랑): 요리사는 "난 무조건 고기(데이터)가 있다고 가정하고 햄버거 조립만 한다" 라고 선언합니다.
   만약 고기가 아직 안 왔으면? 요리사는 주방 밖으로 소리를 지르며 쓰러집니다(Throw). 그럼 매니저(Suspense)가 튀어나와서 손님에게 우아하게 식전 빵(Spinner)을 대접하며 기다리게 합니다.
   만약 고기가 상했으면? 역시 소리지르며 쓰러지고, 점장(ErrorBoundary)이 뛰어나와 정중하게 사과 쿠폰(에러 UI)을 드립니다. 요리사는 오직 '요리'라는 본질에만 집중합니다!

이것이 리액트가 밀고 있는 "대수적 효과(Algebraic Effects)" 의 멘탈 모델입니다. 자식 컴포넌트에서 감당할 수 없는 사이드 이펙트(로딩, 에러)를 부모가 캐치하여 대신 처리하는 것 이죠.

🧩 극의 체득: 선언적 비동기 UX 설계하기

영철이의 문제가 컸던 코드를 Suspense 와 ErrorBoundary (React 18 & Next.js 시대의 표준 교양)를 써서 리팩토링해 봅시다. (현업에서는 React Query의 useSuspenseQuery 등과 결합해 많이 사용합니다.)

✅ 1단계: 영호의 선언적 컴포넌트 설계

우선 자식 컴포넌트는 에러고 같은 표현은 다 버리고 핵심 데이터만 보고 돌진하도록 뇌를 비웁니다.

// 🎯 1. 뇌를 비운 선언적 자식 컴포넌트 (성공한 미래만 바라본다)
function UserProfile({ userId }) {
  // isLoading? isError? 그런 건 부모님이 알아서 하십니다.
  // 나는 '데이터가 무조건 완벽하게 온 상태'라고 가정합니다!
  const { data } = useSuspenseQuery(fetchUserData, userId);
 
  // optional chaining(data?.name) 따위는 개나 줍니다. 데이터는 언제나 100% 있습니다.
  return (
    <div className="profile-card">
      <img src={data.profileImage} />
      <h3>환영합니다, {data.name} 님!</h3>
    </div>
  );
}

✅ 2단계: 매니저(Suspense)와 점장(ErrorBoundary) 배치

자식 컴포넌트에서 데이터를 가져오는 동안 던진(Throw) Promise 펜딩 상태와 Error 리젝션 상태를 부모 계층에서 잡아챕니다.

// 🎯 2. 비동기 책임을 모두 떠안은 부모 컨테이너
import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary'; // 외부 라이브러리 사용 강력 권장
 
function UserPage({ userId }) {
  return (
    <div className="page-layout">
      <h1>유저 페이지</h1>
 
      {/* 🔴 점장: 만약 안에서 치명적 에러가 나면 이 UI로 덮어씌움! */}
      <ErrorBoundary fallback={<div>프로필을 불러오다 서버가 터졌습니다 😭</div>}>
 
        {/* 🟡 매니저: 안에서 아직 데이터를 기다리는 중이면 이 Spinner를 그려줌! */}
        <Suspense fallback={<Spinner size="large" />}>
 
          {/* 성공한 미래만 그리는 요리사 컴포넌트 */}
          <UserProfile userId={userId} />
 
        </Suspense>
 
      </ErrorBoundary>
    </div>
  );
}

✅ 3단계: 기획 변경? 레고 조립하듯 쓱싹!

"영철씨, 프로필 말고 하단에 있는 '최근 작성 글 목록'도 따로 로딩 돌게 해주세요~"
과거엔 내부 내부 코드를 크게 고쳤겠지만, 지금은 자식 컴포넌트들은 건드리지 않고 부모의 레이아웃 껍데기만 튜닝하면 됩니다.

// 🎯 3. 극한의 분리 덕에 얻게 된 완벽한 UI 레이아웃 통제권
function UserPage({ userId }) {
  return (
    <>
      <ErrorBoundary fallback={<TextError />}>
        {/* 프로필은 프로필대로 따로 빙글빙글 돌고~ */}
        <Suspense fallback={<ProfileSkeleton />}>
          <UserProfile userId={userId} />
        </Suspense>
      </ErrorBoundary>
 
      <ErrorBoundary fallback={<Button>글 목록 갱신 실패. 재시도</Button>}>
        {/* 게시물 목록은 또 걔네대로 따로 빙글빙글 돕니다! (병렬 로딩) */}
        <Suspense fallback={<ListSkeleton />}>
          <UserPosts userId={userId} />
        </Suspense>
      </ErrorBoundary>
    </>
  );
}

이 구조 덕분에 특정 구역(예: 글 목록)에서 서버 에러가 오류가 나도, 프로필 렌더링 박스는 끄떡없이 살아남습니다. 화이트아웃(앱 전체가 하얗게 중단되는 현상)을 완벽히 방어하는 부분 장애 격리 시스템이 완성된 것입니다.

🌟 (심화 보너스) Next.js App Router와의 만남

Next.js의 신형 App Router(app/ 디렉토리)는 이 Suspense 와 ErrorBoundary 의 개념을 우주 끝까지 파일 시스템으로 끌어올렸습니다.

• Next.js에서 loading.tsx 파일을 만들면? 👉 자동으로 가장 가까운 layout.tsx 밑에 <Suspense fallback={<Loading />}> 껍데기를 몰래 씌워줍니다!
• error.tsx 파일을 만들면? 👉 몰래 <ErrorBoundary fallback={<Error />}> 껍데기를 씌워줍니다!

우리가 여태 손으로 짜던 복잡한 부모 컴포넌트 래핑 코드를, 그저 파일을 알맞은 위치에 배치하는 것만으로 라우팅 수준에서 대행해 주는 것입니다. (이 기법들이 등장한 근본 원리를 알면, Next.js 공식 문서가 얼마나 편의성을 극대화했는지 선명하게 체감할 수 있습니다.)

🏁 이번에 배운 내용 총정리

💡 한 줄로 기억하기
"컴포넌트는 눈물을 흘리지 않는다."
로딩과 에러는 내부에서 제각각 처리하지 말고 명시적으로 상위 경계로 올려라(Throw). Suspense와 ErrorBoundary가 사용자가 보는 화면 단위로 안정적인 경계를 만들어 줄 것이다.

📝 마무리 퀴즈

Q1. Suspense와 ErrorBoundary를 활용하여 비동기 처리를 선언적으로 분리했을 때, 자식 컴포넌트(요리사)의 내부 코드 질량이 극단적으로 가벼워지는 아키텍처적 이유는 무엇인가요?

• A) 클래스 컴포넌트의 LifeCycle 메서드를 Hooks로 오버라이딩하면서 콜백 과밀이 펴지기 때문.
• B) 자식 컴포넌트 내부에 존재하던 isLoading, isError 상태 변수와 그에 따른 방패막이 분기(if) 코드들이 통째로 뜯겨나가며 컴포넌트의 유일한 역할인 '데이터 존재 시의 UI 매핑'만 순수하게 남기 때문.
• C) Suspense 구문 내부의 자식들은 React 가상 돔(VDOM) 변환을 거치지 않고 직접 브라우저 네이티브 코드로 C++ 컴파일되어 그려지기 때문.

✅ 정답: B

💡 상세 해설: 정확합니다! 기존 패러다임에서 개발자는 한 지붕 한 가족 안에서 "아직 오지 않은 데이터", "망가진 데이터", "정상적인 데이터" 3가지 평행우주를 모두 if-else 문으로 케어해야 했습니다. 하지만 책임을 위임(Throw)함으로써 컴포넌트는 오직 "데이터가 도착한 아름다운 1개 우주"의 얼굴표정만 그릴 수 있게 되었고, 큰 가독성 상승을 이뤄냈습니다.

Q2. 사내 프로젝트에서 마이페이지를 리팩토링 중입니다. 유저 프로필 섹션과 결제 내역 섹션, 그리고 추천 상품 3개의 파트가 모두 독립적인 외부 API를 긁어오고 있습니다. 다음 중 Suspense와 ErrorBoundary를 설계하는 시니어의 가장 바람직한 시야는?

• A) 3개의 섹션을 전부 하나의 거대한 <Suspense>와 <ErrorBoundary>로 최상단 레이아웃에 몽땅 묶어서 단일 시스템으로 만든다. (하나라도 로딩 중이면 화면 전체 팽이 돌리기)
• B) 각 3개의 컴포넌트 파일 안에 직접 들어가서 catch 구문을 파고, 스피너 띄우는 if 코드를 욱여넣어 자급자족하게 한다.
• C) 각 섹션을 감싸는 <Suspense> 3개와 <ErrorBoundary> 3개를 부모 레이아웃에서 각각 독립(병렬)적으로 씌워준다. (프로필은 일찍 뜨면 먼저 보여주고, 결제 내역이 DB 연결 문제로 실패하더라도 나머지 페이지는 정상 렌더링 되도록 컴포넌트 섬(Island)을 구축한다)

✅ **정답:**C

💡 상세 해설: 마이크로 아키텍처의 정수입니다. A 방식은 결제 내역 API 응답이 혼자 5초 걸릴 경우, 이미 0.1초 만에 도착한 유저 프로필조차 사용자 눈앞에 안 보여주는 위험한 체감 병목(Waterfall bottleneck) 을 만듭니다. 반면 C 방식처럼 작게 격리(Colocated Boundary)시키면 각 구역이 자기 페이스대로 로딩 팽이를 돌리다 렌더링되며, 하나가 오류가 나도 나머지 2개는 화면에 살아남는 강인한 탄력성(Resilience) 을 확보하게 됩니다.

Q3. 영철이의 테스트 타임: 영수네 커뮤니티 프로필 페이지에서 ProfileCard, RecentPosts, BadgePanel이 각각 다른 API를 Suspense 기반 훅으로 읽고 있습니다. 영숙이 "프로필 사진은 먼저 보이고, 작성 글 목록만 실패하면 그 영역에 재시도 버튼을 보여주세요"라고 요청했습니다. 영호가 리뷰에서 통과시킬 설계는 무엇인가요?

• A) 세 컴포넌트를 하나의 최상위 <Suspense>와 하나의 <ErrorBoundary>로 감싸서 화면 전체가 한 번에 성공하거나 한 번에 실패하게 만든다.
• B) 각 데이터 섹션을 필요한 UX 단위대로 별도의 <Suspense>와 <ErrorBoundary>로 감싸고, 실패한 영역에만 fallback과 재시도 UI를 배치한다.
• C) RecentPosts 내부에서 try/catch와 isLoading 상태를 다시 만들고, 나머지 컴포넌트는 Suspense를 사용하지 않는다.

✅ 정답: B

💡 상세 해설: Suspense와 ErrorBoundary의 핵심은 로딩과 실패를 "컴포넌트 내부 조건문"이 아니라 "사용자가 경험하는 화면 구역" 단위로 격리하는 것입니다. 최상위 하나로 묶으면 작은 실패가 전체 페이지의 화이트아웃이 되고, 자식 내부로 되돌리면 선언적 비동기 구조의 장점을 잃습니다. 영호라면 API 단위가 아니라 사용자에게 독립적으로 보여줄 수 있는 UX 단위를 기준으로 경계를 나누라고 볼 겁니다.

🐣 영철이의 퇴근 일기

오늘은 "데이터를 가져오는 코드"와 "성공한 화면을 그리는 코드"를 한 컴포넌트 안에 계속 섞어둔 이유를 다시 봤다. 예전의 나는 로딩과 에러를 직접 처리해야 책임감 있는 코드라고 생각했는데, 사실 그건 화면 구역마다 실패 범위를 설계하지 못했다는 뜻에 가까웠다.

💡 "Suspense와 ErrorBoundary는 스피너 장식이 아니라, 로딩과 실패를 어느 UX 경계에서 격리할지 결정하는 설계 도구다."

영호 리드 님이 "API 개수 말고 사용자가 따로 볼 수 있는 화면 단위로 경계를 잡아보라"고 했던 말이 남았다. 내일부터는 새 비동기 컴포넌트를 만들 때 먼저 성공 UI, 로딩 fallback, 실패 fallback, 재시도 위치를 표로 적고 나서 코드를 짤 생각이다. 이제 영철은 조건문을 줄이는 사람이 아니라, 장애가 번지지 않는 화면 경계를 설계하는 사람이 되어야 한다.