amaranth.log
💻 개발

Q. tanstack-query에서 stale time과 gc time의 차이점에 대해서 설명해주세요

본 포스트는 IT 기술면접 질문 메일링 서비스, 매일메일의 토픽에 대해 추가적으로 학습한 내용을 기록하고자 작성되었습니다. 기술면접 질문 및 답안&해설을 제공해주신 매일메일 서비스에 감사의 말씀 남깁니다.
매일메일 - tanstack-query에서 stale time과 gc time의 차이점에 대해서 설명해주세요
tanstack-query에서 `staleTime`과 `gcTime`은 데이터를 캐싱하고 관리하는 데 중요한 두 가지 설정 값입니다. 먼저 요약해서 말씀 드려보자면, `staleTime`은 **데이터가 얼마나 오래 '신선한 상태'로 유지되는지**를 정하는 시간이고, `gcTime`은 **해당 쿼리를 사용하는 곳이 없게 된 이후에도 캐시 데이터를 얼마 동안 유지할지**를 정하는 시간입니다. 먼저, `staleTime`은 데이터를 처음 가져온 후에 그 **데이터를 '신선한' 상태로 간주하는 시간**을 말합니다. `staleTime` 내에는 같은 쿼리에 대한 새로운 네트워크 요청이 일어나지 않고, 캐시 데이터를 그대로 사용하게 됩니다. 예를 들어, `staleTime`을 5분으로 설정하면, 데이터를 가져오고 나서 5분 동안은 이 데이터가 '신선하다'고 판단해서 refetch가 트리거되더라도 추가 네트워크 요청 없이 캐시 데이터를 계속 사용합니다. 그리고 `staleTime`이 지난 후 refetch가 트리거된다면 새로운 요청을 보내 데이터를 갱신하게 됩니다. `staleTime`의 기본값은 0입니다. 반면에 `gcTime`은 **해당 쿼리가 더 이상 사용되지 않을 때, 캐시 데이터가 메모리에 얼마나 더 남아 있을지를 정하는 시간**입니다. `staleTime`이 지나면 데이터는 '오래된' 상태가 되지만, 여전히 캐시된 데이터는 사용이 가능합니다. 이 캐시 데이터는 새로운 요청을 보내 신선한 데이터를 받아오기 이전에 임시로 기존 데이터를 표시하는 데 활용됩니다. 다만, 해당 쿼리가 사용되지 않게 된 시점으로부터 `gcTime`으로 설정된 시간이 지나면 캐시에서 데이터가 삭제됩니다. 예를 들어, `gcTime`을 10분으로 설정하면, 해당 쿼리를 사용하는 컴포넌트가 모두 언마운트된 시점으로부터 10분 후에 캐시에서 데이터가 삭제됩니다. tanstack-query에서 설정한 기본 `gcTime`은 5분입니다. 정리해서 말씀드려보자면, `staleTime`은 **데이터를 처음 가져온 후 얼마 동안 네트워크 요청 없이 캐시된 데이터를 사용할지**를 정하는 시간이고, `gcTime`은 해당 **쿼리가 사용되지 않게 된 후에도 캐시에 유지될** 시간을 정하는 겁니다. 이렇게 각각의 설정을 통해 데이터를 더 효율적으로 관리하고, 불필요한 네트워크 요청을 줄이면서도 최신 데이터를 가져올 수 있도록 합니다. ## 📚 추가 학습 자료를 공유합니다. - [[tanstack-query 공식문서] caching example](https://tanstack.com/query/v5/docs/framework/react/guides/caching) - [[tanstack-query 공식문서] staleTime property](https://tanstack.com/router/latest/docs/framework/react/api/router/RouteOptionsType#staletime-property)
 

서론

프론트엔드 개발을 할 때 서버 데이터를 관리하는 데 있어 성능과 편의성을 생각한다면 tanstack-query(구 react-query)는 가히 필수적이다. 예전에 tanstack-query를 공부하면서 분명 stale time, gc time을 비롯한 속성에 대해서도 정리를 했었는데, 기술 공부가 그렇듯 자주 보고 사용하지 않으면 금새 잊어버린다…이번에도 역시나 잊어버려서 캐시에 저장되는 시간…?정도로만 답할 수 있었다.

정답

