📡 02. [아키텍처] 효과적인 Query Key 설계 워크샵

📋 목차

• ☕️ 영철이의 고민: "무효화를 날렸는데 엉뚱한 애들이 사라져요..."
• 🤔 왜 알아야 하는가: 문자열 오타가 부르는 캐시 대참사
• 1. 배열 키의 포함 관계 (Fuzzy Matching) 해부
• 2. 실전 적용: Query Key Factory 아키텍처
• 3. 궁극의 Next Step: Query Options API (v5)
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 아까 invalidateQueries(['todos']) 치셨죠? 방금 영숙 님이 보는 화면 캐시까지 싹 날아갔습니다. 쿼리 키 오타 내셨거든요."

☕️ 영철이의 고민: "무효화를 날렸는데 엉뚱한 애들이 사라져요..."

(화요일 점심 직전, 버그 제보를 받고 창백해진 영철)

🐣 영철: 아 리드 님 큰일 났어요! 유저가 '완료된 할 일' 목록에서 아이템 하나 삭제했는데, 갑자기 메인 화면에 있던 '진행 중인 할 일' 리스트랑 '이번 달 전체 통계' 캐시까지 몽땅 폭파(Invalidate)돼서 전부 미친 듯이 리패칭 치고 서버 부하가 튀었어요;;

🦁 영호: 코드 줘 보세요. (타닥타닥)
queryClient.invalidateQueries({ queryKey: ['todos'] }) 이렇게 쏘셨군요.
영철 님이 모든 훅들에 쿼리 키를 ['todos', 'done'], ['todos', 'in-progress'], 심지어 ['todos', 'stats', 'monthly'] 이렇게 중구난방 문자열로 달아두셨잖아요.
React Query의 invalidate 는 상위 키(['todos']) 만 포함되어 있으면 그 밑의 꼬리표가 달린 하위 트리 전체를 자비 없이 박살 내버립니다.

🐣 영철: 헉! 그럼 지우고 싶은 '완료된 리스트'만 딱 꼬집어서 지우려면 어떡해요?

🦁 영호: 그래서 5년 차 실무의 시작은 "쿼리 키 팩토리(Query Key Factory)" 계층형 아키텍처 를 짜는 것부터 출발하는 겁니다. 중앙 통제소가 없으면 이런 스파게티 무효화 현상이 터집니다.

🤔 왜 알아야 하는가: 문자열 오타가 부르는 캐시 대참사

React Query의 코어 심장은 QueryCache 라는 거대한 금고입니다.
그 금고의 방 번호가 바로 우리가 배열로 넘겨주는 Query Key 죠.

여기서 발생하는 두 가지 치명적 문제가 있습니다.

1. 타입의 부재: 개발자 A는 useQuery({ queryKey: ['todo', 1] }) 라고 짜고, 개발자 B는 삭제 완료 후 엉뚱하게 queryClient.invalidateQueries({ queryKey: ['todos', 1] }) 라고 오타를 냅니다. 아무일도 일어나지 않고 유저는 영원히 낡은 화면을 봅니다. (TypeScript도 문자열 오타는 못 잡아줍니다!)
2. 부비트랩(Fuzzy Matching): 배열의 포함 관계 원리를 모르면, 영철이처럼 실수로 앱 전체의 네트워크를 죄다 초기화시켜버리는 미친 성능 저하 폭발이 발생합니다.

이 챕터에서는 전역 상수 객체 로 쿼리 키를 설계하여 휴먼 에러를 0%로 박멸하는 최강의 구조를 배웁니다.

1. 배열 키의 포함 관계 (Fuzzy Matching) 해부

TkDodo의 아티클 #8에 명시된 가장 중요한 무효화 룰입니다.
"앞에서부터 계층(배열 순서)이 일치하면 무조건 타겟 대상이 된다!"

queryClient.invalidateQueries({ queryKey: ['todos'] }) 하나를 발사했을 때,

• ✅ ['todos'] (맞음 -> 무효화)
• ✅ ['todos', 'list', 'done'] (todo계열 맞음 -> 무효화 범위 안 됨!)
• ✅ ['todos', 'detail', 1] (todo계열 맞음 -> 삭제!)
• ❌ ['users', 'todos'] (틀림, 맨 앞이 users임 -> 살려줌)

만약 영철이가 "딱 'done' 상태인 리스트만" 우아하게 지우고 싶었다면?
반드시 정확하게 queryClient.invalidateQueries({ queryKey: ['todos', 'list', 'done'] }) 까지 구체적으로 집어넣어야만 다른 형제 캐시들(['todos', 'detail', 1])이 폭파되는 걸 살릴 수 있습니다.

2. 실전 적용: Query Key Factory 아키텍처

문자열 하드코딩을 원천 봉쇄하기 위해 전역 팩토리 파일(keys.ts 또는 queries.ts)에 상수화된 객체(Factory Pattern) 를 만듭니다.

// 📝 constants/queryKeys.ts
 
// 🚀 모든 쿼리 키는 이 객체 트리를 통해 생성된다! (공장)
export const todoKeys = {
  // 1단계: 기본 도메인 키 (전체 무효화 때 쓸 거대한 폭탄 스위치)
  all: ['todos'] as const,
  
  // 2단계: 리스트 계열 묶음 키
  lists: () => [...todoKeys.all, 'list'] as const,
  // 3단계: 구체적인 검색/필터 리스트 (상위 키들을 전부 품고 내려옴)
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  
  // 2단계: 단건(디테일) 계열 묶음 키
  details: () => [...todoKeys.all, 'detail'] as const,
  // 3단계: 특정 1건 디테일
  detail: (id: number) => [...todoKeys.details(), id] as const,
};

