💥 03. 에러 핸들링과 전역 콜백(Global Callbacks) 아키텍처

📋 목차

• ☕️ 영철이의 고민: "에러 토스트 창이 화면을 다 덮어버려요!"
• 🤔 왜 알아야 하는가: 댐을 어디에 건설할 것인가?
• 1. 최상단 수문장: Global Cache Callbacks 세팅
• 2. Error Boundary의 아름다운 결합 (Declarative UX)
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 만약 유저 토큰이 갓 만료되어서 터진 '401 Unauthorized API' 호출이 1초 사이에 5개가 동시다발적으로 돌아갔다면, 브라우저에 '로그인 해주세요' 토스트 알림을 5개 동시에 띄우고 유저한테 욕먹을 건가요?"

☕️ 영철이의 고민: "에러 토스트 창이 화면을 다 덮어버려요!"

(목요일 오후, 화면을 빼곡히 덮은 빨간색 실패 알람 창들에 식은땀을 흘리는 영철)

🐣 영철: 저기... 🦁 리드 님. 제가 각 useQuery 컴포넌트마다 아래처럼 방어 로직을 참 잘 짜놨거든요?

const { data, isError, error } = useQuery(['user'], fetchUser);
 
useEffect(() => {
  // 💥 각 컴포넌트의 독단적인 에러 핸들링
  if (isError) {
    if (error.response.status === 401) {
      toast.error("토큰이 만료되었습니다. 다시 로그인 해 주세요.");
      router.push('/login');
    }
  }
}, [isError, error]);

근데 갑자기 백엔드(영수) 님이 잠시 배포한다고 서버를 10초 내렸거든요? 그 사이에 제 대시보드 화면에 있던 10개의 위젯(각각 다른 API 호출 중)이 일제히 응답을 못 받더니, 에러 토스트(알림창)가 우다다다 엄청나게 파바박 뜨면서 화면을 벌겋게 덮어버렸어요 ㅠㅠ.

🦁 영호: 영철 님... API 하나하나의 아주 끄트머리인 로컬(Local) 컴포넌트 단위 에서 저렇게 "인증 에러"나 "500 서버 붕괴 에러" 같은 치명적인 상태를 다루려고 하니까 10중 폭발이 치는 겁니다.
이런 중대한 공통 에러는 컴포넌트 내부(로컬)에서 잡는 게 아닙니다. 어차피 모든 네트워크 비동기 에러가 귀결되어 쏟아지는 최상단 중앙 댐, 바로 QueryClient의 캐시(Cache) 전역 콜백 단에서 통합 타격을 가해야죠.

🤔 왜 알아야 하는가: 댐을 어디에 건설할 것인가?

우리는 그동안 에러 처리를 할 때마다 useQuery 혹은 useMutation 설정 객체의 onError 콜백이나 isError 상태 변수만 바라보았습니다. 이건 "자신의 컴포넌트만 지키는 작은 우산"입니다.

