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

📋 목차

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

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

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

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

🐣 영철: 리드 님, 완료된 할 일 목록에서 아이템 하나를 삭제했는데 메인 화면의 진행 중 리스트와 이번 달 통계 캐시까지 같이 무효화됐어요. 화면은 맞게 갱신됐지만, 서버 로그를 보니 필요 없는 리패칭이 너무 많이 생겼습니다.

🦁 영호: 코드 줘 보세요. (타닥타닥)
queryClient.invalidateQueries({ queryKey: ['todos'] }) 이렇게 호출하셨군요.
영철 님이 모든 훅들에 쿼리 키를 ['todos', 'done'], ['todos', 'in-progress'], 심지어 ['todos', 'stats', 'monthly'] 이렇게 중구난방 문자열로 달아두셨잖아요.
React Query의 invalidateQueries는 전달한 queryKey를 prefix로 삼아 일치하는 쿼리를 찾습니다. 즉 ['todos']를 넘기면 ['todos', 'list'], ['todos', 'detail', id]처럼 그 아래 계층의 쿼리도 함께 대상이 될 수 있습니다.

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

🦁 영호: 그래서 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): 배열의 포함 관계 원리를 모르면, 영철이처럼 실수로 앱 전체의 네트워크를 죄다 초기화시켜버리는 과도한 성능 저하 급증이 발생합니다.

이 챕터에서는 전역 상수 객체 로 쿼리 키를 설계하여 오타와 과도한 무효화 범위를 줄이는 구조를 배웁니다.

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));

문자열 오타 가능성을 줄이고, 같은 키를 useQuery, prefetchQuery, invalidateQueries에서 일관되게 재사용할 수 있습니다.

📝 배운 내용 점검하기 (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의 무효화는 배열의 앞부분이 일치하는 쿼리를 찾는 prefix 기반 fuzzy matching을 사용합니다. ['orders', 'shipping']을 넘기면 A와 B처럼 같은 prefix를 가진 쿼리는 대상이 되고, C처럼 두 번째 계층이 다른 쿼리는 대상에서 벗어납니다.
• 오답 피드백: "영철 님, C번 캐시는 orders 까지는 같지만 두 번째 계층에서 shipping이 아니라 payment로 갈라졌죠? 그래서 무효화 범위 밖에 남습니다. 이렇게 계층(Hierarchy) 순서 설계가 무효화 범위를 결정합니다."
• 📌 핵심 기억법: 앞에서부터 스펠링과 순서가 일치하면 대상, 중간 계층이 갈라지면 대상 밖.

📝 마무리 퀴즈

Q1. Query Key Factory를 도입하는 핵심 이유는 무엇인가요?

✅ 정답: 도메인별 키 계층을 한곳에서 만들고 재사용해 오타를 줄이며 무효화 범위를 예측 가능하게 만들기 위해서입니다.

💡 상세 해설:
문자열 배열을 손으로 반복하면 ['todo']와 ['todos'] 같은 미묘한 차이가 캐시를 갈라놓습니다. Factory는 리스트, 상세, 필터 키의 부모·자식 관계를 코드로 고정합니다. 팀 단위 캐시 설계에서는 이 일관성이 성능보다 먼저입니다.

Q2. invalidateQueries({ queryKey: ['orders'] })가 배열 키에서 작동하는 기본 원리는 무엇인가요?

✅ 정답: 키의 앞부분이 일치하는 쿼리를 대상으로 삼는 prefix 기반 fuzzy matching입니다.

💡 상세 해설:
['orders', 'list']와 ['orders', 'detail', id]는 ['orders']의 하위 범위로 볼 수 있습니다. 반면 ['users', 'orders']는 앞부분이 다르므로 대상이 아닙니다. 그래서 키 계층을 어떻게 설계하느냐가 무효화 폭을 결정합니다.

Q3. 영철이의 테스트 타임: 댓글 상세 수정 후 댓글 목록은 갱신하되 게시글 상세 캐시는 건드리고 싶지 않습니다. 무엇을 먼저 확인해야 하나요?

✅ 정답: 댓글 도메인의 key factory가 목록과 상세 범위를 분리해 무효화할 수 있는 계층을 제공하는지 확인합니다.

💡 상세 해설:
정밀 무효화는 invalidateQueries 한 줄의 문제가 아니라 키 설계의 결과입니다. commentKeys.lists()처럼 범위를 표현할 수 있어야 불필요한 캐시까지 흔들지 않습니다. 영철이 이제 무효화를 "호출하는 것"이 아니라 "범위를 설계하는 것"으로 이해해야 합니다.

🐣 영철이의 퇴근 일기

오늘은 todoKeys.all, todoKeys.lists()처럼 부모 배열을 확장해 계층을 만들면 무효화 범위를 코드로 표현할 수 있다는 걸 배웠다.

💡 오늘의 교훈: "하드코딩 배열 키를 반복하지 말고, key factory로 도메인과 범위를 이름 붙이자."

아까 오타 하나로 전체 범위를 무효화했을 때 영수 님의 서버 로그가 크게 흔들렸다. 내일은 앱 곳곳에 흩어진 [] 리터럴 키를 찾아 queryOptions 팩토리로 모아야겠다.