[REACT] react-query (v3)

react-query (v3) 설치 및 공식문서

Installation | TanStack Query Docs

 npm i react-query

---

react-query 에서 사용되는 용어

fresh, stale

• fresh 는 신선한, stale 은 상한 의 의미를 가지는 영어 단어
• 데이터를 받아오면 fresh 상태 에서 stale 로 변경된다.
• 웹은 stateless 기 때문에, 클라이언트 영역의 데이터와 서버의 데이터의 정합성을 실시간으로 유지할 수 없다.

refetch 의 조건

• 새로운 query instance가 마운트 될 때 ( 페이지 이동 )
• 브라우저 화면을 이탈 했다가 다시 focus 할 때 (refetchOnWindowFocus)
• 네트워크가 다시 연결될 때 (refetchOnReconnect)
• 특별히 설정한 refetch interval에 의한 경우 (refetchInterval)

staleTime

• 데이터가 fresh 에서 stale 상태로 변경되는 시간 ( default : 0 초 ) ( v4 default : Infinity )
• fresh 상태에서는 쿼리 인스턴스가 새롭게 mount 되어도 ( 페이지 이동 ) fetch가 발생하지 않는다.
• 데이터가 한번 fetch 되고 나서 staleTime이 지나지 않았다면 unmount 후 mount 되어도 fetch가 일어나지 않는다.
• staleTime: Infinity 시 페이지 이동, refetchOnWindowFocus, refetchOnReconnect 를 true 로 설정하여도 fetch 하지 않는다.
• refetchInterval 은 staleTime 과 관계 없이 동작한다.
• 따라서 데이터 구조가 변경이 빈번한경우 staleTime 을 지정 하지 않는게 좋고, 정적 데이터일 경우 staleTime 을 지정해 서버 부하를 줄이는게 좋다.

cacheTime

• 데이터가 inactive 상태일 때 캐싱된 상태로 남아있는 시간 ( default : 5 분, 5 * 60 * 1000ms )
• 쿼리 인스턴스가 unmount 되면 데이터는 inactive 상태로 변경되며, 캐시는 cacheTime만큼 유지된다.
• cacheTime이 지나기 전에 쿼리 인스턴스가 다시 마운트 되면, 데이터를 fetch하는 동안 캐시 데이터를 보여준다.

---

QueryClientProvider

• 캐시 관리를 위해 QueryClient 인스턴스를 사용한다.
• QueryClient 인스턴스를 접근하는 useQueryClient 훅스를 사용하기 위해 QueryClientProvider 로 감싼다.
• QueryClient 생성자 안에 옵션을 넣어 default 값 셋팅을 할 수 있다.

import { QueryClient, QueryClientProvider } from 'react-query'

const queryClient = new QueryClient()

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}

new QueryClient({
  defaultOptions: {
    queries: {
    },
    mutations: {
    },
  },
});

---

useQuery

• 서버에서 데이터를 가져오고 ( fetch ) 캐싱하는데 사용하는 hooks
• 보통 데이터 조회 ( get ) 에서 사용하고, 구조분해 값은 주로 아래의 4가지를 사용한다.

const {data, isLoading, isError, isSuccess } = useQuery(key, function, options?)

반환 값

• data : 응답 데이터
• error : 에러시 리턴되는 객체
• isError : 에러 발생시 boolean 값 리턴
• isSuccess : 요청 성공시 상태에 따라 boolean 리턴
• isLoading : 캐싱 데이터가 없을 때 fetch ( 데이터 요청 ) 중에 true
• isFetching : 데이터가 fetch 될 때 true, 캐싱 데이터가 있더라도 요청중 true

query key

// 다른 키로 취급한다. 
useQuery(['todo', 1], ...)
useQuery(['todo', 2], ...)

// 객체 필드의 값이 달라도 다른 키로 취급한다
useQuery(['todo', { preview: true }], ...)
useQuery(['todo', { preview: false }], ...)

// 객체 필드의 순서가 달라도 내용이 같으면 같은 키로 취급한다
useQuery(['todo', { preview: true, status: 'done' }], ...)
useQuery(['todo', { status: 'done', preview: true }], ...)

