[React] ErrorBoundary & Suspense, 거의 완벽한 사용방법 가이드

📒 ErrorBoundary & Suspense, 거의 완벽한 사용방법 가이드

---

잘 만든 Errorboundary
백개의 try-catch 안 부럽다.

프론트 개발을 계속하다 보니 다양한 상황을 마주치게 되었고, 그에 따른 적절한 화면 표현의 중요성을 점차 느껴갔습니다.

대표적으로 서버 데이터에 대한 로딩과 에러 처리가 있죠.

끊임없이 사용해 보고 개선해 보니 1년이 지난 지금에서야 어느 정도 감이 잡히는 거 같아 그 방법을 공유해보려 합니다.

이 글은 실제 서비스에서의 적용 방법에 대해 설명하는 글이기 때문에 ErrorBoundary와 Suspense에 대한 개념은 아래 글을 참조해 주세요.

• ErrorBoundary를 통한 선언적인 에러 핸들링, react-query를 이용한 재호출 방법
• Suspense을 사용해 선언적으로 로딩 화면 구현하기

ErrorBoundary와 Suspense를 실제 프로덕트에서 어떻게 사용했는지 소개드립니다.

📌 왜 사용해야 하는가

사실 “왜” 사용하는지가 가장 중요하겠죠.

한 줄로 요약하자면 “한 곳에서 관리할 수 있고, 선언적으로 사용할 수 있기 때문”입니다.

더 자세히 설명하자면 다음과 같습니다.

🔎 미사용 예제

function MyComponent() {
  // 데이터와 로딩, 에러 상태를 관리하는 state를 선언합니다.
  const [data, setData] = useState(null);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    // 컴포넌트가 마운트될 때 데이터를 가져오는 함수를 호출합니다.
    const fetchData = async () => {
      setIsLoading(true); // 로딩 시작
      try {
        const result = await getData()
        );
        setData(result); // 데이터 설정
        setError(null); // 오류 초기화
      } catch (error) {
        setError(error); // 오류 설정
      } finally {
        setIsLoading(false); // 로딩 종료
      }
    };

    fetchData();
  }, []);

  // 로딩 중일 때 로딩 표시, 에러가 있을 때 에러 메시지를 표시하고,
  // 데이터가 있을 때 데이터를 표시합니다.
  return (
    <div>
      {isLoading ? (
        <div>Loading...</div>
      ) : error ? (
        <div>Error: {error.message}</div>
      ) : (
        <div>{data}</div>
      )}
    </div>
  );
}

export default MyComponent;

 

한 컴포넌트 내에서 useEffect를 이용해 데이터를 호출하고,
try-catch와 각각의 상태를 통해 에러와 로딩 상태를 표시하는 모습은 보기만 해도 어지럽죠.

 

그 이유는 한 컴포넌트에 너무나 많은 역할이 부담되었기 때문입니다.

 

이러한 역할들을 표시하기 위해서는 당연히 그 컴포넌트 내 코드가 포함되어야 할 것이고,
이들은 한데 뒤섞여 가독성을 망쳐버립니다.

 

그렇다면 이러한 역할들을 분리한다면 어떤 모습일까요?

🔎 역할 분리

<ErrorBoundary FallbackComponent={<span>에러 발생</span>}> // 에러상태 분리
  <Suspense fallback={<span>로딩중...</span>}> // 로딩상태 분리
    <MyComponent />
  </Suspense>
</ErrorBoundary>

function MyComponent() {
  const { data } = useSuspenseQuery({ queryKey: ['data'], queryFn: getData })
  return <div>{data}</div>
}

export default MyComponent;

 

우선 로딩상태가 감지되었을 땐 Suspense가 로딩상태에 대한 대체 UI를 표시하고,

에러상태가 감지 되었을 땐 ErrorBoundary가 에러상태에 대한 대체 UI를 표시하게 됩니다.

 

그러면 MyComponent에서는 로딩, 에러 상태에 대한 로직을 제거할 수 있어,

