📡 07. 커스텀 훅(Custom Hooks)으로 Query 추상화하기

📋 목차

• ☕️ 영철이의 고민: "코드가 너무 길고 뚱뚱해요!"
• 🤔 왜 알아야 하는가: 비즈니스 로직의 격리
• 1. 커스텀 훅 추상화의 3단계 설계
  • ❌ 단계 0: 뚱뚱한 컴포넌트 (Before)
  • ✅ 단계 1: 훅으로 분리 (After)
• 2. 진화의 끝: queryOptions API (v5의 비기)
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 똑같은 useQuery 설정을 컴포넌트 5군데에 다 복붙해 놓으셨네요. 나중에 API 주소 바뀌면 5군데 다 찾아서 고치실 건가요?"

☕️ 영철이의 고민: "코드가 너무 길고 뚱뚱해요!"

(수요일 오후, 코드를 스크롤하다 손가락에 쥐가 난 영철)

🐣 영철: 아 리드 님... 저희 커뮤니티 앱 여기저기서 '인기 게시글' 목록을 띄워야 하거든요? 그래서 메인 페이지, 마이 페이지, 검색 페이지마다 useQuery 써서 쿼리 키 넣고, queryFn 넣고, staleTime 5분으로 맞추고... 똑같은 코드를 계속 치다 보니까 파일 하나당 코드가 막 200줄씩 넘어가요 ㅠㅠ

🦁 영호: 영철 님, UI를 그리는 컴포넌트(View) 안에 데이터 파이프라인(Logic)을 생으로 때려 박으니까 뚱뚱해지는 겁니다. React Query의 모든 호출은 무조건 커스텀 훅(Custom Hooks) 으로 추상화해서 빼내는 것이 5년 차 실무의 국룰입니다. 게다가 TypeScript 타입 추론까지 얹으면 완벽해지죠.

🤔 왜 알아야 하는가: 비즈니스 로직의 격리

만약 컴포넌트 안에서 원시적인 useQuery를 그대로 쓰면 다음과 같은 치명적인 단점이 생깁니다.

1. 중복의 저주: 쿼리 키 문자열 오타, staleTime 설정 누락 등 여기저기서 휴먼 에러가 터집니다.
2. 타입의 늪: 서버에서 내려오는 Response 타입을 컴포넌트마다 매번 제네릭(<T>)으로 달아줘야 합니다.
3. 가독성 파괴: UI 렌더링 코드보다 비동기 상태 뽑아내는 코드가 더 길어집니다.

이를 해결하기 위해, 우리는 쿼리 호출부를 useTodos, useUser 같은 커스텀 훅으로 예쁘게 포장하여 컴포넌트가 "어떻게(How) 가져오는지 알 필요 없이, 무엇(What)만 쓰도록" 완벽히 격리해야 합니다.

1. 커스텀 훅 추상화의 3단계 설계

가장 기본적인 커스텀 훅 분리 방식을 TypeScript 규격에 맞춰 살펴봅시다.

❌ 단계 0: 뚱뚱한 컴포넌트 (Before)

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';
 
// 컴포넌트가 너무 많은 걸 알고 있다!
function Dashboard() {
  const { data, isLoading } = useQuery<Todo[], Error>({
    queryKey: ['todos', 'done'],
    queryFn: async () => {
      const res = await axios.get('/todos?status=done');
      return res.data;
    },
    staleTime: 5 * 60 * 1000, // 5분
  });
 
  return <div>...</div>;
}

✅ 단계 1: 훅으로 분리 (After)

새로운 파일 hooks/queries/useTodos.ts 를 만들고 로직을 몽땅 몰아넣습니다. 컴포넌트는 오직 이 훅만 호출하면 됩니다.

// 📝 hooks/queries/useTodos.ts
import { useQuery } from '@tanstack/react-query';
import axios from 'axios';
 
// 1. DTO 타입 선언 (이 파일 안에서만 응집도 높게 관리)
export type Todo = { id: number; title: string; status: 'open' | 'done' };
 
// 2. 순수 페칭 함수 (추후 테스팅이나 서버 사이드에서 재사용 용이)
const fetchTodos = async (status: string): Promise<Todo[]> => {
  const { data } = await axios.get(`/todos?status=${status}`);
  return data;
};
 
// 3. ✨ 드디어 커스텀 훅 (타입 추론이 완벽하게 흘러감)
export const useTodos = (status: string) => {
  return useQuery({
    queryKey: ['todos', status],
    queryFn: () => fetchTodos(status),
    staleTime: 5 * 60 * 1000,
  });
};

// 🎨 View 컴포넌트는 극도로 가벼워진다!
import { useTodos } from '@/hooks/queries/useTodos';
 
function Dashboard() {
  // Query Key가 뭔지, staleTime이 얼만지 컴포넌트는 모른다. 그저 꺼내 쓸 뿐!
  const { data: todos, isLoading } = useTodos('done');
  
  return <div>...</div>;
}

2. 진화의 끝: queryOptions API (v5의 비기)

