2026-03-02

TanStack Query (React Query)

TanStack Query란?

서버 상태(Server State)를 효율적으로 관리하기 위한 라이브러리

• TanStack Query는 클라이언트 상태 관리 라이브러리가 아님
  • 클라이언트 상태: 프론트엔드 내부에서만 관리되는 상태 (동기적) → Redux, Zustand, Context 등이 관리
  • 서버 상태: 서버에 존재하고, API를 통해 가져오는 데이터 (비동기) → TanStack Query: 서버에서 받아오는 데이터를 관리하는 도구

왜 필요한가?

기존 방식:

useEffect(() => {
  fetchData().then(setData);
}, []);

문제점:

• 로딩 상태 관리 필요
• 에러 상태 관리 필요
• 캐싱 없음
• 재요청 관리 복잡
• 중복 요청 가능
• 새로고침 시 데이터 사라짐

⇒ TanStack Query로 해결

핵심 개념

• 서버 상태(Server State)
  • 서버에 존재하는 데이터
  • 비동기
  • 여러 곳에서 공유됨
  • 최신 상태 유지 필요
• useQuery 데이터 조회용

  const { data, isLoading, error } = useQuery({
    queryKey: ["users"],
    queryFn: fetchUsers,
  });
  

• useMutation 데이터 변경용 (POST, PUT, DELETE)

  const mutation = useMutation({
    mutationFn: addUser,
  });
  

• queryKey
  • 캐시를 구분하는 키
  • 배열 형태 권장
  • 데이터 동기화 핵심

주요 기능

• 자동 캐싱
  • 동일 queryKey는 캐시 사용
  • 중복 요청 방지
• 자동 재요청
  • 윈도우 포커스 시 재요청
  • 네트워크 복구 시 재요청
• staleTime
  • 데이터를 “신선한(fresh)” 상태로 유지하는 시간
  • 이 시간 동안은 재요청 안 함

  useQuery({
    queryKey: ["users"],
    queryFn: fetchUsers,
    staleTime: 1000 * 60
    gcTime: 60000
  });
  

  • staleTime 동안은 fresh 상태
  • staleTime이 지난 후 stale (오래된 상태)로 간주
  • stale = 오래되었지만 여전히 캐시에 존재 (특정 트리거 발생시 재요청 대상이 되는 상태)
• gcTime (구 cacheTime)
  • 해당 쿼리를 사용하는 곳이 없게 된 이후에도 캐시 데이터를 얼마 동안 유지할지를 정하는 시간
  • Active 상태(컴포넌트가 해당 query를 사용 중)와 Inactive 상태(컴포넌트가 언마운트되어 더 이상 사용하지 않음) 존재
  • gcTime은 Inactive가 됐을때 바로 삭제하지 않고 캐시에 남겨두는 시간
• staleTime과 gcTime 차이 | 구분 | staleTime | gcTime | | —— | ————————————– | ——————————— | | 의미 | 데이터가 “신선한 상태”로 유지되는 시간 | 캐시가 완전히 제거되기까지의 시간 | | 기준 | 재요청 여부 | 메모리에서 삭제 여부 | | 기본값 | 0 | 5분 |
• invalidateQueries
  • 데이터 변경 후 다시 불러오기
  • 특정 query를 “stale 상태로 만들어서” 다시 데이터를 가져오도록 하는 함수

    queryClient.invalidateQueries(["users"]);
    

• 낙관적 업데이트 (Optimistic Update)
  • 서버 응답 이전에 UI를 미리 업데이트하는 방법
  • UX 개선
  • 예시 ) 좋아요 기능
    • 사용자가 좋아요 버튼을 클릭
    • 서버 응답 기다리지 않고, UI상 바로 좋아요 상태 보여줌
  • 서버 오류 발생 고려해 오류 핸들링(롤백) 로직을 같이 설계해야 함

React Query vs Redux 차이

장점

• 서버 상태 관리 간소화
• 캐싱 자동 → 효율적인 캐싱 처리 기능 제공
• 로딩/에러 상태 관리 단순화
• 성능 최적화 → 비동기 데이터 관리 복잡성 줄어듬

단점

• 캐싱 전략 관리의 복잡성 → 잘못 쓰면 stale 문제 발생
• 초기 학습 곡선 존재 → 개념 이해 필요
• 클라이언트 상태와 서버 상태 간 의존 관계가 부족할 경우 TanStack Query만으로 해결 어려움 → 클라이언트 상태 관리용은 아님

참고자료

• https://bbjbc.github.io/tanstack-query/react/sixty-seventh-posting/
• https://velog.io/@uchan0/Tanstack-Query-%EC%82%AC%EC%9A%A9%EB%B2%95-%EC%A0%95%EB%A6%AC
• https://o-yeon.tistory.com/227
• https://velog.io/@kandy1002/React-Query-%ED%91%B9-%EC%B0%8D%EC%96%B4%EB%A8%B9%EA%B8%B0
• https://kyounghwan01.github.io/blog/React/react-query/basic/#react-suspense%E1%84%8B%E1%85%AA-react-query-%E1%84%89%E1%85%A1%E1%84%8B%E1%85%AD%E1%86%BC%E1%84%92%E1%85%A1%E1%84%80%E1%85%B5