정신없는 상태관리와 조건부 렌더링이 사라지게 되어 성공했을 때만 작성할 수 있게 됩니다.

 

게다가 Suspense와 ErrorBoundary를 사용하기 위해 필요한 서버 상태관리 도구인 tanstack-query(react-query)에 의해 useEffect 같은 사이드 이펙트까지 사라지니 말도 안 되게 깔끔해진 것을 확인할 수 있습니다.

 

그럼 설계 방법을 설명하기 전 필요한 라이브러리를 소개합니다.

📌 사전 설치

$ npm i @tanstack/react-query react-error-boundary react-toastify

• tanstack-query (react-query)

요즘에는 거의 대세라고 할 수 있죠.

서버 상태를 깔끔하게 관리하는 역할뿐 아니라 Loading 상태를 throw 해 Suspense가 catch 할 수 있도록 기능을 제공합니다.

또한 에러 발생 시 해당 쿼리를 refetch 하는 기능도 제공하니 필수적으로 설치해 줍니다.

이 글에서는 v5 버전을 사용합니다.

 

• react-error-boundary

ErrorBoundary를 사용하기 위해서는 클래스 컴포넌트의 강력한 생명주기 기능을 필수적으로 이용해야 합니다.

클래스형으로 직접 ErrorBoundary를 구현하기 귀찮으니 잘 만들어진 패키지를 설치합니다.

 

• react-toastify

대체 UI를 표시하지 않고 사용자에게 에러가 발생했음을 알리는 토스트 메시지 라이브러리입니다.

다른 방식으로 에러 알림을 표현해도 괜찮습니다.

📌 에러 상태의 종류 분류하기

로딩이야 서버 데이터 받기 전, 받은 후로만 나뉘어서 달리 생각할 것이 없지만 에러 상태는 그렇지 않죠.

그래서 저는 다음과 같이 분리해서 구분하기로 했습니다.

🔎 JavaScript 에러

타입스크립트를 사용해서 컴파일 시점에 에러를 잡아내더라도 100% 완벽하게 할 순 없습니다.

참조 오류가 발생했을 때 에러가 최상위 실행 컨텍스트까지 전파되면 앱이 crush 됩니다.

이 경우 에러 메시지를 error.message로 잡아낼 수 있지만, 사용자에게 보여줄 필요가 없기에 default message로 처리합니다.

🔎 합의된 에러 (error.response.data)

http status가 에러 상태여도 Error 객체의 error.response.data를 통해 데이터를 받을 수 있습니다.

이를 통해 특정한 상황에서의 에러를 서버 측과 정의해 어떤 에러인지 표현할 수 있습니다.

이러한 기능을 구현하기 위해서는 서버측과 어떤 데이터 구조로 전송할 것인지, 어떤 코드가 어떠한 의미인지를 합의한 후 계속해서 다듬는 과정이 필요합니다.

 

좋은 예시로 카카오 쇼핑에서 공개한 에러 데이터 구조와 합의된 에러 코드로 참고할 수 있습니다.

응답 코드 및 에러 코드

🔎 http 요청 에러 (error.response)

서버 측에서 예외처리가 되어있지 않아 error.response.data가 없는 경우에 해당합니다.

서버 개발 시 가능한 모든 예외 상황을 처리해 클라이언트 측에서 정보를 추출할 수 있도록 하는 것이 가장 이상적이나 현실적으로 100% 완벽한 상황은 없습니다.

이런 상황에서는 error.response.status 의 HTTP 상태 코드를 이용해 상황을 유추할 수 있도록 합니다.

 

상태 코드에 대한 정보는 다음을 참고해 주세요.

HTTP 상태 코드 - HTTP | MDN

🔎 응답이 없는 에러 (error)

이 경우는 주로 네트워크 문제나 서버가 다운되어 아무런 응답을 받지 못한 경우에 해당합니다.

또한 클라이언트 측에서 설정한 타임아웃이 초과되거나 DNS, CORS에 의해서 발생할 수 있으며 error.code로 식별합니다.

