React-Query useQuery와 useMutation

이아름·2025년 10월 12일

이번 프로젝트에서 react, typescript를 사용하는데
react하면 중요하게 여겨지는 라이브러리가 react-query라는 이야기를 들었다.(실제로 이번 프로젝트에서도 사용한다.)

react-query의 핵심 함수 useQuery, useMutation에 대해 알아보려고 한다.

React-query가 무엇인가?

react-query란 "React 애플리케이션에서 서버 상태(Server State)를 효율적으로 관리하기 위한 라이브러리"이다.

서버 상태(Server State)란?

서버로 부터 가져온 데이터 <-> 클라이언트 상태(useState, useReducer 등)

서버에서 가져온 데이터를 관리하는 API 응답 데이터

react-query는 서버 상태(Server State)를 캐싱하고, 자동으로 갱신하며, 상태를 추적한다.
React Component 내부에서 간단하고 직관적으로 API를 사용할 수 있어서 많이 사용한다.
또한 서버 데이터와 클라이언트 데이터(화면 데이터)를 분리해서 관리한다는 점에서 이점이 있다.

추가적인 이점이라면 무한 스크롤 구현이 쉽다는 장점도 있다.
react-query는 getPreviousPageParam, fetchPreviousPage, hasPreviousPage 등 페이지 관련 기능들이 존재해 페이지 관리가 편하다.

UseQuery란?

react-query의 조회용 훅으로
서버에서 데이터를 조회하는 역할을 한다.
주로 GET 요청에 사용하고 조회한 결과를 자동으로 캐싱, 갱신, 중복 요청을 방지한다.

Hook이란?

React에서 상태나 생명주기(lifecycle)에 접근하기 위해 사용하는 특별한 함수

ex) useState -> 컴포넌트 상태 관리
useEffect, useRef 등

queryKey : 쿼리를 구분하는 고유한 값
배열 형태로 지정한다.
queryFn : 실제 데이터 요청 함수
data와 error 객체를 반환한다.
staleTime : 캐시가 신선한(fresh) 상태로 유지되는 시간
기본값은 0이다.
enabled : false일 경우 자동 실행하지 않음

useQuery 동작원리

컴포넌트가 렌더링될 때 자동으로 useQuery가 실행된다.

    queryKey: ["user", userId],

이때 queryKey를 기준으로 캐시되어 있는 데이터가 있는지 확인한다.

1-1. 캐시된 데이터가 있으면 데이터의 상태를 확인하고 사용한다.

1-2. 캐시된 데이터가 없으면 queryFn을 실행한다.

    queryFn: async () => {
      const res = await axios.get(`/api/users/${userId}`);
      return res.data;
    },

queryFn 성공시 데이터를 캐시에 저장하고 UI를 업데이트 한다.
네트워크 상태, focus 이벤트(탭 전환). refetch 조건에 따라 자동으로 재요청할 수 있다.

데이터의 신선도

react-query는 캐시한 데이터의 상태를 fresh(신선), stale(상함)의 상태로 관리한다.

데이터가 fresh 하다면 캐시하고 데이터가 stale하다면 새로운 데이터를 가져온다.

이 stale까지 걸리는 시간을 staleTime 옵션으로 지정할 수 있고
stale의 여부를 isStale로 확인 할 수 있다.