tanstack-query의 stale time과 gc time

참고한 블로그...

https://velog.io/@jasmine0714/React-Query-staleTime-vs-gcTime

[React-Query] staleTime vs gcTime (구 cacheTime)

 

https://until.blog/@morethanmin/react-query의-staletime과-gctime-mkkwywz2

react-query의 staleTime과 gcTime

 

https://velog.io/@o1011/2-staleTime-과-gcTime

[2일차] 매일 공부 - staleTime 과 gcTime

 

https://ifelseif.tistory.com/148

[240614 TIL] TanstackQuery - Life Cycle

 

https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType#staletime-property

RouteOptions type | TanStack Router React Docs

 

https://jjang-j.tistory.com/65

React Query(Tanstack Query) 의 staleTime 사용 방법

 

https://www.timegambit.com/blog/digging/react-query/03

[React Query] stale & cache 동작원리

 

---

 

 

react-query에서 useQuery를 사용하면 staleTime과 gcTime을 이용해 데이터를 효율적으로 다룰 수 있습니다.

상태	설명
fresh	데이터를 새로 패칭할 필요가 없는 상태입니다. staleTime이 지나지 않은 상태로, 캐시 데이터를 그대로 사용할 수 있습니다.
stale	데이터를 새로 패칭해야 하는 상태입니다. staleTime이 지난 후로, 새로운 데이터를 가져오기 위해 쿼리가 실행됩니다.
active	현재 컴포넌트에서 사용 중인 쿼리 상태입니다. 컴포넌트가 마운트되어 쿼리를 사용하고 있을 때를 말합니다.
inactive	더 이상 사용되지 않는 쿼리 상태입니다. 컴포넌트가 언마운트되거나 쿼리가 더 이상 필요하지 않을 때를 말합니다.
deleted	캐시에서 제거된 쿼리 상태입니다. gcTime 이 지나면 쿼리가 캐시에서 삭제되어 이 상태가 됩니다.
fetching	데이터를 서버에서 가져오고 있는 상태입니다. 이 상태에서는 isFetching이 true로 설정됩니다.

 

stale time

캐시된 데이터가 ‘신선한 상태(fresh)’라 간주되는 시간 → 최신 데이터

defaultValue는 0으로, 리액트 쿼리에서는 기본적으로 불러온 데이터를 fresh하지 않다고 간주합니다.

 

설정된 시간 동안은 캐시 데이터를 별도의 네트워크 요청 없이 그대로 보여줍니다.

staleTime이 지나면 다시 fetch해오고, staleTime이 지나지 않았으면 쿼리된 데이터를 보여줍니다.

 

gc time (구 cache time)

캐시 데이터가 ‘메모리에 유지되는 시간’

defaultValue는 클라이언트 사이드에서는 5분, 서버사이드에서는 Infinity로 지정 됩니다.

 

캐시가 오래된 데이터로 간주되더라도(stale 상태) 메모리에서 삭제되지 않고 일정 시간 동안 보관됩니다.

설정된 시간이 지나면 캐시가 GC(Garbage Collection)에 의해 삭제됩니다.

 

 

- staleTime이 지나고 gcTime 이내라면

staleTime이내에서는 별도의 네트워크 요청 없이 캐싱된 데이터를 보여줍니다.

 

하지만 staleTime이 지났지만 gcTime 이내라면 백그라운드에서 네트워크 요청을 하되, 유저에게는 기존에 캐싱된 데이터를 우선 보여줍니다.

 

요약

• 기존 데이터를 보여줌
• 화면에는 캐시에 저장된 데이터를 즉시 렌더링.
• 백그라운드에서 새 데이터를 요청
• 새로운 데이터가 받아지면 화면을 업데이트.

구체적인 동작

1. 캐시 데이터 사용
   • staleTime이 지나도 캐시 데이터는 여전히 gcTime 동안 유지됩니다.
   • 이 상태에서 요청이 들어오면, 화면에는 기존 캐시 데이터를 즉시 렌더링.
2. 백그라운드 요청
   • 네트워크를 통해 최신 데이터를 요청합니다.
   • 요청한 데이터가 도착하면, 캐시를 갱신하고 화면에 업데이트합니다.

사용자가 보는 데이터는?

• 네트워크 요청이 완료되기 전: 기존 캐싱된 데이터.
• 네트워크 요청이 완료된 후: 새롭게 받아온 최신 데이터.

 

- 쿼리 인스턴스가 inactive 될 때 (언마운트될 경우, 더 이상 구독하는 컴포넌트가 없음)

staleTime와는 별개로, inactive 상태가 되면 React Query는 캐시 데이터를 삭제하기 위한 GC 스케줄링을 시작합니다.

 

GC 스케줄링은 gcTime으로 제어됩니다.

• gcTime동안 데이터가 메모리에 유지됩니다.
• gcTime이 지나면 캐시 데이터가 삭제됩니다.

동작 과정

1. 컴포넌트에서 useQuery로 데이터를 구독 중 → active 상태
2. 컴포넌트 언마운트 → 해당 쿼리 인스턴스가 더 이상 사용되지 않아 inactive 상태
3. inactive 상태가 되면gcTime 이 지나면 캐시 데이터를 삭제(GC)합니다.
4. React Query는 gcTime타이머를 시작합니다.

💡

gcTime은 쿼리가 다시 active 상태가 되면 멈춥니다.

다시 마운트될 경우: active 상태로 전환

• 같은 queryKey로 다시 쿼리를 구독하면 해당 쿼리는 active 상태가 됩니다.
• gcTime 타이머는 멈춥니다.
  • 캐시 데이터가 여전히 유효(staleTime 내)하면, 네트워크 요청 없이 캐시 데이터를 즉시 반환합니다.
  • 만약 데이터가 오래됨(staleTime 초과)이면, 네트워크 요청을 트리거하여 최신 데이터를 가져옵니다.

 

쿼리 인스턴스(Query Instance)

쿼리의 상태와 동작을 관리하는 객체

 

React Query의 훅(useQuery)을 호출할 때 생성됩니다.

특정 키(Query Key)로 식별되며, 해당 키와 관련된 데이터를 React Query가 추적합니다.

 

쿼리 인스턴스 내에 포함되는 정보들

• status: 데이터의 상태 (idle, loading, error, success 등)
• isFetching: 데이터가 현재 요청 중인지 여부
• data: 쿼리의 실제 데이터
• error: 데이터 요청 중 발생한 에러
• 기타 상태 정보 (isStale, isLoading, 등)

 

개념 정리

 

- staleTime

데이터를 처음 가져온 후 얼마 동안 네트워크 요청 없이 캐시된 데이터를 사용할지를 정하는 시간

 

- gcTime

그 데이터가 오래된 상태가 된 후에도 캐시에 유지될지를 정하는 시간

 

각각의 설정을 통해 데이터를 더 효율적으로 관리하고, 불필요한 네트워크 요청을 줄이면서 최신 데이터를 가져올 수 있습니다.