사실상 최후의 관문이라 할 수 있기 때문에 서버 요청에 대한 에러 처리는 이쪽 단계에서 마무리할 수 있도록 해야 합니다.

🔎 에러 데이터 파싱

import { AxiosError } from 'axios';

type ErrorCodeType = {
  [key: string]: { code: string; message: string; requireLogin?: boolean };
};

export const ERROR_CODE: ErrorCodeType = {
  default: { code: 'ERROR', message: '알 수 없는 오류가 발생했습니다.' },

  // axios error
  ERR_NETWORK: { code: '통신 에러', message: '서버가 응답하지 않습니다. \n프로그램을 재시작하거나 관리자에게 연락하세요.' },
  ECONNABORTED: { code: '요청 시간 초과', message: '요청 시간을 초과했습니다.' },

  // http status code 및 정의 된 코드
  400: { code: '400', message: '잘못된 요청.' },
  4001: { code: '4001', message: '요청에 대한 Validation 에러입니다.' },
  401: { code: '401', message: '인증 에러.', requireLogin: true },
  4011: { code: '4011', message: '인증이 만료되었습니다.', requireLogin: true },
  403: { code: '403', message: '권한이 없습니다.' },
} as const;

export const getErrorDataByCode = (error: AxiosError<{ code: number; message: string }>) => {
  const serverErrorCode = error?.response?.data?.code ?? '';
  const httpErrorCode = error?.response?.status ?? '';
  const axiosErrorCode = error?.code ?? '';
  if (serverErrorCode in ERROR_CODE) {
    return ERROR_CODE[serverErrorCode as keyof typeof ERROR_CODE];
  }
  if (httpErrorCode in ERROR_CODE) {
    return ERROR_CODE[httpErrorCode as keyof typeof ERROR_CODE];
  }
  if (axiosErrorCode in ERROR_CODE) {
    return ERROR_CODE[axiosErrorCode as keyof typeof ERROR_CODE];
  }
  return ERROR_CODE.default;
};

 

여러 가지 에러들을 한 곳에 정의해 두고 일반화하여 어디서든 동일한 에러 데이터 타입을 받도록 만들었습니다.

최대한 Type Safety 하게 에러 정보에 접근하며, 모든 에러 정보를 한 곳에 모아두기 때문에 새로운 에러 정보가 추가될 때는 ERROR_CODE만 수정하면 됩니다.

 

return 해주는 데이터는 [합의된 에러] > [http status] > [axios error] 순으로 우선순위를 둡니다.

 

인증 정보 관련 에러가 발생할 땐 requireLogin 속성을 이용해 사용자가 재로그인하도록 유도할 것입니다.

이에 대해 자세한 내용은 뒤에서 설명하겠습니다.

📌 에러 표현 방법에 따른 QueryClient 세팅

에러를 표현하는 방법은 많이 있겠지만 저는 2가지로 나누기로 했습니다.

🔎 데이터 표현(useQuery, useSuspenseQuery) → Fallback UI

get과 같이 단순히 데이터를 받아와 표현하는 화면에서 에러가 발생했을 때는 대체 UI를 표시합니다.

애초에 에러가 발생해 데이터를 받지 못했을 경우에 빈 화면을 표시하는 것보단 사용자에게 에러가 발생했음을 알리는 역할을 합니다.

🔎 사용자 상호작용(useMutation) → Toast Message

사용자가 클릭과 같은 상호작용을 통해 서버와 통신하는 경우는 토스트 메세지로 에러를 알립니다.

버튼을 눌렀는데 에러가 발생해 대체 UI로 전환되면 당황스러울 것 같다고 생각했습니다.

🔎 QueryClient 세팅

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      throwOnError: true,
    },
    mutations: {
      throwOnError: false,
      onError: (error: any) => {
        const errorData = getErrorDataByCode(error);
        toast.error(`[${errorData.code}] ${errorData.message}`);
      },
    },
  },
});

 

react-query의 QueryClient는 쿼리들의 defaultOptions 세팅을 할 수 있습니다.

