TanStack-Query

오늘은 헬지 과제인 TanStack-Query 라이브러리에 대해 알아보도록 하겠습니다.

 

TanStack-Query란?

TanStack-Query는 서버로부터 데이터 가져오기, 데이터 캐싱, 캐시 제어 등 데이터를 쉽고

효율적으로 관리할 수 있는 라이브러리입니다.

 

공식 문서: https://tanstack.com/query/latest/docs/framework/react/overview

Overview | TanStack Query React Docs

 

 

 

TanStack-Query의 기능

 

1. 서버 데이터 캐싱 기능

TanStack-Query는 서버에서 가져온 데이터를 내부 캐시에 저장합니다.

같은 queryKey를 사용하는 쿼리가 다시 실행될 경우, 서버에 다시 요청하지 않고 캐시에 저장된 데이터를 재사용하는데
이를 통해 불필요한 API 요청을 줄이고, 페이지 전환 시에도 데이터를 유지할 수 있습니다.

 

2. 로딩 및 에러 상태 자동 관리

TanStack Query는 서버 요청과 관련된 상태를 자동으로 관리합니다.

• isLoading: 데이터 요청 중 여부
• isError: 요청 실패 여부
• isSuccess: 요청 성공 여부
• data: 서버에서 받은 데이터
• error: 발생한 에러 정보

 

3. Refetching

TanStack Query는 특정 조건에서 서버 데이터를 자동으로 다시 요청할 수 있습니다

예시 상황으로는

• 컴포넌트가 다시 마운트될 때
• 브라우저 창이 다시 포커스를 얻을 때
• 네트워크가 재연결될 때
• 데이터가 stale 상태가 되었을 때

이를 통해 클라이언트와 서버 데이터의 동기화를 유지할 수 있다고 합니다.

 

4. staleTime

staleTime은 데이터가 어느정도 오래됐는지를 판단하는 시간을 뜻합니다

해당 시간 동안 데이터는 신선한 상태로 간주되며, 재요청이 발생하지 않게되는데
이를 설정하면 불필요한 API 호출을 줄이고 성능을 개선할 수 있습니다.

 

추가적으로 TanStack Query는 기본값으로 staleTime이 0이기 때문에 데이터를 받아오자마자 stale 상태가 됩니다.

이 의미는 staleTime을 설정하지 않으면 컴포넌트가 mount 될 때마다 기본적으로 재요청이 발생할 수 있습니다

 

5. gcTime

gcTime은 더 이상 사용되지 않는 캐시 데이터를 언제 메모리에서 제거할지를 결정하는건데

해당 쿼리를 사용하는 컴포넌트가 모두 언마운트된후에 gcTime이 지나면 캐시가 완전히 삭제됩니다.

 

6. Mutation

서버 데이터를 변경하기 위해 useMutation을 쓰는데

게시글 작성, 수정, 삭제와 같이 서버 상태를 변경하는 작업에 사용되며, 성공 또는 실패에 따른 콜백을 따로 설정할 수 있습니다.

또한 데이터 변경 이후 관련 쿼리를 무효해서 최신 데이터를 다시 가져오도록 할 수도 있습니다!

 

7. 쿼리 무효화

invalidateQueries는 특정 쿼리를 무효화하여 다시 서버에서 데이터를 가져오도록하는 기능입니다.

서버 데이터가 변경될때 기존 캐시 데이터를 그대로 사용하는 문제를 예방하고 최신 상태를 유지할 수 있습니다

 

8. 조건부 쿼리 및 병렬 쿼리 실행

TanStack Query는 조건에 따라 쿼리를 실행하거나 여러 쿼리를 동시에 실행할 수 있습니다.

• enabled 옵션을 사용하면 특정 조건이 만족될 때만 쿼리를 실행할 수 있고
• useQueries를 사용하면 여러 API 요청을 병렬로 처리할 수 있습니다.

이런식으로 복잡한 데이터를 효율적으로 관리할 수 있습니다.

 

9. 페이지 이동 시 데이터 유지

TanStack Query의 캐시는 전역으로 관리되어서 페이지 이동이 발생해도 데이터가 유지되는데

같은 데이터를 다시 사용하는 페이지로 돌아왔을 때 바로 화면에 데이터를 표시할 수 있습니다.

 

 

TanStack Query를 사용하면 좋은 경우

• 서버 API에서 데이터를 가져오는 구조
• 같은 데이터를 여러 컴포넌트에서 사용할 경우
• 페이지 이동이 많은 SPA 구조
• 로딩 및 에러 재요청 로직이 반복

 

위와 같은 상황에서 TanStack Query를 사용하면

• API 중복 요청 감소
• 페이지 이동 시 데이터 유지
• 서버 상태 관리 코드 간소화
• 사용자 경험 개선

 

Hello, GSM에서 TanStack Query를 사용한 이유

Hello, GSM은 광주소프트웨어마이스터고 입학 지원자들이 직접 원서를 작성하고 제출하는 서비스이기 때문에

• 지원 전형 정보, 작성 중인 원서 데이터 등 서버와 지속적으로 데이터가 동기화되고
• 원서 작성 과정에서 페이지 이동이 있고
• 중간 저장, 최종 제출 등 서버 데이터 변경이 많기 때문에

이러한 프로젝트는 서버 상태를 잘 관리하는 것이 매우 중요하다고 생각합니다.

 

그래서 원서 작성 중 서버와의 동기화를 안정적으로 유지하고 임시 저장과 제출 후 상태를 빨리 반영하기 위해 TanStack Query를 사용한 것 같습니다.

 

 

Hello, GSM에서 실제로 적용된 방식

다음 코드는 원서 제출을 하고 출력하는 페이지 코드를 가져왔습니다

'use client';

import { GetMyOneseoType } from 'types';

import { ApplicationForm, PrintButton, ScoreConfirmationForm } from 'client/components';

import { useGetMyOneseo } from 'api/hooks';

interface PrintPageProps {
  initialData: GetMyOneseoType | undefined;
}

const ApplicationPage = ({ initialData }: PrintPageProps) => {
  const { data: oneseo } = useGetMyOneseo({ initialData: initialData });

  if (!oneseo) return <>원서 정보가 없습니다</>;

  return (
    <>
      <style jsx global>{`
        @media print {
          body {
            header,
            #sample,
            footer {
              display: none !important;
            }
          }
          @page {
            margin: 0;
          }
        }
      `}</style>

      <PrintButton />
      <ApplicationForm oneseo={oneseo} />
      {oneseo.privacyDetail.graduationType !== 'GED' && <ScoreConfirmationForm oneseo={oneseo} />}
    </>
  );
};

export default ApplicationPage;

 

const { data: oneseo } = useGetMyOneseo({ initialData: initialData });

 

이 부분에서 TanStack Query가 사용되는것 같은데
useGetMyOneseo는 TanStack Query의 useQuery를 내부에서 사용한 커스텀 훅이며, 서버에 저장된 내 원서의 데이터를 가져오는 역할을 합니다.

 

 

마무리

오늘은 TanStack-Query 라이브러리에 대해 알아보았는데 서버와의 데이터 통신이 많고 중요한 프로젝트에서 쓰면 좋을것 같다고 생각했습니다.

 

 

참고 자료:https://www.heropy.dev/p/HZaKIE

TanStack Query(React Query) 핵심 정리