💻 개발
Q. tanstack-query에서 stale time과 gc time의 차이점에 대해서 설명해주세요
본 포스트는 IT 기술면접 질문 메일링 서비스, 매일메일의 토픽에 대해 추가적으로 학습한 내용을 기록하고자 작성되었습니다. 기술면접 질문 및 답안&해설을 제공해주신 매일메일 서비스에 감사의 말씀 남깁니다.
서론
프론트엔드 개발을 할 때 서버 데이터를 관리하는 데 있어 성능과 편의성을 생각한다면 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하면 캐시에 데이터가 남아있다.

📚 일일 기술토크2 / 4