staleTime: 데이터가 얼마나 오래 신선한 상태로 유지되는지 정하는 시간

tanstack-query에서 서버 데이터(api로 불러온 데이터)를 처음 불러오면, 그 데이터는 ‘신선한’ 상태로 캐시에 저장된다.
캐시 내 데이터가 ‘신선한’ 상태인 동안은 refetch가 트리거되더라도 새로 네트워크 요청을 하지 않고, 캐시에 저장된 데이터를 그대로 사용한다.
*여기서 주의할 점은, refetch()를 수동으로 호출하는 경우엔 캐시 데이터 상태와 상관없이 새로 네트워크 요청을 한다.(v5 기준) 여기서는 윈도우 포커스, 재마운트와 같은 자동 refetch를 상정한다.
그리고 일정 시간(기본 값 = 0초) 후 데이터는 ‘오래된’ 상태가 되고, 이 시점에서 refetch가 트리거되면 새로 네트워크 요청을 하고 캐시 데이터를 갱신하게 된다. 여기서의 일정 시간이 바로 staleTime이다.
 
여기서 후술할 cache time과 비교 시 유의할 점은, stale time이 만료되어도 캐시에는 여전히 데이터가 남아있다는 것이다. 캐시된 데이터의 상태가 변하는 것이지 데이터가 사라지는 것은 아니다.
즉, 원한다면 오래된 데이터라도 캐시에 남아있는 데이터에 접근해 사용하는 것이 가능하다.

gcTime: 해당 쿼리를 사용하는 곳이 없게 된 이후에도 캐시 데이터를 얼마 동안 유지할지를 정하는 시간

‘쿼리를 사용하는 곳이 없게 된 후’⇒가 무슨 뜻이냐면… 말 그대로 해당 쿼리를 사용하는 컴포넌트들이 모두 언마운트되어서 더 이상 해당 쿼리를 사용하는 컴포넌트가 없을 때를 의미한다.
캐시에 저장된 모든 서버 데이터를 삭제하지 않고 영.원.히. 저장하게 된다면… 많은 리소스를 불필요하게 소모하게 될 것이다.
그래서 tanstack-query는 효율적인 캐시 관리를 위해, 해당 쿼리를 사용하는 곳이 없게 된 시점에서 일정 시간(기본 값 = 5분)이 지나면 캐시에 저장된 데이터를 삭제한다. 여기서의 일정 시간이 바로 gcTime이다.

실습해보기