이렇게 공장을 차려두면, 사용하는 클라이언트(View, Hook) 쪽 코드가 100% 안전하고 오타 없는 코드로 진화합니다.

// 1️⃣ 데이터 가져올 때
import { todoKeys } from '@/constants/queryKeys';
 
function TodoDetail({ id }: { id: number }) {
  // 오타 날 확률 0%, id 파라미터를 안 넣으면 TypeScript가 즉시 에디터에서 에러 뿜음!
  const { data } = useQuery({
    queryKey: todoKeys.detail(id), 
    queryFn: () => fetchTodoDetail(id),
  });
}

// 2️⃣ 삭제/수정 완료 후 무효화 할 때 (정밀 타격)
const deleteMutation = useMutation({
  mutationFn: deleteTodo,
  onSuccess: () => {
    // 🔥 "todos 디테일 캐시는 다 살려두고, 리스트 계열 렌더링만 싹 다시 해!"
    queryClient.invalidateQueries({ queryKey: todoKeys.lists() });
  }
})

3. 궁극의 Next Step: Query Options API (v5)

아키텍처에 욕심이 많은 시니어들은 한 통 더 나아갑니다.
키(queryKey) 따로, 펑션(queryFn) 따로 관리하는 것도 귀찮습니다. 어차피 ['todos', id] 면 무조건 fetchTodoDetail(id) 함수를 호출해야 하는 게 필연적인 운명(Coupling)이잖아요?

그래서 최신 React Query v5 에서는 이 둘을 한 몸으로 묶어버린 queryOptions 기반의 팩토리가 표준이 되었습니다 (TkDodo #24 참조). 앞선 Basic 07강의 심화 복습입니다.

import { queryOptions } from '@tanstack/react-query';
 
export const todoQueries = {
  all: () => ['todos'],
  
  // 키 + 페칭 로직 + 만료기간(staleTime) 까지 영원히 하나로 묶어버림!
  detail: (id: number) => queryOptions({
    queryKey: [...todoQueries.all(), 'detail', id],
    queryFn: () => axios.get(`/todos/${id}`).then(res => res.data as Todo),
    staleTime: 5 * 60 * 1000, 
  }),
};

// 데이터 수정 무효화 때, 그냥 통짜 옵션 객체를 발사해 버립니다.
queryClient.invalidateQueries(todoQueries.detail(1));

단 한 줄의 문자열 오타(String Typo)도 발생 불가능한, 빈틈없는 티타늄 장벽이 프론트엔드 전체에 깔리게 되는 셈이죠!

🐣 영철이의 퇴근 일기

헐... todoKeys.all, todoKeys.lists() 이렇게 부모 배열 껍데기 그대로 확장(...spread)해서 가져다 붙이니까 무효화시킬 때 스코프(Scope) 딱딱 나눠서 제어하는 거 예술이다 진짜.

💡 오늘의 교훈: "하드코딩 배열 ['foo', 'bar'] 을 쓰는 자는 에러 수습에 밤을 새우리라! 무조건 객체 기반의 Query Key Factory 패턴(또는 Query Options 팩토리)을 구축해서 파일 하나에 모든 캐시 금고 이름을 통제하자."

아까 오타 나서 전체 무효화 쳤을 때 영수(백엔드) 님 모니터에 터져나오던 서버 부하 트래픽 로그가 아직도 눈앞에 선하다 ㅋㅋ ㅠㅠ... 내일 일찍 출근해서 앱 곳곳에 오타 확률 숨어있는 [] 리터럴 키들 싹 다 찾아서 queryOptions 제국으로 대통일 시켜놔야지!!

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

Q. 다음과 같은 계층을 가지는 쿼리 키 팩토리를 구성했습니다. 특정 Mutation 이후에 아래의 invalidateQueries 를 실행했을 때, 무효화(삭제 및 리패치 마킹)를 '피하게 되는(생존하는)' 캐시는 어느 것일까요?

queryClient.invalidateQueries({ queryKey: ['orders', 'shipping'] });

• A) ['orders', 'shipping', 'list', { status: 'done' }]
• B) ['orders', 'shipping', 12345]
• C) ['orders', 'payment', 'list']

✅ 정답: C

💡 상세 해설:

• 원리 설명: React Query의 무효화(invalidate) 내부 알고리즘은 "배열의 앞에서부터 값이 완벽히 일치하는(포함 관계인) 모든 하위 노드를 폭파" 시키는 퍼지 매칭(Fuzzy Matching)을 사용합니다. 우리가 입력한 쏘스는 ['orders', 'shipping'] 이므로, 앞 두 자리가 저 글자로 시작하는 A번과 B번의 무수히 많은 상세 트리 가지들은 모조리 폭파됩니다.
• 오답 피드백: "영철 님, C번 캐시는 orders 까지는 같지만 두 번째 계층에서 shipping이 아니라 payment로 갈라졌죠? 그래서 방폭 텐트 안에 안전하게 살아남습니다. 이렇게 계층(Hierarchy) 순서 설계가 무효화의 폭발 반경(Blast Radius)을 결정하는 겁니다!"
• 📌 핵심 기억법: 앞에서부터 스펠링&순서 일치 = 포함된 모든 자식 박살. 엇나간 가지 = 생존!