react-query란 도대체 뭘까?

저는 React Query를 처음 접해보는 사람의 입장으로서, 조금 더 쉽게 이에 대해서 이해하고, 사용해야 하는 이유를 느껴보기 위해서 이 아티클을 작성합니다.

React Query는 대표적인 서버 상태 관리에 사용되는 도구입니다!

그렇다면, React에서는 기존에 어떻게 상태관리를 하고 있었을까요?

▶️ React의 상태 관리

📚 state(상태)란?

저는 지난 주 공유과제를 하면서 React의 상태에 조금 더 이해할 수 있었는데요!
리액트에서 상태란 컴포넌트 내부에서 변할 수 있는 값입니다.

위 사진은 팜스프링의 사진인데요,
우측 상단에 로그인 한 상태와 로그인 하지 않은 상태에 따라 버튼이 구분되는 것을 확인할 수 있습니다.

즉, 상태란 "유저와의 상호작용을 위한, 변할 수 있는 데이터" 라고 다시 한 번 정리할 수 있습니다.

그럼 본격적으로 react-query에 대해서 알아보겠습니다.

▶️ react-query?

react-query란 fetching, caching, 서버 데이터와의 동기화를 지원해주는 라이브러리 - 공식문서

조금 자세하게 말하면, react-query는 React Application에서
서버의 상태를 불러오고, 캐싱하며, 지속적으로 동기화하고 업데이트하는 작업을 도와주는 라이브러리입니다.

그럼 여기서 나오는 서버의 상태는 위에서 알아본 React의 상태와 다른 걸까요?

서버는 클라이언트에게 데이터베이스에 있는 정보를 전달해주는 역할을 하는데요,
이 때, 데이터베이스에서 가져온 데이터
즉, 서버에서 전달받는 데이터를 우리는 서버의 상태라고 이야기합니다.

즉, 상태(state) 라고 하면 위에서 알아본 것 처럼, 클라이언트에서 뿐만 아니라 서버에서도 받을 수 있는 모든 것들을 포함하고 있습니다.

그래서 상태는 클라이언트의 상태와 서버의 상태로 나뉘어지는데,
각각의 간단한 특징에 대해 살펴보겠습니다.

클라이언트 상태

UI 테마, 사이드바, 폼 입력 등
즉, 유저와의 인터렉션에 의해서 발생하는 상태(데이터)

서버 상태

유저 DB 정보 등과 같이 클라이언트가 서버로부터 받아오는 모든 데이터
즉, API 통신을 통해서 서버에서 받아온 데이터(상태)

결국, 서버 상태 관리에 사용되는 react-query란 간단하게 비동기 API 호출을 통해 불러오는 데이터들을 관리하기 위해서 사용되는 것입니다.

그럼 이제는 왜, 도대체 왜 API 호출과 같은 데이터들은 react-query를 사용해서 서버 상태 관리를 사용해야할까? 라는 궁금증이 생기기 마련입니다.

▶️ Why React Query?

이는 React-query를 사용했을 때의 여러가지 이점들을 얻을 수 있기 때문입니다.
한 번 살펴볼까요?

React Query의 이점

📌 1. 캐싱(cachcing)

캐싱이란 특정 데이터의 복사본을 저장하여 이후 동일한 데이터에 다시 접근할 때, 속도를 높이는 것을 말합니다.

React Query는 캐싱을 통해 동일한 데이터에 대한 반복적인 비동기 데이터 호출을 방지하고, 이는 불필요한 API 호출을 막아 서버에 대한 부하를 줄이는 결과를 가져옵니다.

이 과정이 중요한 이유는 API 호출 == 비용을 뜻하기 때문입니다.

카카오톡처럼 실시간이 중요한 서비스가 아니라, 공지사항과 같이 많아야 하루의 1개 정도의 업로드가 되는 불필요한 API 호출을 페이지가 들어갈 때 마다 한다면, 우리는 불필요한 데이터 호출을 반복적으로 해 서버의 대한 부하와 비용을 늘리고 있는 것 아닐까요?

여기서 우리의 의문은 "반복적인 데이터가 아닌 데이터가 변경되었을 경우에는 어떻게 갱신할 수 있지?"입니다.