import { Typography } from "@mui/material"; import { QueryClient, QueryClientProvider, useQuery, useQueryClient, } from "@tanstack/react-query"; import { useEffect, useRef, useState } from "react"; // QueryClient 설정 - 자동 refetch 활성화 const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 5000, // 3초 동안 데이터 '신선' gcTime: 5000, // 5초 동안 캐시에 유지 refetchOnWindowFocus: true, }, }, }); async function fetchData() { const res = await fetch("https://jsonplaceholder.typicode.com/todos/1"); return await res.json(); } function DataComponent() { const staleTime = 5000; const queryClient = useQueryClient(); const lastFetchTimeRef = useRef<number | null>(null); const [tick, setTick] = useState(0); // 0.1초 단위 리렌더링용 const [logs, setLogs] = useState<string[]>([]); const { data, isFetching } = useQuery({ queryKey: ["demo"], queryFn: async () => { const now = new Date().toLocaleTimeString(); setLogs((prev) => [`[${now}] API 호출 발생`, ...prev]); const result = await fetchData(); lastFetchTimeRef.current = Date.now(); return result; }, staleTime: 5000, // 5초 동안 데이터 '신선' gcTime: 5000, // 5초 동안 캐시에 유지 refetchOnWindowFocus: true, }); useEffect(() => { // 포커스 이벤트 시 stale 상태라도 캐시만 사용된 경우 로그 표시 const handleFocus = () => { const query = queryClient.getQueryState(["demo"]); if (!query) return; const now = new Date().toLocaleTimeString(); // fetchStatus === 'idle'이면 API 호출 없이 캐시 사용 if (query.fetchStatus === "idle") { setLogs((prev) => [ `[${now}] window focus → 캐시 데이터만 사용됨`, ...prev, ]); } }; window.addEventListener("focus", handleFocus); return () => window.removeEventListener("focus", handleFocus); }, [queryClient]); useEffect(() => { const cached = queryClient.getQueryData(["demo"]); const nowStr = new Date().toLocaleTimeString(); if (cached) { setLogs((prev) => [`[${nowStr}] 마운트됨 → 캐시에 데이터 있음`, ...prev]); } else { setLogs((prev) => [`[${nowStr}] 마운트됨 → 캐시에 데이터 없음`, ...prev]); } }, [queryClient]); // 0.1초마다 리렌더링 → 타이머 UI 업데이트 useEffect(() => { const timer = setInterval(() => setTick((t) => t + 1), 100); return () => clearInterval(timer); }, []); // staleTime 남은 시간 계산 const now = Date.now(); const lastFetchTime = lastFetchTimeRef.current ?? now; const staleLeft = Math.max(0, staleTime - (now - lastFetchTime)); return ( <div style={{ border: "1px solid gray", padding: "1rem", margin: "1rem", display: "flex", }} > <div style={{ marginRight: "1rem" }}> <div style={{ marginTop: "1rem", color: "#555" }}> <p>staleTime 남음: {(staleLeft / 1000).toFixed(1)}초</p> <Typography component="div"> 현재 캐시 상태:{" "} {staleLeft > 0 ? ( <span style={{ color: "green" }}>신선 (fresh)</span> ) : ( <span style={{ color: "red" }}>오래됨 (stale)</span> )} </Typography> </div> <h3>서버 데이터</h3> {isFetching && <p>로딩 중...</p>} {data && <pre>{JSON.stringify(data, null, 2)}</pre>} </div> <div> <h4>실행 로그</h4> <ul> {logs.map((log, idx) => ( <li key={idx}>{log}</li> ))} </ul> </div> </div> ); } function App() { const [visible, setVisible] = useState(true); const [unmountTime, setUnmountTime] = useState<number | null>(null); const gcTime = 5000; // ms // 0.1초마다 리렌더링 → gcTime 카운트다운용 const [tick, setTick] = useState(0); useEffect(() => { const timer = setInterval(() => setTick((t) => t + 1), 100); return () => clearInterval(timer); }, []); const gcLeft = unmountTime ? Math.max(0, gcTime - (Date.now() - unmountTime)) : null; return ( <QueryClientProvider client={queryClient}> <div style={{ padding: "1rem" }}> <h1>staleTime / gcTime 자동 refetch 실험 (v5)</h1> <button onClick={() => { if (visible) { setUnmountTime(Date.now()); // 언마운트 시작 시각 기록 } else { setUnmountTime(null); } setVisible(!visible); }} > {visible ? "컴포넌트 언마운트" : "컴포넌트 마운트"} </button> {visible && <DataComponent />} {!visible && ( <div style={{ marginTop: "1rem", color: "#555" }}> <p> 컴포넌트 언마운트됨 → 캐시 삭제까지 남은 시간:{" "} {gcLeft !== null ? (gcLeft / 1000).toFixed(1) : "0"}초 </p> </div> )} </div> </QueryClientProvider> ); } export default App;
탭 전환을 통해 자동 refetch를 유도했다. 보시다시피, staleTime이 끝난 후 refetch하면 api를 새로 호출하고, staleTime이 끝나기 전에 refetch하는 경우 api를 새로 호출하지 않고 기존 캐시 데이터를 사용한다.
그리고 언마운트 후 gcTime이 끝난 후 refetch하면 캐시에 데이터가 남아있지 않고(그래서 api를 호출해 데이터를 새로 불러오고), gcTime이 끝나기 전에 다시 refetch하면 캐시에 데이터가 남아있다.
notion image
📚 일일 기술토크2 / 4
  1. 1편Q. 리액트에서 변수 관리 시 useRef를 사용하는 것은 let을 사용하는 것과 어떤 차이가 있나요?2025년 8월 17일
  2. 2편Q. tanstack-query에서 stale time과 gc time의 차이점에 대해서 설명해주세요2025년 8월 29일
  3. 3편useEffect와 useLayoutEffect의 차이점에 대해서 설명해주세요2025년 9월 14일
  4. 4편Q. 왜 기본 img 태그 대신 next/Image를 사용하셨나요?2025년 10월 31일