TanStack Query란?
서버로부터 데이터 가져오기,데이터 캐싱,캐시 제어등 데이터를 쉽고 효율적으로 관리할 수 있는 라이브러리
기능 정리
- 데이터 가져오기 및 캐싱
- 동일 요청의 중복 제거 (단일 요청으로 통합)
- 신선한 데이터 유지 및 빠른 데이터 업데이트
- 페이지네이션 및 데이터 지연로드 등의 성능 최적화
- 네트워크 재연결, 요청 실패 등의 자동 갱신
기본 설정
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 10
},
},
});
function App() {
return (
<QueryClientProvider client={queryClient}>
<div>기본 설정 세팅</div>
</QueryClientProvider>;
);
}1. QueryClient를 사용하여 캐시와 상호 작용 할 수 있다.
2. QueryClientProvider를 최상단에서 감싸주고 QueryClient 인스턴스를 client props로 넣어 연결해야 함.
3. 해당 context는 비동기 요청을 알아서 처리하는 background 계층이 된다.데이터 캐싱
const result = useQuery({
queryKey: ["A"],
queryFn,
staleTime: 0, // (기본값 0초)
gcTime: 1000 * 60 * 5, // (기본값 5분)
});1. A라는 queryKey를 가진 쿼리 인스턴스가 mount
2. 네트워크 요청을 통해 데이터를 fetch(queryFn)하고, 데이터 A라는 queryKey로 캐싱
3. 기본값인 staleTime이 0이므로, 데이터를 가져오자마자 바로 stale(상함) 상태로 전환
4. 쿼리 인스턴스가 unmount 되면, Tanstack Query는 해당 캐시를 gcTime 동안 유지
5. 설정해놓은 5분 이내에 A 쿼리가 다시 mount 되면, 캐시된 데이터를 즉시 반환
(동시에 queryFn은 background에서 실행)
6. 5분 이내에 A 쿼리가 다시 mount 되지 않으면, 해당 캐시는 가비지 컬렉션에 의해 삭제
// gcTime: 해당 시간이 지나면 "데이터 캐시에서 제거" (메모리에서도 사라짐)
// staleTime: "데이터가 상하는데까지 걸리는 시간" 설정 옵션 (위 코드는 0으로 설정했기 때문에 바로상함)useQuery 기본 문법
- useQuery는
v5부터 인자로 단 하나의 객체만 받는다. 그 중 첫번째 인자queryKey,queryFn가 필수 값이다.
const result = useQuery({
queryKey, // 쿼리 식별자 (필수)
queryFn, // 데이터 fetch하는 비동기 함수 (필수)
// 옵션 예시) gcTime, staleTime, select 등
});
result.data; // queryFn 결과값 or 캐시된 데이터
result.isStale; // 값이 상했는지 여부 (staleTime 지나면 true)
result.refetch; // 재요청 함수 (queryFn을 다시 실행시키는 수동 트리거)
result.isLoading; // 로딩 상태 (queryFn 진행 상태 확인)useQuery - queryFn
- 쿼리 함수는 데이터를 가져오는 비동기 함수로, 꼭 데이터를 반환하거나 오류를 던져야 함
- 던져진 오류는 반환되는
error객체로 확인 가능 error는 기본적으로null
import { useQuery } from '@tanstack/react-query'
type ResponseValue = {
message: string
time: string
}
export default function DelayedData() {
const { data, error } = useQuery<ResponseValue>({
queryKey: ['delay'],
queryFn: async () => {
const res = await fetch('https://api.heropy.dev/v0/delay?t=1000')
const data = await res.json()
if (!data.time) {
throw new Error('문제가 발생했습니다!')
}
return data
},
staleTime: 1000 * 10,
retry: 1
})
return (
<>
{data && <div>{JSON.stringify(data)}</div>}
{error && <div>{error.message}</div>}
</>
)
}useQuery 주요 리턴 데이터
const {
data,
error,
status,
isPending,
fetchStatus,
isLoading,
isFetching,
isError,
refetch,
// ...
} = useQuery({
queryKey: ["all-items"],
queryFn: getAllItems,
});
- data: 쿼리 함수가 리턴한 Promise에서 resolved된 데이터
- error: 쿼리 함수에 오류가 발생한 경우, 쿼리에 대한 오류 객체
- status: data, 쿼리 결과값에 대한 상태를 표현하는 status는 문자열 형태로 3가지의 값이 존재한다.
- pending: 쿼리 데이터가 없고, 쿼리 시도가 아직 완료되지 않은 상태
ㅤ- { enabled: false } 상태로 쿼리가 호출되면 이 상태로 시작된다
- error: 에러 발생했을 때 상태
- success: 쿼리 함수가 오류 없이 요청 성공하고 데이터를 표시할 준비가 된 상태- isPending: 쿼리가 아직 수행되지 않았고, 캐싱된 데이터가 없을 때 true를 반환한다
- status(pending)에 파생된 boolean 값이다- fetchStatus: queryFn에 대한 정보를 나타냄
- fetching: 쿼리가 현재 실행 중인 상태
- paused: 쿼리를 요청했지만, 잠시 중단된 상태 (network mode와 연관)
- idle: 쿼리가 현재 아무 작업도 수행하지 않는 상태- isLoading: 캐싱 된 데이터가 없을 때 즉, 처음 실행된 쿼리일 때 로딩 여부에 따라 true/false로 반환된다.
- 이는 캐싱 된 데이터가 있다면 로딩 여부에 상관없이 false를 반환한다.
- status(pending)와 fetchStatus(fetching) 결합된 boolean이다. 즉, isFetching && isPending 와 동일하다.- isFetching: 캐싱된 데이터가 있더라도 서버에 요청을 보내면 true를 반환한다
- fetchStatus(fetching)에 파생된 boolean 값이다- isSuccess: 쿼리 요청이 성공하면 true
- isError: 쿼리 요청 중에 에러가 발생한 경우 true
- refetch: 쿼리를 수동으로 다시 가져오는 함수
그 외 반환 데이터들을 자세히 알고 싶으면 useQuery 공식 문서 참고
솔직히 옵션이 너무 많아서 엄청 복잡해보인다. 하지만 평소 state 관리하던 loading이나 성공 결과들을
API 요청 시 한번에 처리 할 수 있다는것이 tanStack Query의 장점인 것 같다.
옵션을 하나씩 정리하기에는 너무 많은 양으로 아래 참조 링크를 보며 학습하도록 하자... 🙀
https://www.heropy.dev/p/HZaKIE
https://github.com/ssi02014/react-query-tutorial?tab=readme-ov-file#%EA%B0%9C%EC%9A%94