만약, 서버 데이터를 불러와 캐싱한 후, 실제 서버 데이터를 확인했을 때 서버 상에서 데이터의 상태가 변경되어 있다면, 사용자는 실제 데이터가 아닌 변경 전의 데이터를 보게 됩니다. 이는 사용자에게 잘못된 정보를 보여주는 에러를 낳습니다.

그럼 이런 에러를 발생시키지 않고, 필요한 상황에 적절하게 데이터를 갱신해 줄 수 있어야 합니다. 그렇다면 그런 상황은 언제일까요?

📚 언제 데이터를 갱신해야 하는가?

기본적으로는 컴포넌트 최초 mount 시에 데이터를 fetching 해온 후,

• 새로운 Query Instance가 마운트 될 때 (refetchOnMount)
• 브라우저 화면을 다시 focus 할 때 (refetchOnWindowFocus)
• 인터넷이 재연결되었을 때 (refetchOnReconnect)
• refetchInterval이 설정되어있을 때

위 조건에 따라 refetching이 발생하게 됩니다.
이를 위해서 React Query에서는 기본적인 아래의 옵션을 제공합니다.

refetchOnWindowFocus, // default: true
refetchOnMount, // default: true
refetchOnReconnect, // default: true
staleTime, // default: 0
gcTime, // default: 5분 (60 * 5 * 1000)

위의 옵션들을 통해 React Query가 어떤 시점에 데이터를 refetching 할지 설정해줄 수 있습니다.

📚 staleTime vs gcTime(cacheTime) 이란?

v5 이후 cacheTime -> gcTime으로 바뀌었습니다.
이해가 쉽도록 cacheTime이라는 용어를 사용해서 설명하도록 하겠습니다.

여기서, cacheTime은 cache에 사용되는 시간이라는 것을 유추할 수 있는데,
저와 같이 처음 접해시는 분들은 'stale은 무슨 개념이지?' 라는 생각이 들텐데요

React Query에는 cache와는 별도로 stale이라는 개념이 있습니다.
그리고 stale과 대비되는 fresh라는 개념도 있습니다.

여기서 fresh와 stale 단어의 대비에서 알 수 있듯이
fresh는 데이터를 그대로 사용해도 좋을 만큼 신선한 상태라는 뜻이며,
stale은 데이터를 새롭게 fetch해 오는 것이 필요할 만큼 신선하지 못한 상태라는 뜻입니다.

중요한 개념인데요, staleTime을 설정해주면 그만큼 데이터가 fresh 상태로 존재하였다가 그 후에는 stale 상태로 바뀝니다.

예를들어, staleTime을 10,000으로 설정하였다면, data fetching이 성공한 후 10초(= 10,000ms) 동안 fresh 상태로 존재하다가 10초 이후에는 stale 상태가 됩니다. stale 상태가 된 후 위에서 알아본 refetching 특정 조건들이 충족되면 이때, refetching이 발생하게 됩니다.

주의할 점은 stale 상태가 되었다고 해서 refetching이 곧바로 일어나는 것이 아니라,
stale 상태가 되고 특정조건을 만족해야 refetching이 일어난다는 것입니다.

📚 그럼 왜 stale이 필요할까?

저도 처음에는 잘 이해가 되지 않았습니다.
stale과 cache는 비슷한 역할을 하는 것 같은데 어째서 cache만으로 관리하지 않고, stale과 cache라는 개념으로 나누어서 관리하지? 라는 의문이 들었습니다. 그런데 cache만으로 관리했을 때와의 차이점을 생각해보니 조금 이해가 편했습니다.

위 상황은 useQuery를 이용해 캐싱된 데이터가 stale 상태로 바뀐 이후에,
페이지를 이동하여 동일한 키값의 데이터를 refetching 해야하는 상황을 나타낸 것입니다.

stale과 cache로 관리할 때와 cache만으로 관리할 때의 ⓐ, ⓑ, ⓒ, ⓓ는 각각 다음과 같은 모습입니다.

차이점은 ⓒ입니다.
자료의 위 사진들처럼 stale과 cache로 관리하게 된다면, ⓒ에서 stale 상태의 캐싱된 데이터를 이용한 UI를 먼저 보여준 후, refetching을 완료하면 새로운 데이터를 이용한 UI로 교체해줄 수 있습니다.

refetching 이전과 이후의 데이터가 많이 다르지 않다면, 사용자는 페이지 이동 후 더욱 빠르게 서비스를 이용할 수 있게됩니다.

