[hook] useQuery

 

options

useQuery({
  queryKey,
  queryFn,
  enabled,
  staleTime,
  gcTime,
  retry,
  retryDelay,
  refetchOnWindowFocus,
  refetchOnReconnect,
  refetchOnMount,
  refetchInterval,
  refetchIntervalInBackground,
  initialData,
  placeholderData,
  select,
  structuralSharing,
  meta,
  networkMode,
  queryHash,
})

 

 

 1) queryKey (필수)

Query 캐시 식별자.

`queryKey: ['user', userId]`

키가 같으면 캐시를 재사용

배열 형태 권장

---

 

  2) queryFn (필수)

데이터를 가져오는 함수.

`queryFn: () => axios.get('/api/user')`

---

3) enabled (조회 ON/OFF)

false면 자동 실행 안 됨 → 조건부 요청에 필수.

`enabled: !!userId`

---

4) staleTime (신선한 상태 유지 시간)

단위: ms
데이터가 "신선한" 것으로 간주되는 시간 → 이 동안은 재요청 안 함

`staleTime: 1000 * 60`  // 1분

기본: 0ms → 항상 stale → 포커스 이동 시 재요청

---

5) gcTime (가비지 컬렉션 유지 시간)

stale 캐시가 언마운트 후 사라지기까지의 캐시 보관 시간

staleTime과 같은 기능 하지만 메모리의 데이터를 삭제하는점이 다름

`gcTime: 5 * 60 * 1000` // 5분

React Query v4 기준 cacheTime → v5에서는 gcTime.

 

필요	기능설정
컴포넌트 나가면 캐시 즉시 삭제	gcTime: 0
컴포넌트 벗어나든 말든 항상 API 새로 호출	gcTime: 0 + staleTime: 0 + refetchOnMount: 'always'
캐시 자체를 완전히 안 쓰는 느낌으로 동작	gcTime: 0 + staleTime: 0

---

6) retry (재시도 횟수)

기본값: 3

retry: 2          // 최대 2번 재시도
retry: false      // 재시도 X
retry: (failCount, err) => failCount < 2

---

 

7) retryDelay (재시도 간격)

retryDelay: attemptIndex => attemptIndex * 1000,

---

8) refetchOnWindowFocus (포커스 시 재요청)

기본값: true
refetchOnWindowFocus: false

SPA에서는 보통 꺼서 UX 개선.

---

 

9) refetchOnReconnect (네트워크 다시 연결되면 재요청)

기본: true

---

10) refetchOnMount (컴포넌트 마운트 시 재요청)

기본값: "always"

설정 예:
`refetchOnMount: false`

---

11) refetchInterval (폴링)

주기적으로 데이터 다시 받기.

refetchInterval: 5000  // 5초마다 재요청

---

 

12) refetchIntervalInBackground

탭이 background여도 폴링 유지.

refetchIntervalInBackground: true

---

13) initialData (최초 로딩시 임시 데이터)

서버 요청 전 임시 값.

initialData: () => [{ id: 1, name: 'temp' }]

---

14) placeholderData (로딩 중 화면용 데이터)

Skeleton 역할, 실제 캐시에 저장되지 않음.

placeholderData: []

---

15) select (데이터 변환)

응답 데이터를 가공해서 리턴.

`select: (data) => data.items`
캐시에는 원본 그대로 저장되며, select는 “표현용”.

---

16) structuralSharing (구조적 공유)

객체 비교 시 deep compare 최적화
기본값: true

 

이전 캐시:
{ user: { name: "Tom", age: 20 } }

새 응답:
{ user: { name: "Tom", age: 21 } }

→ 생성 결과:
user: { name: (기존 객체 그대로), age: (새 값) }

 

=> React 리렌더도 최소화됨

---

17) meta (메타데이터)

미들웨어 또는 DevTools용 정보 저장용

meta: { authRequired: true }

---

18) networkMode (네트워크없을 때 동작)

"online" (기본)

"always": 오프라인에서도 실행

"offlineFirst"

예: `networkMode: 'offlineFirst'`

---

 

---

exact

옵션	의미
exact: true	쿼리 키가 완전히 같은 경우만 무효화
exact: false (기본값)	쿼리 키가 부분 일치하는 것까지 전부 무효화

 

queryClient.invalidateQueries({
  queryKey: ['todos'],
});

 

✅ 전부 무효화됨

• ['todos']
• ['todos', 1]
• ['todos', { status: 'done' }]

➡ ['todos']로 시작하는 모든 쿼리