📡 02. 핵심 데이터 페칭: `useQuery` 완벽 가이드

📋 목차

• ☕️ 영철이의 고민: "스피너가 돌아가다 말다 하는데요?"
• 🤔 왜 알아야 하는가: 쿼리를 100% 통제하기 위해
• 1. Query Key: 배열 컨벤션과 의존성의 마법
  • 배열을 쓰는 진짜 이유: 의존성 배열
• 2. Promise를 캐싱하는 Query Function (queryFn)
• 3. 로딩 상태의 진실: status vs fetchStatus (v4+)
  • 결론: 스피너는 도대체 언제 띄워야 하나요?
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 데이터가 로딩 중일 때 스피너가 안 뜬다고요? status랑 fetchStatus의 차이를 아직 모르시는군요."

☕️ 영철이의 고민: "스피너가 돌아가다 말다 하는데요?"

(수요일 오전, 새로고침 버튼을 연타하며 한숨 쉬는 영철)

🐣 영철: 아... 미치겠네. 처음에 페이지 들어올 때는 "로딩 중..." 스피너가 잘 돌거든요? 근데 똑같은 페이지에 다시 들어올 때는 스피너가 0.1초 떴다가 훅 사라져서 화면이 퍽퍽 끊겨 보여요. 그리고 유저 리스트 가져오는 쿼리 키를 그냥 문자열 "users" 하나 띡 썼더니 영수 님이 백엔드 부하 심하다고 뭐라고 하시네요.

🦁 영호: 영철 님, Query Key를 문자열로만 관리하면 나중에 캐시 파편화나 엉뚱한 캐시 히트(Cache Hit)가 발생해요. 게다가 방금 말씀하신 '스피너 퍽퍽 현상'은 isLoading과 isFetching의 차이를 제대로 몰라서 발생하는 전형적인 안티 패턴입니다.

🐣 영철: 헉! isLoading이 그냥 fetch 돌 때 true 되는 거 아니에요? 두 개가 어떻게 다르죠?

🤔 왜 알아야 하는가: 쿼리를 100% 통제하기 위해

🦁 영호: useQuery는 단순히 "Promise 주면 데이터 줄게" 수준의 훅이 아닙니다. 이 앱 전체의 비동기 네트워크 스피너를 지휘하는 교통 순경이에요.

• Query Key: 이 데이터표(대장부)의 '이름표'이자, 그 데이터의 의존성 배열(Dependency Array) 역할을 동시에 수행합니다.
• 상태의 이원화: React Query v4(TanStack Query)부터는 데이터의 유무(status)와, 백그라운드 네트워크의 활동 유무(fetchStatus)를 완전히 분리했습니다. 이걸 구분하지 못하면 오프라인 상황이나 백그라운드 업데이트 상황에서 사용자에게 잘못된 피드백을 주게 됩니다.

이 기본적인 원리를 대충 넘어가면 나중에 무한 스크롤, 낙관적 업데이트를 할 때 캐시 관리에서 반드시 사고가 터집니다. 제대로 파헤쳐봅시다.

1. Query Key: 배열 컨벤션과 의존성의 마법

과거(v3 이전)에는 Query Key를 문자열 하나만 던질 수도 있었습니다. (예: useQuery('users', fetchUsers)). 하지만 지금은 무조건 배열(Array) 형태로만 선언해야 합니다. 왜 그럴까요?

// ❌ 영철이의 위험한 코드
const { data } = useQuery(['todos', state], () => fetchTodos(state));
 
// ✅ 영호 리드의 깔끔하고 확장 불가능한 코드
// 객체 안에 넣어서 순서 무관 & 확장성 확보
const { data } = useQuery({
  queryKey: ['todos', { status: state }],
  queryFn: () => fetchTodos(state)
});

배열을 쓰는 진짜 이유: 의존성 배열

useEffect의 두 번째 인자인 의존성 배열을 생각해보세요. React Query의 Query Key는 정확히 그 역할을 수행합니다. 배열 내부의 요소(예: state 변수)가 변경되면, React Query는 즉각적으로 "어? 키가 바뀌었네? 그럼 새로운 데이터를 가져와야지(Refetch)!" 라고 판단하여 새로운 네트워크 요청을 날립니다.

💡 심화 팁: Query Key 배열 내부의 아이템 순서는 중요할까요?

• 문자열 배열 요소의 순서는 무조건 일치해야 같은 캐시로 칩니다. (['todos', 'all'] 과 ['all', 'todos'] 는 완전 다른 캐시입니다.)
• 반면, 객체 내부의 키 순서 는 무관합니다. ([{ status: 'all', page: 1 }] 과 [{ page: 1, status: 'all' }] 은 동일한 캐시로 인식하여 낭비를 막아줍니다.)

2. Promise를 캐싱하는 Query Function (queryFn)

queryFn은 반드시 Promise를 반환하는 함수 여야 합니다.
대부분의 주니어 프론트엔드 개발자들이 여기서 겪는 오류는 "함수 자체를 던지지 않고, 함수 실행 결과를 던지는" 실수입니다.

// ❌ 영철이의 흔한 실수 1 (단일 실행 후 폭발)
useQuery({
  queryKey: ['user', 1],
  queryFn: fetchUser(1) // 💥 이건 함수가 아니라 '실행된 Promise 결과물'입니다! 렌더링마다 콜백 지옥 발생.
});
 
// ✅ 올바른 방식 (고차 함수 형태로 전달)
useQuery({
  queryKey: ['user', 1],
  queryFn: () => fetchUser(1) 
});

