Tanstack/query 캐싱 - gcTime과 staleTime

 

https://tanstack.com/query/latest/docs/framework/react/guides/caching

TanStack | High Quality Open-Source Software for Web Developers

 

Tanstack의 Query는 서버 사이드의 데이터를 캐싱하고 자동으로 갱신하며 불필요한 요청을 줄이는 기능을 제공합니다.

캐싱 설정에서 gcTime과 staleTime에 대해 찾아보고 정리해봅니다.

*gcTime은 Tanstack query v5에서 하위버전의 cacheTime이 변경된 이름이라 하네요.

 

Tanstack Query에서의 캐싱 개념

Tanstack Query는 쿼리 캐시를 이용하여 데이터의 유효성과 네트워크 요청을 제어하며, 이를 기반으로 앱의 성능과 UX를 개선합니다. 대표적인 옵션으로 staleTime, gcTime이 있으며 이는 데이터가 언제까지 유효한지, 언제 메모리에서 제거되는지 시점을 설정합니다.

 

staleTime

데이터의 유효성 기간을 설정합니다.

데이터가 "Fresh"하게 유지되는 기간을 설정하는 옵션입니다. 이 값의 설정에 따라 Tanstack Query는 staleTime이 경과할 때까지 데이터가 최신 상태로 유지된다고 판단하여 추가 요청을 보내지 않게 됩니다.

기본값: 0 (밀리초, 항상 최신 정보 요구)

 

gcTime

캐시된 데이터가 메모리에서 완전히 제거되기 전까지의 시간을 설정합니다. gcTime이 경과한 데이터는 메모리에서 자동으로 제거합니다. 

기본값: 5 * 60 * 1000 (밀리초, 5분)

 

staleTime과 gcTime의 관계

staleTime이 경과한 데이터는 stale 상태로 간주되지만, gcTime이 지나기 전까지는 메모리에 남아있을 수 있습니다.

staleTime이 gcTime보다 길다면, 데이터는 오래 "신선"한 상태로 유지될 수 있으나, 메모리에서 일찍 사라질 수도 있으니 사용 목적에 맞게 두 값을 조정해야 합니다.

 

예시) 

1. QueryClient 설정시 defaultOptions에 설정하는 방법

 

const queryClient = new QueryClient({

  defaultOptions: {

    queries: {

      gcTime: 1000 * 60 * 5,

      staleTime: 1000 * 60 * 1,

    }

  }

})

 

 

2. 특정 쿼리에서 설정하는 방법

 

const userProfileQuery = useQuery(

  ["userProfile", userId],

  fetchUserProfile,

  {

    staleTime: 1000 * 60 * 10, // 10분 동안 신선한 상태로 유지

    cacheTime: 1000 * 60 * 30 // 30분 동안 캐시에 저장

  }

);

 

 

3. staleTime을 함수 형태로 설정하는 방법 (defaultOptions에서)

 

const queryClient = new QueryClient({

  defaultOptions: {

    queries: {

      staleTime: (query) => {

        if (query.queryKey[0] === "userProfile") {

          return 1000 * 60 * 10; // userProfile 쿼리에는 10분의 staleTime 적용

        } else if (query.queryKey[0] === "posts") {

          return 1000 * 60 * 5; // posts 쿼리에는 5분의 staleTime 적용

        }

        return 0; // 그 외의 쿼리는 기본적으로 staleTime이 0으로 설정됨

      },

      gcTime: 1000 * 60 * 5 // 기본 gcTime 5분

    }

  }

});

 

함수형태의 설정 역시 개별 쿼리에서도 설정이 가능하다.