query function

• 서버에서 데이터를 요청하고 Promise 객체를 반환하는 함수를 전달한다. axios, fetch
• 단 fetch 사용시 별도의 Promise 에러 처리를 해야한다.

options

• onSuccess, onError, onSettled : 함수 값을 전달해 결과( 성공, 실패, 완료 )에 따른 사이드 이펙트 정의
• select : 데이터 조정
• refetchOnWindowFocus : 브라우저를 포커싱 할때 refetch boolean
• refetchOnReconnect : 네트워크 재 연결시 refetch boolean
• refetchInterval : 주기적인 refetch
• staleTime : fresh 상태 유지
• retry : 요청 실패시 재요청 ( default : 3 )
• 그 외 : cacheTime, enabled, initialData, initialDataUpdatedAt, isDataEqual, keepPreviousData, meta, notifyOnChangeProps, notifyOnChangePropsExclusions, placeholderData, queryKeyHashFn, refetchIntervalInBackground, refetchOnMount, refetchOnReconnect, retryOnMount, retryDelay, select, structuralSharing, suspense, useErrorBoundary

---

useMutation

• 생성, 수정, 삭제 (CUD) 시 주로 사용하는 hooks

const mutation = useMutation(fetchAPI, options?);
const mutation = useMutation(key, fetchAPI, options?)

const onSubmit = useCallback(() => {
	...
	mutation.mutate(data);
}, [])

반환 값

• data : 응답 데이터
• isLoading : 캐싱 데이터가 없을 때 fetch ( 데이터 요청 ) 중에 true
• isError : 에러 발생시 boolean 값 리턴
• isSuccess : 요청 성공시 상태에 따라 boolean 리턴
• mutate : mutation을 실행하는 함수
• mutateAsync : Promise 를 반환하는 mutate
• reset : mutate 내부 상태를 reset

useMutation의 mutate함수는 Promise를 반환하지 않는다.

mutateAsync 함수는 Promise를 반환하기 때문에 직접적인 사용이 가능하다. try catch 문안에 mutateAsync를 호출하여 성공, 실패와 같은 서버의 응답 결과를 처리할 수 있다.

Redux-Saga를 사용했을 때는 takeLatest와 같은 이펙트를 사용하여 API의 중복 호출을 제어할 수 있으나, useMutation은 중복 호출에 대한 제어 옵션이 없기 때문에 이를 제어하기 위해서는 쓰로틀링, 디바운싱을 구현해서 사용하거나, isLoading이나 useIsMutating을 활용해서 제어하는 방법들이 있다.

options

{
    onMutate: (variables) => {
			// Mutation 전에 실행하는 함수, variables 는 전달한 값 
    },
    onError: (error, variables, context) => {
			// 실패 시 동작할 이펙트
    },
    onSuccess: (data, variables, context) => {
			// 성공 시 동작할 이펙트
			queryClient.invalidateQueries(key); 
			// 해당 키값의 데이터를 refetch 하기위해 데이터 폐기
			// 아래에서 설명
    },
    onSettled: (data, error, variables, context) => {
			// 실행 완료후 동작
    },
 }

• etc : mutationKey, retry, retryDelay, useErrorBoundary, meta

---

invalidation

• invalidation은 해당 key를 가진 query를 stale 취급하며 폐기한다.
• server 데이터를 변경, 생성, 삭제시 client 데이터를 갱신하기 위해 refetch 한다.

// QueryClient 로 감싼 내부 컴포넌트에서 사용하는 훅스
const queryClient = useQueryClient()
...

// 캐시가 있는 모든 쿼리
queryClient.invalidateQueries()

// 'todos'로 시작하는 모든 쿼리
queryClient.invalidateQueries('todos')

// ['todos', 1] 키를 가진 쿼리를 무효화한다.
queryClient.invalidateQueries(['todos', 1])

---

Reference

My구독의 React Query 전환기

blog.rhostem.com

[react query] stale이란? (feat, 캐싱,use query,fetch, react query에 대해 알아보)

React Query 사용법

---

There might be incorrect information or outdated content.