3. 로딩 상태의 진실: status vs fetchStatus (v4+)

가장 중요합니다. 영철이가 겪었던 "스피너가 돌다 말다 한다"는 문제는 여기서 기인합니다.

TanStack Query는 상태를 두 가지 축 으로 나누어서 봅니다.

1. status (데이터가 있는가?)
   • pending (이전에는 loading): 내 캐시에 보여줄 데이터가 단 1바이트도 없다! 최초 하드 로딩.
   • error: 데이터를 가져오다 에러 났다.
   • success: 내 캐시에 성공적인 데이터가 들어있다.
2. fetchStatus (네트워크가 돌고 있는가?)
   • fetching: 백그라운드든, 포그라운드든 현재 fetch 함수가 뺑뺑이 도는 중이다.
   • paused: 네트워크가 끊겼다(오프라인).
   • idle: 지금 아무것도 안 들고 조용히 쉬는 중이다.

결론: 스피너는 도대체 언제 띄워야 하나요?

만약 영철이가 isLoading(즉, status === 'pending')일 때만 전체 화면 스피너를 띄운다면 다음과 같은 일이 일어납니다:

• 첫 진입 (캐시 없음): 데이터가 없으므로 isLoading은 true. 스피너 빙글빙글. (정상)
• 두 번째 진입 (캐시 있음): 데이터를 이미 갖고 있어서 바로 보여주므로 isLoading은 false입니다. 하지만 백그라운드에서 최신 데이터를 확인 중(isFetching)이죠.
• 이 경우 스피너가 안 뜹니다. 그래서 유저 눈에는 번개처럼 이전 데이터가 보였다가(캐시 히트), 백그라운드 페칭이 끝나는 순간 0.5초 뒤에 스르륵 최신 데이터로 변경되는 마법을 보게 됩니다.

const { data, isLoading, isFetching } = useQuery({ ... });
 
// 🟡 하드 로딩 스피너 (화면 전체 덮기): 내 손에 보여줄 데이터가 아예 없을 때만!
if (isLoading) return <FullPageSkeleton />;
 
// 🔵 소프트 로딩 스피너 (상단 구석 쪼그맣게): 손에 데이터는 있는데, 뒷단에서 갱신 중일 때!
return (
  <div>
    {isFetching && <SmallSpinner />} {/* 화면 상단 귀퉁이에 살짝 */}
    <ul>{data.map(item => <Item key={item.id} />)}</ul>
  </div>
);

영철아, 이제 스피너 어떻게 띄워야 되는지 알겠지? 무조건 덮는 게 능사가 아니다!

🐣 영철이의 퇴근 일기

아... isLoading 하나로 전체 화면을 다 덮어버리니까 무한 리렌더링이나 화면 번쩍임이 생겼던 거구나. 데이터가 이미 있는데 왜 화면 전체를 로딩으로 덮냐는 영숙(UX 디자인) 님의 잔소리가 이제야 이해됐다.

💡 오늘의 교훈: "isLoading(데이터 없음)과 isFetching(네트워크 도는 중)을 구분하라. 초기 진입은 뼈대(Skeleton)로, 재방문 시에는 상단 쬐만한 스피너로 우아하게 UX를 설계하자!"

내일 출근하자마자 isLoading 하나만 쓰던 컴포넌트들 싹 다 찾아서 백그라운드 스피너용 컴포넌트 조각으로 분리해봐야지. 오늘은 그래도 덜 혼났다. 넷플릭스 봅슬레이 다큐 보면서 맥주나 한 캔 해야지! 🍺

📝 배운 내용 점검하기 (Quiz)

Q. 다음과 같이 카테고리별 뉴스를 조회하는 코드가 있습니다. 사용자가 '정치' 탭에서 '경제' 탭으로 이동할 때, 코드가 최신 '경제' 데이터를 자동으로 다시 가져오게(Refetching) 하려면 어떻게 설계해야 할까요?

// 문제 상황
const [category, setCategory] = useState('politics');
const { data } = useQuery({
  queryKey: ['news'],
  queryFn: () => fetchNews(category)
});

✅ 정답: Query Key 배열 안에 category 변수를 추가하여 의존성 배열처럼 만들어야 합니다.

const { data } = useQuery({
  queryKey: ['news', category], // 이 부분!
  queryFn: () => fetchNews(category)
});

💡 상세 해설:

• 원리 설명: React Query는 queryFn 내부의 의존성이 바뀌었는지 알 수 있는 마법이 없습니다. 오직 queryKey 배열에 어떤 요소들이 들어있는지만 감시합니다. category 상태값이 바뀔 때 쿼리가 다시 실행되도록 만들려면 무조건 그것을 queryKey 배열 요소로 넣어주어야 합니다. 이것이 바로 React Query를 이용한 상태 동기화의 기본입니다.
• 오답 피드백: "영철 님, queryFn 안에 category 변수를 아무리 넣어놔도, queryKey 배열 이름표가 그대로 ['news'] 하나뿐이라면 리액트 쿼리는 '어? 키가 똑같네? 방금 정치 뉴스 캐시해 둔 거 그대로 던져줄게~' 하고 넘어가 버려요. 정치 누르고 경제 눌렀는데 화면에 계속 정치면만 보일 겁니다!"
• 📌 핵심 기억법: 쿼리 펑션 안에서 사용하는 모든 변수(매개변수)는 쿼리 키 배열의 인질로 함께 묶어라!