• 문제점 1: 영철이의 사례처럼 A 컴포넌트, B 컴포넌트, C 컴포넌트가 동시에 401 에러를 만났을 때, 코드 중복이 끔찍하게 일어납니다.
• 문제점 2: useMutation({ onError: ... }) 안쪽에 로그인을 튕구는 로직을 넣어두면? 다른 개발자가 나중에 똑같은 로그인 연동 Mutation을 만들 때마다 방어 코드를 "복붙"해야 합니다. 누군가 하나라도 까먹으면? 곧장 보안 버그가 됩니다. (TkDodo 아티클 #11 참조)

진짜 성숙한 5년 차의 프론트엔드 라면, 개별 컴포넌트의 우산을 다 버리고 QueryCache 와 MutationCache 라는 가장 높은 하늘에 전천후 방어 돔(전역 콜백) 을 치는 아키텍처를 세팅해야 합니다.

1. 최상단 수문장: Global Cache Callbacks 세팅

React Query v5(App Router) 환경의 QueryClient 생성 팩토리 코드로 돌아가 봅시다(Basic 09강 참조). 여기에 진정한 의미의 방어 시스템을 결합합니다.

// 📝 app/providers/get-query-client.ts
import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';
import { toast } from 'react-hot-toast'; // 글로벌 토스트 라이브러리 예시
 
function makeQueryClient() {
  return new QueryClient({
    // 🚀 [1] 데이터를 가져오는 Query(GET) 전역 에러 제어
    queryCache: new QueryCache({
      // 지구상의 어떤 useQuery 훅에서 에러가 터지든 결국 이곳으로 한 번 불려옵니다.
      onError: (error, query) => {
        // 백그라운드 재귀(Refetch) 중에 발생한 에러는 짜증 나니까 살짝 무시하고...
        if (query.state.data !== undefined) {
          toast.error(`최신 데이터를 가져오는 데 실패했습니다: ${error.message}`);
          return;
        }
        
        // 치명적인 401, 500 전역 라우팅 핸들링 로직은 오로지 이 한 곳에 응집시킴!
        if (error.status === 401) {
          toast.error('세션이 만료되었습니다.');
          window.location.href = '/login'; // 글로벌 로그인 강제 이동 (단 1회 폭발)
        }
      },
    }),
 
    // 🚀 [2] 데이터를 바꾸는 Mutation(POST/DELETE) 전역 에러 제어
    mutationCache: new MutationCache({
      onError: (error, _variables, _context, mutation) => {
        // 해당 Mutation을 호출한 컴포넌트에서 "나 스스로 onError 처리 잘 해놨어요!" 
        // 라고 선언한 경우(meta 객체를 통해)에는 전역 토스트를 띄우지 않고 로컬에 맡김 
        if (mutation.meta?.bypassGlobalError) return;
 
        toast.error(`저장 중 오류가 발생했습니다: ${error.message}`);
      }
    }),
  });
}

이제 전 세계 컴포넌트 100군데에서 퍼져있던 401 인증 튕김 로직이나 isError 잡동사니 코드들이 순삭 증발합니다. UI 개발자는 그저 "화면에 데이터 예쁘게 그리기" 에만 집중하게 되죠!

2. Error Boundary의 아름다운 결합 (Declarative UX)

🐣 영철: 아 전역 처리 쩌네요! 근데 로컬 쪽에선 "데이터 자체가 박살나서 isError === true 일 때, 아예 화면 대신 '빨간색 에러 났어 힝구' 컴포넌트(Fallback UI)를 그려줘야" 할 때도 있잖아요. 그건 결국 개별 컴포넌트에서 if (isError) return <div>에러남</div> 써야 하는 거 아닌가요?

🦁 영호: 네, 맞습니다. 하지만 컴포넌트 안쪽에 if (isError) 도배를 시작하는 짓도 끔찍하긴 매한가지죠. 에러가 났을 때 "UI를 무엇으로 (선언적으로) 렌더링 할 것인가"는 React 본연의 갓-기능인 Error Boundary 에게 위임해야 합니다.

React Query 옵션 중 throwOnError: true (v5 변경점, 예전엔 useErrorBoundary) 를 켜면, 훅 내부에서 잡고 있던 꼬리가 React의 기본 에러 시스템으로 탁! 던져집니다(throw).

export const todoOptions = {
  detail: (id: number) => queryOptions({
    queryKey: ['todos', id],
    queryFn: fetchTodoDetail,
    // 🔥 마법의 지시어: "에러 나면 내가(isError) 쥐고 있지 않고 에러 바운더리로 폭탄 던질게!"
    throwOnError: true,
  }),
};

이렇게 하면, 이제 이 데이터를 소비하는 컴포넌트 코드는 불순물이 1g도 안 섞인 "순수 데이터 정상 렌더링 코드" 로 극한의 캡슐화가 됩니다.

import { ErrorBoundary } from 'react-error-boundary';
import { Suspense } from 'react';
 
// 화면 최상단 또는 페이지 레이아웃 단
function Page() {
  return (
    // 터진 폭탄을 캐치해서 예쁜 "다시 시도" 에러 카드 그려주는 우산 ☂️
    <ErrorBoundary fallback={<ErrorFallbackCard />}>
      <Suspense fallback={<Spinner />}>
        {/* 🎉 이 녀석 내부엔 온갖 예외 제어물(if isLoading, if isError)이 아예 없습니다! */}
        <PureTodoDetail id={1} />
      </Suspense>
    </ErrorBoundary>
  )
}

이 패턴이 바로 선언적 비동기 UX의 정점, 이른바 "Suspense + Error Boundary + React Query" 대통합 패턴입니다.

🐣 영철이의 퇴근 일기

와씨... 아까 백엔드 401 터졌을 때 내 화면에 뻘건 토스트 알림창 12개 우르르 쏟아진 거 생각하면 어지러운데, 이걸 최상단 QueryCache 로 넘기니까 12개가 아니라 깔끔하게 한 번 딱 걸러서 로그인 창 튕겨주는 거 무빙 지렸다...

💡 오늘의 교훈: "로컬 훅(onError, isError)에서 모든 똥을 다 치우려고 하지 마라. 치명적인 인증 에러나 500 터짐은 가장 위쪽 전역 캐시(QueryCache, MutationCache) 댐으로 몰아버리고 (로직 격리), 로컬 UI 에러 화면은 폭발물 던지기(throwOnError: true) 로 Error Boundary한테 짬처리하자!"

결국 시니어 영호 님이 항상 짜르치던 "너의 컴포넌트가 너무 많은 걸 알고 있게(결합도 높게) 하지 마라"는 철학이 상태 관리뿐만 아니라 에러 방어망(Defensive UX) 설계에도 똑같이 통하는 거였다. 소름 돋는다 즌쯔... 오늘은 맥주 말고 에스프레소 마시고 이 철학을 뇌에 각인 시켜야지. ☕️

📝 배운 내용 점검하기 (Quiz)

Q. 전역 MutationCache 안에 토스트 실패 알림(onError)을 달아두었습니다. 그런데 개발 중, 어느 한 특정 버튼(게시글 좋아요 취소) 만큼은 전역 에러 팝업을 띄우지 않고 조용히 뒷단에서 처리하거나 다른 스타일로 예외 처리를 하고 싶어졌습니다. 이때 팩토리 전역 코드를 더럽히지(수정하지) 않고, 해당 로컬 컴포넌트 쪽의 Mutation에서 전역 콜백을 "우회(Bypass)" 할 수 있게 알려주는 가장 권장되는 React Query 문법/옵션은 무엇입니까?

• A) 훅 옵션에 ignoreGlobalError: true 같은 자체 내장 옵션을 건다.
• B) 불가능하다. 전역 캐시에 박힌 로직은 무조건 지구상 모든 훅에 동일하게 적용되므로 우회할 수 없다.
• C) useMutation ({ meta: { bypassGlobalToast: true } }) 처럼 커스텀 인계 메타객체(meta) 안에 키 값을 달아, 전역 캐시가 그 값을 읽고 분기 처리하게 만든다.

