[React] react-query 에러 핸들링

이 글은 react-query 의 에러 핸들링에 대해 알아본다.
API 요청에서 4xx, 5xx 와 같은 상태코드를 받는 경우라고 이해하면 된다.
react-query - https://github.com/tanstack/query

 

이번 주제는 코드를 통해 진행하게된다.

해당 코드는 특정 라이브러리들을 기준으로 진행된다.

사용하는 라이브러리의 기본 지식은 필요하지만, 모르더라도 에러 핸들링의 전체적인 흐름만 이해해도 좋을 것이라고 생각하고 있다.

 

• react-query
• axios
• react-error-boundary

---

 

우리는 API 에러 응답에 대해서 핸들링 해야한다.

기본적으로 HTTP status code 를 4xx, 5xx 응답한다면, 에러라고 받아들이고 있다.

 

API 가 에러 응답을 한다면, 클라이언트는 무엇을 해야하는가?

에러의 경우에는 이미 예상된 에러와 예상치 못한 에러로 구분될 수 있다.

 

• 예상된 에러
• 예상치 못한 에러

 

우리는 이 2가지를 모두 대응해야한다.

모든 에러는 사용자 입장에서는 에러 상황을 어떻게 안내할지 대응해야한다.

 

https://www.kodingmadesimple.com/2015/09/codeigniter-modal-contact-form-jquery-ajax-validation-example.html

https://www.mkubdev.xyz/blog/nextjs/create-custom-error-page

https://www.tutorialrepublic.com/snippets/preview.php?topic=bootstrap&file=elegant-error-modal

 

 

얼럿을 노출하거나 문구를 안내, 별도 안내 페이지 등 다양한 방식으로 처리될 수 있다.

예상치 못한 에러의 경우에는 이것을 시스템에서 탐지하여 내부 알림을 받아 인지할 수 있도록 해야한다.

 

이 글에서 말하고자하는 "에러 핸들링" 이라는 것은 위와 같은 상황들을 대응하는 로직을 말한다.

react-query 에서 에러 핸들링 하는 법을 한번 알아보자.

 

react-query 는 상태 관리를 도와주는 라이브러리일뿐, HTTP 통신에 대해 직접적인 관여는 하지 않는다.

즉, HTTP 통신은 axios, ajax, fetch 와 같은 모듈에서 에러에 대한 상황을 받아들이고 있다.

react-query 로직 이전에 위와 같은 모듈에서 에러를 핸들링하는 것이 먼저이다.

 

API 에러 응답 구조는 다음과 같은 구조로 내려온다고 가정한다.

 

{
  code: "INVALID_PARAMETER",
  message: "잘못된 파라미터입니다."
}

 

 

code 의 경우에는 에러 구분을 위한 값을 의미한다.

그렇기에, code 의 값은 다양하게 존재할 것이고, 이러한 값들은 모두 클라이언트에서 관리되고있을 것이다.

code 값이 협의된 것이 위에서 언급한 "예상된 에러" 이고, 그 외는 "예상치 못한 에러" 라고 볼 수 있다.

 

우선 협의된 code 를 관리하고 해당 에러를 위한 에러 객체를 위한, "예상된 에러" 를 대응하기 위한 코드를 작성한다.

 

// ServerError.ts
export const ServerErrorCodeConst = [
  'INVALID_PARAMETER',
  'UNKNOWN',
] as const;

export type ServerErrorCode = (typeof ServerErrorCodeConst)[number];

export default class ServerError extends Error {
  code: ServerErrorCode;

  constructor(code: ServerErrorCode, message?: string) {
    super(message);
    this.code = code;
  }
}

 

 

그리고 에러 발생시 협의되지 않은 code, "예상치 못한 에러" 를 대응하기 위한 코드를 작성한다.

 

// errorService.ts
export interface ErrorResponse {
  code: ServerErrorCode;
  message: string;
}

class ErrorService {
  static generateServerError(axiosError: AxiosError<ErrorResponse>) {
    const error = axiosError?.response?.data;

    if (!error) {
      return new ServerError('UNKNOWN');
    }

    let code = ServerErrorCodeConst.includes(error.code)
      ? error.code
      : 'UNKNOWN';

    return new ServerError(code, error.message);
  }
}

 

axios 에서 발생한 에러 객체의 code 값이 code 관리 리스트(ServerErrorCodeConst)에 없다면, 이를 인지하기 위한 별도 "UNKNOWN" 코드로 지정해주고 있다.

 

위 코드들은 실질적으로 HTTP 통신에서 에러가 발생하는 지점에서 활용된다.

 

// apiService.ts
const apiService = axios.create();

apiService.interceptors.response.use(
  (response) => {
    return response;
  },
  (error) => {
    const exception = ErrorService.generateServerError(error);

    return Promise.reject(exception);
  }
);

 

axios 에러 콜백 함수에서 받아온 error 를 generateServerError 함수를 통해 한번 가공되어 반환된다.

서버의 응답 그대로 사용하지 않고, 가공 로직에 의해 에러 객체는 모두 핸들링 범위 안에 들어오게 된다.

Promise.reject(exception) 에 의해 이제 react-query 범위로 넘어가서 핸들링하게 된다.

 

react-query 의 에러 핸들링을 확인해보자.

에러 발생시 2가지 콜백 함수에서 에러 처리를 할 수 있다.

 

• onError
• throwOnError

2가지 모두 쿼리 요청에 대해 에러 발생시 호출된다. (suspense 값에 따라 결과는 상이할 수 있다. 해당 내용은 여기서 다루지 않는다.)

onError 는 기본적인 에러 콜백 함수라고 인지하면 된다.

throwOnError 는 ErrorBoundary 로 에러를 throw 할지말지를 결정할 수 있다.

 

