React-query 환경에서 효율적으로 오류 처리하기

1. 오류 처리 흐름

1-1. 오류 유형 별 화면에서의 표현 방법

1. 조회 시 발생한 오류는
1. API 오류인 경우 ApiErrorBoundary로 잡아요.
2. 그 외의 오류인 경우 ErrorBoundary로 잡아요.

2. 수정 시 발생한 오류는
1. 응답 코드가 400인 경우 오류에 맞게 직접 Toast 등으로 표시해요.
2. 응답 코드가 4xx, 5xx인 경우 전역에서 Toast로 표시해요.
3. 그 외의 오류인 경우 ErrorBoundary로 잡아요.

3. 그 외의 오류는
1. ErrorBoundary로 잡아요.

1-2. 오류 유형 별 코드로 처리하는 방법

1. 조회 API 오류를 처리하는 방법
1. 2xx대 응답이 아니면 모두 throw해요.

2. 수정 API 오류를 처리하는 방법
1. Axios의 Response Interceptor에서 2xx, 400인 경우 정상 응답으로 반환해요.
2. 그 외의 경우 defaultOptions.mutations.onError에 등록된 핸들러를 호출해요.
1. AxiosError인 경우 Toast를 띄워요.
2. 그 외의 경우 처리할 수 없으므로 throw 해요.
3. 각 mutation에서 커스텀이 필요한 경우

1-3. 오류를 모니터링하는 방법

1. 다음의 콜백 함수에서 Sentry 등의 도구로 오류를 전달할 수 있어요.
1. 각 ErrorBoundary의 componentDidCatch
2. React-query의 QueryCache, MutationCache의 onError

2. 비동기 오류 처리 시 주의 사항

2-1. 오류의 종류

1. 동기 코드
1. 컴포넌트, 훅에서 실행한 동기 코드

2. 비동기 코드
1. 이벤트 핸들러
2. Promise
3. API 요청 (Axios, fetch + React-query 환경)

2-1-1. 동기 오류

2-1-2. 비동기 오류

2-2. 비동기 오류 발생 시 공통 처리 방법

2-2-1. 컴포넌트에 throw 위임하기

import { useEffect, useMemo, useState } from 'react';

/**
 * Error Boundary로 오류를 전파하기 위한 훅이에요.
 *
 * 이벤트 핸들러와 같이 별도의 Stack에서 실행될 때 사용해요.
 *
 * 이벤트 핸들러는 감싸서 사용하면 돼요.
 *
 * @example
 * const bindThrow = useBindThrow();
 * onClick: bindThrow(() => setIsOpen(true)),
 *
 * Promise의 경우 catch로 등록할 수 있어요.
 *
 */
const useErrorBoundary = () => {
  const [error, throwError] = useState<unknown>(undefined);

  useEffect(() => {
    if (!error) {
      return;
    }
    throw error;
  }, [error]);

  // FIXME: 타입 단언이 필요해요. 이 코드에선 생략되어 있어요.
  const passError = useMemo(
    () =>
      <T extends Function>(handler: T): T =>
      (...args: unknown[]) => {
        try {
          handler(...args);
        } catch (error) {
          throwError(error);
        }
      },
    [],
  );

  return { passError, throwError };
};

export default useErrorBoundary;

2-2-2. 이벤트 핸들러, setTimeout, requestAnimationFrame

import useErrorBoundary from '@/utils/useErrorBoundary';

export const HomePage = () => {
  const { passError } = useErrorBoundary();

  const handleClick = passError(() => {
    throw 'handleClickError!!';
  });

  return (
    <div className='flex flex-col'>
      <div className='grow'>
        <button onClick={handleClick}>Click me to throw</button>
      </div>
    </div>
  );
};

2-2-3. Promise 내의 throw, reject

// 컴포넌트 내부에서 Hook을 사용하기
const { throwError } = useErrorBoundary();

// Promise에 catch를 붙이기
getNotificationList().catch(throwError);

3. 오류 별 화면

3-1. 조회 오류

3-1-1. 화면의 일부만 오류 페이지로 렌더링

3-2. 수정 오류

4. 구현 방법

4-1. ErrorBoundary

4-1-1. 필요 이유

• <NotificationList />에서 오류가 발생하면 MyErrorBoundary에서 알 수 있어요.

<ErrorBoundary>
  <NotificationList />
</ErrorBoundary>

4-1-2. 동작 방식

Component – React

The library for web and native user interfaces

https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary

4-1-3. 구현