여기서 주요하게 봐야 할 속성은 throwOnError입니다.

 

throwOnError는 기본값이 false며 true로 설정할 경우 발생한 에러를 전파하게 됩니다.

 

queries(useQuery)에서 발생한 에러는 throw 하여 ErrorBoundary로 받아버리고,
mutations(useMutation)에서 발생한 에러는 전파되지 않도록 설정 후 토스트 메세지만 띄워줄 겁니다.

📌 로딩 및 에러 처리 Component

본격적인 컴포넌트 설명에 앞서 간단하게 구조와 배치하는 방법에 대해 간략하게 설명하겠습니다.

🔎 구조

const Boundray = ({ children }: { children: React.ReactElement }) => {
  return (
    <ErrorBoundary>
      <Suspense>
        {children}
      </Suspense>
    </ErrorBoundary>
  );
};

• 기본적으로 데이터를 Fetching 하는 컴포넌트를 감싸는 구조를 갖고 있습니다.
• Suspense로 로딩, ErrorBoundary로 에러를 일괄적으로 처리합니다.

🔎 배치 방법

export const App = () => {
  return (
    <GlobalBoundary>
      <FetchBoundary>
        <ComponentA />
      </FetchBoundary>

      <FetchBoundary>
        <ComponentB />
      </FetchBoundary>

      <FetchBoundary>
        <ComponentC />
      </FetchBoundary>

      <FetchBoundary>
        <ComponentD />
      </FetchBoundary>
    </GlobalBoundary>
  );
};

• GlobalBoundary
  • 최상단에 배치해 화면 전체에 로딩, 에러 대체 UI를 표시합니다.
  • 미처 처리하지 못한 에러와 로딩 상태를 흡수할 수 있습니다.
  • 인증에 대한 처리를 담당합니다. ex) 로그인 화면으로 이동
• FetchBoundary
  • 감싼 컴포넌트의 로딩, 에러 대체 UI를 표시합니다.
  • 대체로 useQuery 혹은 useSuspenseQuery를 사용한 컴포넌트에 감아줍니다.

🔎 레이아웃 주의점

위와 같이 배치해 두면 든든하게 대체 UI를 표시하지만 주의해야 할 점이 있습니다.

기존 컴포넌트들과 대체 UI와의 스타일이 달라 급격하게 변하게 될 가능성이 있습니다.

저는 이러한 문제를 다음과 같은 방법으로 해결했습니다.

• Boundary 컴포넌트에 레이아웃 조정 속성을 Props로 받기
• 너무 좁은 공간에 위치한 컴포넌트의 경우 아이콘과 호버 카드로 대체 UI표시하기
• 컴포넌트의 레이아웃 관련 코드를 바깥으로 빼내기

방법은 정말 많으니 입맛에 맞게 자유롭게 커스텀하면 됩니다.

이 글의 예제에서는 기능 중심으로 설명을 드리기 때문에 이 부분은 생략했습니다.

🔎 GlobalBoundary

import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
import { GlobalErrorFallback } from './GlobalErrorFallback';
import { Loading } from '@components/Loading';

export const GlobalBoundary = ({ children }: { children: React.ReactNode }) => {
  return (
    <ErrorBoundary FallbackComponent={GlobalErrorFallback}>
      <Suspense fallback={<Loading />}>{children}</Suspense>
    </ErrorBoundary>
  );
};

import { FallbackProps } from 'react-error-boundary';
import { getErrorDataByCode } from '@components/boundary/getErrorDataByCode';
import { useNavigate } from 'react-router-dom';
import { Button, Container } from '@components/atoms';

export const GlobalErrorFallback = ({ error, resetErrorBoundary }: FallbackProps) => {
  const navigate = useNavigate();
  const navigatePage = (to: string) => {
    // resetErrorBoundary를 호출하여 에러를 초기화
    resetErrorBoundary();
    navigate(to);
  };
  const errorData = getErrorDataByCode(error);
  return (
    <Container.Column>
      <h1>{errorData.code}</h1>
      <h2>{errorData.message}</h2>
      <Button onClick={() => navigatePage(errorData.requireLogin ? '/login' : '/main')}>
        {errorData.requireLogin ? '로그인 이동' : '메인화면 이동'}
      </Button>
    </Container.Column>
  );
};