const App = () => {
  const queryClient = new QueryClient()
  return (
    <QueryClientProvider client={queryClient}>
      <ErrorBoundary fallbackComponent={ErrorComponent}>
        <Page />
      </ErrorBoundary>
    </QueryClientProvider>
  )
}

 

2가지를 쉽게 UI/UX 적으로는 바라보면 다음과 같다.

onError 의 경우에는 현재 화면을 유지한채 에러 안내 문구나 얼럿 같은 기능을 활용할 수 있다.
throwOnError 는 ErrorBoundary 로 랜더링되기에, 화면이 극단적으로 변경되는 것이다.

 

예를 들어, GET 요청이 아닌 경우에서 발생되는 에러는 대부분 예상된 에러이다.

 

• 회원가입에서 아이디가 중복된 경우 (code = ALREADY_REGISTERED)
• 허용되지 않은 특수 문자를 보내는 경우 (code = SEARCH_INVALID)
• 금지된 검색어를 입력한 경우 (code = SEARCH_PROHIBITED)

이러한 경우들에서는 화면의 변경되는 것은 없고 사용자에게 안내를 위해 얼럿창을 보여주게 된다.

 

반대로, 의도적으로 더 명확한 내용을 전달하기 위해서 화면 변경이 필요한 경우도 존재한다.

• 서버의 시스템 에러가 발생하여 정상적인 동작을 보장할 수 없는 경우 (code = INTERNAL_ERROR)
• 사용자가 해당 기능을 사용할 수 없는 경우 (code = USER_SUSPENDED)

 

이를 기반으로 react-query 의 에러에 대한 옵션을 설정해본다.

 

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      throwOnError: (error) => {
        if (error.code === 'NETWORK_ERROR') { return true; }
        return false
      },
    },
    mutations: {
      throwOnError: (error) => {
        if (['INTERNAL_ERROR', 'USER_SUSPENDED'].include(error.code)) { return true; }
        return false;
      },
      onError: (error) => {
        if (["ALREADY_REGISTERED","SEARCH_PROHIBITED","SEARCH_INVALID"].include(error.code)) { 
          alert(error.message); 
        }
        logger.error(error)
        // ...
      },
    },
  },
  queryCache: new QueryCache({
    onError: (error) => {
      logger.error(error)
      // ...
    },
  }),
});

 

위 설정에 대해 요약하면 다음과 같다.

 

queries: { throwOnError: ... }
=> useQuery 에 의해 발생한 에러는 code 값이 NETWORK_ERROR 인 경우에만 ErrorBoundary 로 넘긴다.

mutations: { throwOnError: ... }
=> useMutation 에 의해 발생한 에러는 code 값이 INTERNAL_ERROR, USER_SUSPENDED 인 경우에는 ErrorBoundary 로 넘긴다.

mutations: { OnError: ... }
=> useMutation 에 의해 발생한 에러는 code 값이 ALREADY_REGISTERED, SEARCH_PROHIBITED, SEARCH_INVALID 인 경우에는 alert 창을 띄우고, 반대인 경우에는 에러 로그를 보낸다.

queryCahce: { onError: ... }
=> useQuery 에 의해 발생한 에러 콜백 함수

 

일부 코드중 logger.error 의 의도는 알림 및 로그를 남길 필요가 있는 에러의 경우를 위함이다.

 

onError 는 특정 code 들을 얼럿을 통해 핸들링하고 있고, 추가적으로 필요한 code 들을 추가할 수 있다.

throwOnError 는 특정 code 들을  ErrorBoundary 로 던져 에러 핸들링을 위임한다.

결과적으로 넘어간 에러는 ErroryBoundary 에 의해 각각의 code 를 위한 컴포넌트로 노출하게 된다.

 

type ErrorComponentProps = {
  error: unknown;
};
const ErrorComponent = ({ error }: ErrorComponentProps) => {
  const renderComponent = useCallback(() => {
    switch (error.code) {
      case 'SEARCH_SUSPENDED':
        return <SuspendedError />;
      case 'INTERNAL_ERROR':
        return <InternalError />;
      default:
        return <UnknownError />;
    }
  }, [error]);

  return (
    <>
      <h2>Error Component</h2>
      {renderComponent()}
    </>
  );
};

 

위 설정들은 react-query 요청의 에러에 대해 기본 옵션으로 설정하였다.

즉, react-query 에 의한 모든 요청은 기본 옵션을 따르게 된다.

반대로 기본 옵션을 따르지 않아야하는 경우가 생겨난다면, 기본 옵션을 따르지 않도록 하면 된다.

 

const ComponentA = () => {
  const { mutate } = useMutation({
    mutationFn: () => { ... },
    onError: (error) => {
      if (error.code === 'SEARCH_CONFIRM') {
        confirm('I am confirm!');
      }
    },
  });

  return (
    <>...</>
  )
}

 

 

위처럼 각 사용처에서 기본으로 설정되어있는 onError, throwOnError 를 오버라이딩해서 사용하면 된다.

 

---

 

서비스마다 요구사항이 다르고, 처해진 개발 환경도 다를 것이다.

• 여러 API 엔드포인트를 사용하고, 엔드포인트마다 에러 응답 구조가 다를 수 있는 경우
• 비동기 요청은 react-query 뿐만 아니라, axios 로 직접 요청, 소켓 통신 등이 공존하는 경우

 

위와 같은 상황들도 전체적인 흐름을 이해하면, 이것들을 기반으로 더 많은 확장성을 충분히 보장할 수 있을 것이다.

 

전체적인 흐름 설명을 위해 최소화된 코드로 진행하였다.

아래 예제 코드는 언급된 내용과 코드를 기반으로 조금 더 심화된 예제 코드이니 살펴보면 좋을 것이다.