[Tanstack Query] 2. 데이터 가져오기와 캐싱

1. Query의 기본 동작

useQuery는 데이터를 가져올 때 아래 순서로 동작한다.

1. 캐시 확인 → 기존 데이터가 있으면 재사용
2. stale 상태 확인 → staleTime 이내면 캐시 사용, 넘어가면 서버 재요청
3. 서버 요청 → 데이터가 없거나 staleTime이 지나면 API 호출
4. 자동 갱신 → refetchInterval, enabled 옵션 등으로 새 데이터 가져오기

staleTime과 gcTime의 차이

옵션	설명	기본값
staleTime	데이터가 “stale” 상태로 간주되기 까지의 시간	0ms
gcTime	데이터가 캐시에 남아있는 시간
(v5, cacheTime → gcTime 변경)	5분

---

2. staleTime과 gcTime 비교

<script setup lang="ts">
import { getUsersApi } from '@/apis/users'
import { useQuery } from '@tanstack/vue-query'

const {data, isLoading, isFetching, error,} = useQuery({
  queryKey: ['users'],
  queryFn: getUsersApi, 
  staleTime: 5000, // 5초 동안 캐시된 데이터 사용
  gcTime: 10000,   // 10초 후 캐시 삭제
})
</script>

staleTime

해당 시간 동안 캐시된 데이터를 사용한다.

상태: fresh → stale

gcTime

해당 시간 동안 캐시를 유지, 시간이 지나면 삭제

페이지를 벗어나면 inactive 상태가 되고, gcTime이 지나면 사라진다.

inactive 상태에 해당 페이지로 돌아갔는데 fresh상태라면 재요청 없이 캐시된 데이터를 사용, stale 상태라면 새 데이터를 가져오는 동안 캐시 데이터 표시

상태: inactive → (삭제)

staleTime과 gcTime 조합 정리

상황	설명	결과
fresh data, 유효한 gcTime	캐시 데이터가 fresh 상태(staleTime 내)	리패치 없음, 캐시 데이터 바로 반환
stale data, 유효한 gcTime	staleTime이 지나서 데이터가 stale 상태	리패치 발생, 기존 캐시 데이터 먼저 표시
gcTime 초과 (캐시 삭제됨)	gcTime이 지나 캐시 데이터가 삭제됨	리패치 발생, 캐시가 없으므로 빈 상태부터 시작

변형 케이스

일반적으로 일어나지 않는다. 특정 설정을 일부러 넣어야만 발생한다.

상황	설명	결과
staleTime 무한대	데이터가 항상 fresh 상태	Refetch 없음, 캐시 데이터만 계속 사용
gcTime 무한대	캐시가 절대 삭제되지 않음	언제든 캐시된 데이터 반환 가능

---

3. 자동 새로고침 : refetchInterval

<script setup lang="ts">
import { getUsersApi } from '@/apis/users'
import { useQuery } from '@tanstack/vue-query'

const {data, isLoading, isFetching, error,} = useQuery({
  queryKey: ['users'],
  queryFn: getUsersApi, 
	refetchInterval: 5000, // 5초 후 자동 새로고침
})
</script>

데이터를 가져오는 즉시 fresh→stale이 되고 5초 마다 새로 데이터를 가져온다.