반면 cache만으로 관리하게 된다면 이와는 달라집니다.
자료의 아래 사진 처럼 페이지 이동 직전에 캐시가 만료되었다고 가정해보겠습니다.
캐시가 만료되어 삭제되었을테니, ⓒ에서 refetching이 완료되기 전까지 데이터가 없으므로 Loading 페이지를 보여줘야합니다. 그리고 refetching이 완료되면 그제야 데이터를 이용한 UI를 보여줄 수 있습니다.

이렇게 되면 사용자는 페이지 이동 후 더욱 느리게 서비스를 이용하게 됩니다.

그래서 'staleTime이 cacheTime보다 작게 설정하는게 좋다' 라고 합니다.

그래서, staleTime, cacheTime은 원격 서버와 통신하는데에 걸리는 시간을 단축하고자,
여러번 불러올 데이터는 캐시에 저장하여 반복해서 필요로 할 경우 원격 서버가 아닌 캐시에서 빠르게 가져올 수 있는 방식입니다!

📚 Query Invalidation

여기서 지정해준 staleTime과는 무관하게 즉시 데이터를 stale 상태로 처리해야하는 경우가 있는데요!

예를 들어, API에 POST 요청을 보내 데이터 값을 업데이트할 때, API 엔드포인트에 있는 데이터의 값이 캐시에 저장되어있는 값보다 더 최신 상태가 되고, 캐시에 저장되어있는 데이터는 곧바로 stale한 값이 되어버립니다.

이럴 때엔 즉시 캐시 데이터를 stale 상태로 처리해줘야 합니다.

이는 QueryClient 객체의 invalidateQueries 메소드를 활용해서 수행할 수 있습니다!

// 사용법

// useQueryClient 훅을 사용하여 queryClient 객체 생성
const queryClient = useQueryClient();

// 캐시의 모든 쿼리 무효화
queryClient.invalidateQueries();

// 'users'로 시작하는 키가 있는 모든 쿼리 무효화
queryClient.invalidateQueries({ queryKey: ["users"] });

이처럼 간단하게 캐시 데이터를 stale한 상태로 바꿔, 데이터가 바뀌었다면, 조건에 따라서 refetching이 수행되게 할 수 있습니다.

📌 2. 로직의 단순화

📚 Data Fetching

기존에 서버에서 데이터를 가져오기 위해서는 다음과 같은 절차가 필요했습니다.

1. Fetching을 위한 코드 작성
2. 데이터를 담아 둘 상태 생성
3. useEffect를 이용해 컴포넌트 Mount시 데이터를 Fetching 한 후에 상태 저장

이를 코드로 작성하면, 아래처럼 작성했었습니다.

// getData 함수는 서버에서 게시물을 반환하기 위한 비동기 함수를 나타냅니다.