🐣 영철: 오, 코드가 진짜 반토막 났네요! 근데 리드 님, 서버 사이드 렌더링(SSR)이나 프리페칭(Prefetching) 할 때 서버 코드에서 useQuery 훅을 몬 쓸 텐데, 그럼 그땐 쿼리 키(['todos', status])를 또 생으로 문자열 쳐야 하는 거 아닌가요?

🦁 영호: 핵심을 찔렀군요! 훅 내부로 키를 완전히 숨겨버리면 컴포넌트 밖(루터 충돌, SSR 프리페칭, QueryCache 직접 제어)에서 그 키에 접근하기 힘들어집니다. 이를 완벽하게 해결하기 위해 React Query v5에서 출시된 queryOptions 라는 함수를 써야 합니다.

queryOptions는 실행하지 않고 '옵션 덩어리(객체)' 만 만들어주는 팩토리 함수 입니다.

// 📝 queries/todoOptions.ts
import { queryOptions } from '@tanstack/react-query';
 
// 🚀 Option 팩토리 생성 (타입스크립트 완전 지원)
export const todoOptions = {
  all: () => queryOptions({
    queryKey: ['todos'],
    queryFn: () => axios.get('/todos').then(res => res.data as Todo[]),
  }),
  detail: (status: string) => queryOptions({
    queryKey: ['todos', status],
    queryFn: () => axios.get(`/todos?status=${status}`).then(res => res.data as Todo[]),
    staleTime: 5 * 60 * 1000,
  }),
};

이 옵션 객체가 있으면 클라이언트 훅 이든, 서버 라우터 든 언제 어디서나 레고 블록처럼 끼워 쓸 수 있습니다!

// 1️⃣ 일반 컴포넌트(Client)에서 쓸 때
function Dashboard() {
  // Option 객체를 그대로 useQuery에 전개해서 집어넣음
  const { data } = useQuery(todoOptions.detail('done'));
}
 
// 2️⃣ 로더(SSR API)나 서버 액션에서 프리페칭 할 때
async function prefetchDashboard() {
  const queryClient = new QueryClient();
  // 동일한 옵션 객체 재사용! 키 오타가 날 확률 0%
  await queryClient.prefetchQuery(todoOptions.detail('done'));
}

🐣 영철이의 퇴근 일기

와... 나 오늘 useTodos 파일 하나 만들어놓고 queryOptions 안에서 깔아둔 다음, 마이페이지랑 대시보드에서 useQuery(todoOptions.xxx()) 로 쫙 갈아끼웠다.
코드 수백 줄이 그냥 증발하는 마술;;

💡 오늘의 교훈: "UI 파일 안에서 직접 useQuery 패턴을 무방비하게 복붙하는 건 안티패턴이다. 쿼리 키와 페칭 로직은 커스텀 훅이나 queryOptions 객체로 완벽히 격리해서, 컴포넌트가 '데이터 줘'라고 소리만 치게 만들자!"

그리고 TypeScript 썼을 때 제일 좋은 점! todoOptions.detail(123) 치니까 빨간 줄 뜨면서 상태(status)는 문자열이야, 바보야! 라고 화내주더라. 휴... TS 안 썼으면 백엔드한테 숫자 123 넘겼다가 400 에러 뜨고 어리둥절할 뻔. 오늘 퇴근길 발걸음 개가볍다 흫ㅎ.

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

Q. 기존에는 데이터 변환 작업을 컴포넌트 안에서 data.filter(...)나 data.map(...)으로 처리했습니다. 커스텀 훅을 분리한 이후, 원본 DB 데이터를 프론트엔드 UI 입맛에 맞게 가공(Transformation)하고 싶을 때 가장 권장되는 React Query의 내장 옵션은 무엇입니까?

• A) queryFn 안에서 axios로 받아온 직후에 filter를 돌린다.
• B) 커스텀 훅 내부에서 useQuery 설정 중 select 옵션을 사용하여 가공한다.
• C) 커스텀 훅에서 반환한 data를, 사용할 UI 컴포넌트에서 useMemo로 다시 감싼다.

✅ 정답: B

💡 상세 해설:

• 원리 설명: TkDodo 아티클 #2에 따르면, React Query의 select 옵션은 "원본 데이터(캐시)는 훼손하지 않고 냅둔 채, 특정 컴포넌트를 구독할 때만 내가 원하는 조각으로 잘라내어(Memozation) 던져주는" 최강의 데이터 변환 도구입니다. select 옵션은 내부적으로 결과값을 캐싱하므로 불필요한 연산 낭비를 완벽히 차단합니다.
• 오답 피드백: "영철 님, A번처럼 queryFn 안에서 데이터를 갈아버리면 어떻게 될까요? 다른 페이지에서 원본 전체 목록을 달라고 했을 때 캐시통엔 이미 난도질당한 조각밖에 안 남아있게 됩니다! C번처럼 매번 뷰 컴포넌트가 짊어지게 하지 말고, 깔끔하게 useQuery의 select에게 위임하세요."
• 📌 핵심 기억법: 원본 훼손 없는 우아한 데이터 가공은 무조건 select 옵션!