왜 TanStack Query를 사용할까?

TanStack Query는 웹 애플리케이션에서 꼭 필요했던 data-fetching 라이브러리의 완성판이라고 불린다. 기술적으로 말하면, 웹 애플리케이션의 서버 상태를 가져오고, 캐싱하며, 동기화하고, 업데이트하는 작업을 아주 쉽게 만들어 준다.

 

왜 필요할까?

대부분의 핵심 웹 프레임워크는 데이터를 가져오거나 업데이트하는 것에 대해 통합적이고 정형화된 방법을 제공하지 않는다. 이 때문에 개발자들은 데이터 페칭에 대한 엄격한 규칙을 포함하는 메타 프레임워크를 만들거나, 자신만의 데이터 페칭 방식을 만들어낸다. 이는 보통 컴포넌트 기반 상태 관리와 사이드 이펙트를 엮거나, Redux나 Zustand 같은 전역 상태 관리 라이브러리를 사용하여 비동기 데이터를 앱 전체에서 관리하는 방식으로 귀결된다.

 

전통적인 상태 관리 라이브러리들은 client state를 다루는 데는 훌륭하지만, async or server state를 다루는 데는 그다지 좋지 않다. 왜냐하면 서버 상태는 다음과 같은 특징을 가진, 완전히 다른 종류의 상태이기 때문이다.

• 서버에 저장되며 우리가 직접 제어할 수 없는 곳에 위치한다.
• 데이터를 가져오고 업데이트하기 위해 비동기 API가 필요하다.
• 여러 사람과 공유되는 데이터이므로, 내가 모르는 사이에 다른 사람에 의해 변경될 수 있다.
• 제대로 관리하지 않으면 애플리케이션에서 오래된 데이터가 될 수 있다.

애플리케이션의 서버 상태가 가진 본질을 파악하고 나면, 다음과 같은 더 많은 문제들이 발생하게 된다.

• 캐싱
• 동일한 데이터에 대한 여러 요청을 하나로 합치기
• 오래된 데이터를 백그라운드에서 업데이트하기
• 데이터가 언제 오래된 상태가 되는지 파악하기
• 데이터 변경 사항을 가능한 한 빠르게 화면에 반영하기
• 페이지네이션, 무한 스크롤과 같은 성능 최적화
• 서버 상태에 대한 메모리 관리 및 가비지 컬렉션(GC)
• 구조적 공유(structural sharing)를 통한 쿼리 결과 메모이제이션

TanStack Query는 서버 상태 관리를 위한 최고의 라이브러리 중 하나이다. 별도의 설정 없이 바로 사용해도 잘 동작하며, 애플리케이션이 성장함에 따라 원하는 대로 커스터마이징할 수 있다. TanStack Query를 사용하면 까다로운 서버 상태 문제들을 정복하고, 앱 데이터가 당신을 통제하기 전에 당신이 데이터를 통제할 수 있게 된다.

 

좀 더 기술적인 관점에서 보면, 다음과 같은 도움을 줄 것이다.

• 애플리케이션에서 복잡하고 이해하기 어려웠던 코드를 상당수 제거하고, 단 몇 줄의 TanStack Query 로직으로 대체할 수 있다.
• 새로운 서버 데이터를 연결하는 걱정 없이 새로운 기능을 더 쉽게 만들 수 있어, 애플리케이션의 유지보수성을 높여준다.
• 애플리케이션이 이전보다 더 빠르고 반응성 좋게 느껴지도록 하여 최종 사용자 경험에 직접적인 영향을 준다.
• 네트워크 대역폭을 절약하고 메모리 성능을 향상시키는 데 도움을 줄 수 있다.

아래 예제는 TanStack Query를 가장 기본적이고 단순한 형태로 사용하여 TanStack Query Github 프로젝트의 통계 정보를 가져오는 코드이다.

import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Example />
    </QueryClientProvider>
  )
}

function Example() {
  const { isPending, error, data } = useQuery({
    queryKey: ['repoData'],
    queryFn: () =>
      fetch('https://api.github.com/repos/TanStack/query').then((res) =>
        res.json(),
      ),
  })

  if (isPending) return 'Loading...'

  if (error) return 'An error has occurred: ' + error.message

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.description}</p>
      <strong>👀 {data.subscribers_count}</strong>{' '}
      <strong>✨ {data.stargazers_count}</strong>{' '}
      <strong>🍴 {data.forks_count}</strong>
    </div>
  )
}

 