function App() {
  const [state, setState] = useState([]);
  
  useEffect(() => {
    getData()
      .then((dataList) => setState(dataList))
      .catch((e) => setState([]));
  }, []);
  
  return <div>{JSON.stringify(state)}</div>;

하지만, React-query를 사용하면 다음과 같이 바꿀 수 있습니다.

function App() {
  const { data } = useQuery(["data"], getData);
  
  return <div>{data}</div>;

서버 데이터를 담을 상태(state)를 만들고, useEffect로 상태에 데이터를 담는 5줄이 넘는 코드를 useQuery를 이용해 단 한 줄로 처리할 수 있습니다. 미쳤다!

📚 동기적 실행

또, 특정 API를 호출하기 위해 다른 API의 값을 파라미터로 넣어줘야 할 때가 있습니다.

그럴 때는 API를 동기적으로 호출해줘야 합니다.

// API를 동기적으로 호출 예시
const [state1, setState1] = useState();
const [state2, setState2] = useState();

useEffect(() => {
  getData().then((dataList) => {
    setState1(dataList[0]);
  })
}, []);

// state1의 데이터를 파라미터로 넣어 호출하는 API
useEffect(() => {
  if(state1) {
    getAfterData(state1).then((dataList) => {
      setState2(dataList);
    })
  }
}, [state1]);

API 호출 위한 조건이 추가되어 동기적으로 관리가 필요하고, useEffect의 위치가 다른 코드들과 섞인다면 어떤 데이터가 언제, 어떻게 호출되는지 흐름과 시점을 파악하기 어렵습니다.

하지만, React-query의 enabled 옵션을 사용하면 보다 깔끔하고 간단하게 대체할 수 있습니다.

const { data: data1 } = useQuery(["data1"], getData);
const { data: data2 } = useQuery(["data2", data1], getData,
  { enabled: !!data1 }
));

enabled는 조건이 충족될 때만 API를 호출하게 되어 위와 같이 간단하게 API를 동기적으로 호출할 수 있습니다.

📌 3. 프로젝트의 규모

프로젝트의 규모가 커지고 관리해야 할 데이터가 많아지면, Client에서 관리하는 상태(데이터)와 Server에서 관리하는 상태(데이터)가 분리되야할 필요성을 느끼게 됩니다.

• 클라이언트 상태: 모달 관련 데이터, 페이지 관련 데이터 등등
• 서버 상태: 사용자 정보, 비즈니스 로직 관련 정보 등등

위에서 알아봤듯, 이렇게 클라이언트의 상태와 서버의 상태가 나뉘어질 수 있는데요.
실제 클라이언트 상태의 경우 Redux, Recoil와 같은 전역 상태 관리 라이브러리를 통해 잘 관리되어오고 있으나, 문제는 이러한 라이브러리들이 서버 상태까지도 관리를 해야 하는 상황이 발생한다는 것입니다.

이런 라이브러리 외에도 비동기 처리 로직이나, 서드 파티 라이브러리를 지원하는 것들이 많이 있지만, 클라이언트의 상태와 서버의 상태를 완벽하게 분리하여 관리에 용이하도록 충분한 기능을 지원하는 것은 어렵습니다.

즉, 이런 것들은 클라이언트의 상태를 관리하는데 로직이 집중되어 있기 때문에, 서버의 상태까지 효율적으로 관리하기에는 한계가 있습니다.

이때, React Query는 이런 문제에 대한 해결책을 제시할 수 있습니다.

// 클라이언트의 상태
const [toggle, setToggle] = usestate(false);

// 서버의 상태
const { data } = useQuery(["data"], getData);

이 예시에서는 컴포넌트 내부에서 위와 같은 로직을 통해 서버의 데이터를 가져오고 있는데, 이는 서버의 데이터를 불러오는 과정에서 구현해야할 추가적인 설정들을 진행할 필요가 없어졌음을 말해줍니다.

클라이언트의 상태는 상태 관리 라이브러리 혹은 state로 관리하고,
서버의 상태(데이터)는 React-query가 관리할 수 있습니다.

이를 통해 클라이언트 상태와 서버의 상태를 온전하게 분리할 수 있습니다.

▶️ 사용법 맛보기!

React query에서 data fetching을 위해 제공하는 대표적인 기능에 대해 알아보겠습니다.
기본적으로 GET에는 useQuery, PUT, UPDATE, DELETE에는 useMutation이 사용됩니다.

📌 useQuery

// 사용법
const { isLoading, error, data } = useQuery( {queryKey: [ ‘key’ ], queryFn: callback, options} );

useQuery()는 필수 인자로 queryKey, queryFn 을 받고, 선택적으로 options을 받습니다.

queryKey

• 쿼리의 고유 키
• React query 최신 버전 부터는 배열 표기법을 사용해서 키 지정

queryFn

• 훅 호출시 실행되는 Promise 반환하는 함수
• 해당 callback 함수에서 데이터 fetching

options 기본적으로 많이 사용하는 옵션들은

• enable 데이터 자동 패치 여부
• retry 데이터 재요청 여부 및 횟수
• staleTime 데이터가 fresh 상태로 유지되는 시간 (설정 시간이 지나면 stale)
• cacheTime inactive 상태인 캐시 데이터가 메모리에 남아있는 시간 (해당 시간이 초과되면 가비지 컬렉터에 의해 메모리에서 제거됨)
• refreshOnMount, refetchOnWindowFocus, refetchOnReconnet 쿼리가 stale 상태인 경우 refetch 실행 여부

options에는 정말 유용한 옵션들이 많으니 공식문서를 참고하면 좋을 것 같습니다.

// 사용 예시
const getUsers = () => fetch( 'https://jsonplaceholder.typicode.com/users')
                          .then( res  => res.json() )

const query = useQuery( { queryKey: [‘users’], queryFn: getUsers })

그리고 useQuery() 훅의 리턴값에는 쿼리의 상태 정보를 담고 있는 객체가 들어가는데요!

const { isLoading, isError, data, error, refetch, remove } = useQuery( { queryKey: [‘todos’], queryFn: getTodos });

대표적인 프로퍼티

• isLoading 쿼리가 현재 로딩 중인지 여부 (boolean)
• isError 쿼리 결과가 오류인지 여부 (boolean)
• data 쿼리를 통해 성공적으로 fetching된 데이터
• error 쿼리 실행 중 발생한 모든 에러
• refetch 쿼리 데이터를 수동으로 refetch 하는 트리거 메소드
• remove 캐시에서 특정 쿼리 제거하는 메소드

이 훅을 이용해서 쉽게 데이터를 fetching하고, 캐싱하고, 데이터를 가져오는 동안의 여러 상태도 편하게 관리할 수 있습니다.

📌 useMutation

// 사용법
const mutation = useMutation({ mutationFn: mutationFunction });

mutationFn

• 실행하고자 하는 함수를 반환하는 함수

// 사용 예시
const AddUser = useMutation({
  mutationFn: ( user ) => {

    return fetch('https://jsonplaceholder.typicode.com/users',{
      method:'post',
      headers: {
        "Content-Type": "application/json",
      },
      body:JSON.stringify( user )
    }).then( res =>  res.json() )
  })

그리고 useMutation() 훅의 리턴값에는 마찬가지로 실행 결과와 관련 정보를 담은 객체가 들어가는데요!

대표적인 프로퍼티

• isLoading 뮤테이션이 현재 로딩 중인지 여부 (boolean)
• isSuccess 뮤테이션 결과가 성공인지 여부 (boolean)
• isError 뮤테이션 결과가 오류인지 여부 (boolean)
• data 뮤테이션 실행 후 반환된 데이터 (있을 때만)
• mutate 해당 뮤테이션 실행을 위해 호출할 메소드. (인자에 담을 변수를 객체로 전달)
• reset 뮤테이션 초기 상태로 리셋하는 메소드
• onSuccess 뮤테이션 성공시 호출할 콜백함수
• onError 뮤테이션 실패시 호출할 콜백함수

▶️ 회고

이번 아티클을 통해서 모든 react-query의 유용한 옵션들과 다양한 기능들에 대해서 다룰 순 없어서 너무 아쉽지만, 아티클과 실습을 준비하며 여러 이점들을 알 수 있었습니다.

그리고 이번에 react-query를 처음 접하면서 제 개인적인 생각으로 다음 프로젝트에는 무조건 도입해야겠다는 생각이 들었습니다.

그 이유는 다음과 같습니다.

• 옵션 하나로 간편하게 캐싱 기능 및 이에 따른 API 호출 비용 감소
• 코드의 간소화
• 규격화된 방식으로 코드 작성 가능

등... 사용해야할 이유는 정말 많은 것 같습니다.

그리고, 캐싱에 대해서도 정말 많이 생각할 수 있었습니다.
캐싱이 필요한 여러가지 상황 가정을 통해서 정말 실시간이 중요한 게 아니라면, 어느정도까지 캐싱을 제공해야할지도 여러 궁금증이 생겼네요... ㅎ

두서없는 긴 글 읽어주셔서 감사합니다.

다 못다룬 정말 유용한 이점인 낙관적 업데이트에 대해서도 꼭 한 번 읽어보시길 바랍니다.

참고

• https://velog.io/@rookieand/Server-State%EB%8A%94-%EB%AD%90%EA%B3%A0-React-Query%EB%8A%94-%EC%99%9C-%EC%93%B0%EB%8A%94%EA%B0%80
• https://tanstack.com/query/latest/docs/framework/react/quick-start
• https://tech.kakaopay.com/post/react-query-1/
• https://lasbe.tistory.com/163
• https://velog.io/@sheecho0804/React-Query-asynchronous-Recoil%EB%A1%9C-%EC%83%81%ED%83%9C-%EA%B4%80%EB%A6%AC%ED%95%98%EA%B8%B0
• https://www.timegambit.com/blog/digging/react-query/03#user-content-fn-refetch
• https://velog.io/@malza_0408/react-query