• onReset: 오류 화면에서는 리셋 역할의 버튼이 하나 존재하게 돼요. 그 버튼의 핸들러에요.

• onCatch: 오류를 전달받는 콜백 함수에요.

• fallback: 오류를 표시할 화면을 의미해요. onReset과 error를 전달받아요.

import { Component, ComponentType, PropsWithChildren } from 'react';

// Fallback 컴포넌트와 그 prop 타입이에요. 알아서 바꾸시면 돼요.
import ErrorAlertFullScreen, {
  type ErrorAlertProps,
} from '../ErrorAlertFullScreen';

export interface ErrorBoundaryProps extends PropsWithChildren {
  onReset?: () => void;
  onCatch?: (error: unknown) => void;
  fallback?: ComponentType<ErrorAlertProps>;
}

interface State {
  error: unknown;
  isError: boolean;
}

const defaultState = {
  error: undefined,
  isError: false,
};

/**
 * 자식 컴포넌트에서 오류를 잡는 경우 `fallback prop`을 대신 표시해요.
 *
 * 오류를 더 상위 ErrorBoundary에서 처리하게 만드려면 `onCatch`에서 throw를 할 수 있어요.
 */
export default class ErrorBoundary extends Component<
  ErrorBoundaryProps,
  State
> {
  constructor(props: ErrorBoundaryProps) {
    super(props);
    this.state = defaultState;

    this.resetErrorState = this.resetErrorState.bind(this);
  }

  resetErrorState() {
    this.props.onReset?.();
    this.setState(defaultState);
  }

  componentDidCatch(error: unknown) {
    this.props.onCatch?.(error);
    this.setState({ error, isError: true });
  }

  render() {
    const { error, isError } = this.state;
    const { children, fallback: Fallback = ErrorAlertFullScreen } = this.props;

    if (!isError) {
      return children;
    }

    return <Fallback error={error} onReset={this.resetErrorState} />;
  }
}

4-2. QueryErrorResetBoundary

4-2-1. 필요 이유

4-2-2. 개념 설명

queryClient.resetQueries({ queryKey })

QueryClient | TanStack Query Docs

QueryClient The QueryClient can be used to interact with a cache:

https://tanstack.com/query/latest/docs/reference/QueryClient#queryclientresetqueries

4-3-3. 구현

• QueryErrorResetBoundary는 ErrorBoundary와 같은 componentDidCatch 기능이 없기 때문이에요.

• ErrorBoundary에 onReset을 넘겨 쿼리를 리셋해요.

import { QueryErrorResetBoundary } from '@tanstack/react-query';

import ErrorBoundary, { ErrorBoundaryProps } from './ErrorBoundary';

/**
 * 하위 컴포넌트의 error 상태의 query의 상태를 reset 해요.
 */
const ApiErrorBoundary = ({
  onCatch,
  onReset,
  fallback: Fallback,
  children,
}: ErrorBoundaryProps) => { // ErrorBoundary의 prop을 그대로 이용해요.
  return (
    <QueryErrorResetBoundary>
      {({ reset: resetErrorStateQueries }) => {
        const handleReset = () => {
          resetErrorStateQueries();
          onReset?.();
        };

        return (
          <ErrorBoundary
            fallback={Fallback}
            onReset={handleReset}
            onCatch={onCatch}
          >
            {children}
          </ErrorBoundary>
        );
      }}
    </QueryErrorResetBoundary>
  );
};

export default ApiErrorBoundary;

4-3. queryClient.defaultOptions.mutations.onError

4-3-1. 필요 이유

4-3-2. 구현

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { /* ... */ },
    mutations: {
      onError: (error: unknown) => {
			  if (!isAxiosError(error)) {
			    throw error;
			  }
			
			  return showErrorToast(
			    '요청을 처리할 수 없었습니다.\r\n잠시 후 다시 시도해주세요.',
			  );
			},
    },
  },
  // ...
}

4-4. QueryCache, MutationCache의 onError

4-4-1. 필요 이유

4-4-1. 구현

// Sentry와 같은 로그 수집 및 모니터링 도구 사용 시
const sendToSentry = (error: unknown) => { /* ... */ };

const queryClient = new QueryClient({
  // ...
  queryCache: new QueryCache({
    onError: (error, queryConfig) => {
      console.log(error, queryConfig);
			sendToSentry(error);
    },
  }),
  mutationCache: new MutationCache({
    onError: (error, queryConfig) => {
      console.log(error, queryConfig);
			sendToSentry(error);
    },
  }),
});