GlobalErrorFallback에 주목해 주세요.

 

ErrorBoundary가 catch 한 error 객체와 resetErrorBoundary를 props로 받아옵니다.

에러 데이터는 위에서 만든 getErrorDataByCode 함수에 error 객체를 넣어주어 변환합니다.

 

resetErrorBoundary는 ErrorBoundary에서 대체 UI를 띄워주는 상태를 초기화하는 함수입니다.

에러 상태를 해소시키고 다른 동작으로 이어가려면 반드시 호출해 주세요.

 

🔎 FetchBoundary

import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';
import { FetchErrorFallback } from './FetchErrorFallback';
import { Loading } from '@components/Loading';

export const FetchBoundary = ({ children }: { children: React.ReactElement }) => {
  return (
    <ErrorBoundary FallbackComponent={FetchErrorFallback}>
      <Suspense fallback={<Loading />}>{children}</Suspense>
    </ErrorBoundary>
  );
};

import { FallbackProps } from 'react-error-boundary';
import { Button, Container } from '../atoms';
import { getErrorDataByCode } from '@components/boundary/getErrorDataByCode';
import { useQueryErrorResetBoundary } from '@tanstack/react-query';

export const FetchErrorFallback = ({ error, resetErrorBoundary }: FallbackProps) => {
  const { reset } = useQueryErrorResetBoundary();
  const errorData = getErrorDataByCode(error);

  // 인증이 필요한 에러일 경우 상위 Boundary로 Error를 전파
  if (errorData.requireLogin) throw error;

  const handleClickReset = () => {
    resetErrorBoundary();
    reset();
  };

  return (
    <Container.Column>
      <h1>{errorData?.code}</h1>
      <h2>{errorData?.message}</h2>
      <Button onClick={handleClickReset}>재시도</Button>
    </Container.Column>
  );
};

import { FetchBoundary } from '@components/boundary/FetchBoundary';
import { Content } from '@components/Content';
import { Container } from '@components/atoms';

export const Error400 = () => {
  return (
    <>
      <Container.Card>
        <FetchBoundary>
          <Content param="400" />
        </FetchBoundary>
      </Container.Card>
      <Container.Card>
        <FetchBoundary>
          <Content param="4001" />
        </FetchBoundary>
      </Container.Card>
    </>
  );
};

• 각 컴포넌트마다 개별적인 로딩 및 에러 표시를 담당합니다.
• useQueryErrorResetBoundary의 reset을 사용해 에러 발생 쿼리 재호출 기능을 구현할 수 있습니다.

📌 마무리

쓰다 보니 글이 너무 길어진 것 같네요.

 

기능을 선언적으로 추상화한 라이브러리가 로딩, 에러와 관련된 데이터를 중간에서 처리하기 때문에 직접적인 흐름이 눈에 익지 않아 처음엔 어려움을 겪을 수도 있습니다.

그렇지만 번거로운 로딩 및 에러 처리를 일반화해 간편하게 처리할 수 있다는 점이 너무나도 매력적이기 때문에 도입을 강력 추천합니다.

 

마지막으로 이 기능은 프론트만 잘한다고 완성되는 기능이 아니기에 백엔드 개발자와 충분한 협의를 거치며 점차 완성도를 높여가야 한다는 것을 꼭 명심하세요.

🔎 전체 코드

이해가 잘 되지 않는 분들을 위해 react+express로 구현한 전체 코드를 깃허브에 올려놓았습니다.

코드를 받아 상태들의 흐름을 직접 체험해 보시는 것을 추천드립니다.

https://github.com/LasBe-code/error-boundary

GitHub - LasBe-code/error-boundary: 간단한 Express API를 이용한 React ErrorBoundary 테스트입니다.