TanStack Query는 처음 사용할 때부터 공격적이면서도 합리적인 기본값으로 설정되어 있다. 때로는 이 기본 설정들이 새로운 사용자들을 당황하게 하거나, 내용을 잘 모를 경우 학습 및 디버깅을 어렵게 만들 수 있다.

 

TanStack Query를 배우고 사용하면서 다음 사항들을 꼭 기억하자.

 

useQuery나 useInfiniteQuery를 통해 생성된 쿼리 인스턴스는 기본적으로 캐시된 데이터를 stale(오래된) 데이터로 간주한다. stale 상태의 데이터는 특정 조건에서 즉시 다시 가져오게 된다.

 

이러한 기본 동작을 변경하려면 전역 또는 개별 쿼리에서 staleTime 옵션을 설정하면 된다. staleTime을 길게 설정할수록 쿼리가 데이터를 다시 가져오는 빈도가 줄어든다.

 

staleTime이 설정된 쿼리는 지정된 시간이 지나기 전까지 fresh(신선한) 상태로 간주된다. fresh 상태의 데이터는 다시 가져오지 않고 캐시된 데이터를 즉시 반환한다.

 

• staleTime을 2 * 60 * 1000 (2분)으로 설정하면, 2분 동안은 수동으로 무효화(invalidate)하지 않는 이상 캐시에서 데이터를 읽어오고, refetch가 발생하지 않는다.
• staleTime을 Infinity로 설정하면, 수동으로 무효화하기 전까지는 절대 자동으로 refetch되지 않는다.
• staleTime을 'static'으로 설정하면, 수동으로 무효화해도 절대 refetch되지 않는다.

stale 상태인 쿼리는 다음과 같은 상황에서 자동으로 백그라운드에서 refetch 된다.

• 쿼리의 새로운 인스턴스가 마운트될 때 - refetchOnMount
• 브라우저 창이 다시 포커스될 때 - refetchOnWindowFocus
• 네트워크 연결이 끊겼다가 다시 연결될 때 - refetchOnReconnect

과도한 refetch를 방지하기 위해 staleTime을 조절하는 것이 가장 권장되는 방법이지만 위와 같은 옵션들을 false로 설정하여 refetch 시점을 직접 제어할 수도 있다. refetchInterval 옵션을 사용하면 staleTime과 별개로 주기적으로 데이터를 refetch하도록 설정할 수도 있다.

 

useQuery, useInfiniteQuery 등 활성화된 인스턴스가 하나도 없는 쿼리 결과는 inactive 상태가 된다. 이 데이터는 나중에 다시 사용될 경우를 대비해 캐시에 남아있다.

기본적으로 inactive 상태의 쿼리는 5분 후에 GC(Garbage Collection)에 의해 캐시에서 삭제된다.

이 시간을 변경하려면 gcTime 옵션의 기본값인 1000 * 60 * 5 (5분) 밀리초를 다른 값으로 변경하면 된다.

 

쿼리 요청이 실패하면, UI에 에러를 표시하기 전에 기본적으로 3번까지 자동으로 재시도한다. 이때 재시도 간의 딜레이는 exponential backoff 방식으로 점차 늘어난다. retry 옵션으로 재시도 횟수, retryDelay 옵션으로 딜레이 방식을 변경할 수 있다.

 

기본적으로 쿼리 결과 데이터는 구조적 공유를 통해 실제로 데이터가 변경되었는지 감지한다. 만약 변경되지 않았다면, 데이터의 참조는 이전과 동일하게 유지된다. 이렇게 하면 useMemo나 useCallback과 함께 사용할 때 값의 안정성을 높여주며, 불필요한 렌더링을 방지해 성능을 자동으로 최적화해준다.

구조적 공유는 JSON으로 직렬화 가능한 값에서만 동작하며 다른 데이터 타입은 항상 변경된 것으로 간주한다. 만약 응답 데이터가 매우 커서 성능 문제가 발생한다면, config.structuralSharing을 false로 설정하여 비활성화할 수 있다. JSON 호환되지 않는 값을 다루면서도 데이터가 변했는지 감지하고 싶다면, config.structuralSharing에 사용자 정의 함수를 전달해 이전 값과 새 값을 비교하는 방식을 직접 구현할 수 있다.

 

https://tanstack.com/query/latest/docs/framework/react/overview#motivation

Overview | TanStack Query React Docs

 

https://tanstack.com/query/latest/docs/framework/react/guides/important-defaults

Important Defaults | TanStack Query React Docs