1. 핵심 Hooks
| 함수 |
용도 |
주요 반환값 |
주요 옵션 |
|---|
| useQuery |
데이터 조회 (GET) |
data, isLoading, isError, error, isFetching, refetch |
queryKey, queryFn, enabled, staleTime, gcTime, retry, select |
| useMutation |
데이터 변경 (POST/PUT/DELETE) |
mutate, mutateAsync, isPending, isSuccess, isError, data, reset |
mutationFn, onSuccess, onError, onMutate, onSettled |
| useInfiniteQuery |
무한 스크롤/페이지네이션 |
data, fetchNextPage, fetchPreviousPage, hasNextPage, hasPreviousPage, isFetchingNextPage |
queryKey, queryFn, initialPageParam, getNextPageParam, getPreviousPageParam |
| useQueryClient |
QueryClient 인스턴스 접근 |
queryClient 객체 |
– |
| useSuspenseQuery |
Suspense와 함께 사용 |
data (항상 존재) |
useQuery와 동일 |
| useQueries |
여러 쿼리 동시 실행 |
쿼리 결과 배열 |
queries 배열 |
| useIsFetching |
현재 fetching 중인 쿼리 수 |
숫자 |
queryKey, filters |
| useIsMutating |
현재 mutating 중인 개수 |
숫자 |
mutationKey, filters |
2. QueryClient 메서드
캐시 관리
| 메서드 |
용도 |
예시 |
|---|
| invalidateQueries |
쿼리를 stale로 만들고 리페치 |
queryClient.invalidateQueries({ queryKey: ['todos'] }) |
| refetchQueries |
쿼리 즉시 리페치 |
queryClient.refetchQueries({ queryKey: ['todos'] }) |
| cancelQueries |
진행 중인 쿼리 취소 |
queryClient.cancelQueries({ queryKey: ['todos'] }) |
| removeQueries |
쿼리를 캐시에서 제거 |
queryClient.removeQueries({ queryKey: ['todos'] }) |
| resetQueries |
쿼리를 초기 상태로 리셋 |
queryClient.resetQueries({ queryKey: ['todos'] }) |
| clear |
모든 캐시 제거 |
queryClient.clear() |
데이터 조회/설정
| 메서드 |
용도 |
예시 |
|---|
| getQueryData |
캐시에서 데이터 읽기 |
queryClient.getQueryData(['todos']) |
| setQueryData |
캐시 데이터 직접 수정 |
queryClient.setQueryData(['todos'], newData) |
| getQueryState |
쿼리 상태 가져오기 |
queryClient.getQueryState(['todos']) |
| setQueryDefaults |
쿼리 기본 옵션 설정 |
queryClient.setQueryDefaults(['todos'], { staleTime: 10000 }) |
| getQueriesData |
여러 쿼리 데이터 가져오기 |
queryClient.getQueriesData({ queryKey: ['todos'] }) |
| setQueriesData |
여러 쿼리 데이터 설정 |
queryClient.setQueriesData({ queryKey: ['todos'] }, updater) |
Prefetching
| 메서드 |
용도 |
예시 |
|---|
| prefetchQuery |
데이터 미리 가져오기 (Promise 반환) |
await queryClient.prefetchQuery({ queryKey: ['todos'], queryFn }) |
| prefetchInfiniteQuery |
무한 쿼리 미리 가져오기 |
await queryClient.prefetchInfiniteQuery({ queryKey, queryFn }) |
| ensureQueryData |
캐시에 없으면 fetch, 있으면 반환 |
const data = await queryClient.ensureQueryData({ queryKey, queryFn }) |
3. 주요 옵션
useQuery 옵션
| 옵션 |
타입 |
기본값 |
설명 |
|---|
| queryKey |
unknown[] |
필수 |
쿼리의 고유 키 |
| queryFn |
() => Promise<T> |
필수 |
데이터를 가져오는 함수 |
| enabled |
boolean |
true |
false면 쿼리 자동 실행 안 됨 |
| staleTime |
number |
|
데이터가 fresh 상태로 유지되는 시간 (ms) |
| gcTime |
number |
5분 |
캐시 보관 시간 (구 cacheTime) |
| retry |
boolean | number | function |
3 |
실패 시 재시도 횟수 |
| retryDelay |
number | function |
지수 증가 |
재시도 간격 |
| refetchOnMount |
boolean | "always" |
true |
마운트 시 리페치 여부 |
| refetchOnWindowFocus |
boolean | "always" |
true |
윈도우 포커스 시 리페치 |
| refetchOnReconnect |
boolean | "always" |
true |
재연결 시 리페치 |
| refetchInterval |
number | false |
false |
주기적 리페치 간격 (ms) |
| select |
(data: T) => U |
undefined |
데이터 변환 함수 |
| placeholderData |
T | function |
undefined |
로딩 중 표시할 임시 데이터 |
| initialData |
T | function |
undefined |
초기 데이터 (캐시에 저장됨) |
useMutation 옵션
| 옵션 |
타입 |
설명 |
|---|
| mutationFn |
(variables) => Promise<T> |
mutation 실행 함수 (필수) |
| mutationKey |
unknown[] |
mutation의 고유 키 |
| onMutate |
(variables) => Promise<Context> | Context |
mutation 시작 전 실행 (낙관적 업데이트) |
| onSuccess |
(data, variables, context) => void |
성공 시 콜백 |
| onError |
(error, variables, context) => void |
실패 시 콜백 |
| onSettled |
(data, error, variables, context) => void |
성공/실패 후 항상 실행 |
| retry |
boolean | number |
재시도 횟수 |
| retryDelay |
number | function |
재시도 간격 |
4. 상태 플래그
useQuery 상태
| 플래그 |
타입 |
설명 |
|---|
| status |
'pending' | 'error' | 'success' |
쿼리 상태 |
| fetchStatus |
'fetching' | 'paused' | 'idle' |
fetch 상태 |
| isLoading |
boolean |
처음 로딩 중 (isPending && isFetching) |
| isPending |
boolean |
아직 데이터가 없음 |
| isSuccess |
boolean |
성공적으로 데이터 로드 |
| isError |
boolean |
에러 발생 |
| isFetching |
boolean |
현재 fetching 중 (백그라운드 포함) |
| isStale |
boolean |
데이터가 stale 상태 |
| isPlaceholderData |
boolean |
placeholder 데이터 표시 중 |
useMutation 상태
| 플래그 |
타입 |
설명 |
|---|
| status |
'idle' | 'pending' | 'error' | 'success' |
mutation 상태 |
| isIdle |
boolean |
아직 실행 안 됨 |
| isPending |
boolean |
실행 중 |
| isSuccess |
boolean |
성공 |
| isError |
boolean |
실패 |
| data |
T |
mutation 결과 데이터 |
| error |
Error |
에러 객체 |
5. 유틸리티 함수
| 함수 |
용도 |
예시 |
|---|
| hashKey |
queryKey를 해시로 변환 |
import { hashKey } from '@tanstack/react-query' |
| matchQuery |
쿼리 매칭 |
filters에서 사용 |
| matchMutation |
mutation 매칭 |
filters에서 사용 |
6. 필터 옵션
invalidateQueries, refetchQueries 등에서 사용:
| 필터 |
타입 |
설명 |
|---|
| queryKey |
unknown[] |
특정 쿼리 키 매칭 |
| exact |
boolean |
정확히 일치하는 쿼리만 |
| predicate |
(query) => boolean |
커스텀 매칭 함수 |
| type |
'active' | 'inactive' | 'all' |
쿼리 타입 필터 |
| stale |
boolean |
stale 상태 필터 |
| fetchStatus |
'fetching' | 'paused' | 'idle' |
fetch 상태 필터 |