✅ 정답: C

💡 상세 해설:

• 원리 설명: React Query의 useQuery 와 useMutation 에는 아주아주 강력하지만 유저들이 잘 모르는 마법의 뒷구멍인 meta 객체가 존재합니다(TkDodo 아티클 #11 역설). 이 meta 객체의 키와 값들은 오직 정보 전달 용도로만 쓰이며, 최상단 글로벌 에러 핸들러인 (QueryCache/MutationCache 의 콜백)의 4번째 인자로 고스란히 배달됩니다. 글로벌 핸들러는 이 meta 꼬리표를 읽어보고 "아! 이 Mutation은 글로벌 토스트를 띄우지 말라고 부탁했구나! 무시하자~" 라고 스마트하게 우회 분기를 태울 수 있습니다.
• 오답 피드백: "영철 님, A번처럼 라이브러리에 없는 맘대로 지어낸 이름 넣으면 TS 에러 나고 터져요! 오로지 개발자 전용 통신 규약인 meta 옵션을 통해서만 훅 깊숙한 안쪽에서부터 최상단 전역 캐시 대기권 바깥쪽으로 무전(signal)을 때릴 수 있는 겁니다."
• 📌 핵심 기억법: 로컬 훅이 전역 댐 통제실에 몰래 귓속말을 보내는 유일한 뒷구멍, meta 옵션!