현재 쿼리 키 관리의 Pain Points

1. 매번 달라지는 쿼리 함수

   API 로직/옵션이 여기저기 흩어져 있어 동일 도메인에서도 queryFn, staleTime, refetch*가 일관되지 않게 섞입니다. 디버깅도 힘들고, 개발자마다 스타일이 달라져 응집도가 낮아집니다.

   

2. 일관성 떨어지는 쿼리 키 네이밍

   같은 데이터를 다루지만 다른 네이밍 ['myInfo'], [myData], 'GET_AVAILABLE_TIMES_BY_GROUP' 등 표현식과 구조가 제각각입니다. 어떤 키가 어떤 스코프에 속하는지, 무효화(invalidate) 범위는 어떻게 잡아야 하는지 매번 추측해야 합니다.

   

   

3. 중복 선언/중복 로직

   유사한 키/함수가 여러 파일에 반복 선언됩니다. 한 번 바꾸려면 여러 군데를 동시에 수정해야 하고, 버그가 숨어들기 쉽습니다.

4. 일관성 떨어지는 쿼리키 네이밍

그래서 생각했던 대안

A. 키/함수 동시 팩토리

export const checklistKeys = {
  all: ['checklists'] as const,
  lists: (filters: object = {}) => [...checklistKeys.all, 'list', filters] as const,
  mine: (userId: string) => [...checklistKeys.lists(), 'mine', userId] as const,
  completed: (filters: object) => [...checklistKeys.lists(), 'completed', filters] as const,
  pending: (filters: object) => [...checklistKeys.lists(), 'pending', filters] as const,
  detail: (id: number) => [...checklistKeys.all, 'detail', id] as const,
  items: (id: number) => [...checklistKeys.detail(id), 'items'] as const,
};

• 장점: 팀 취향대로 만들 수 있고, 러닝커브가 없다.
• 단점: 키는 표준화되지만, queryFn, staleTime 등 옵션은 여전히 각 훅에서 따로 관리해야 해서 응집도/가독성/타입 추론 이점이 제한적임

B. 키만 별도 상수로 관리

export const QUERY_KEYS = {
  CHECKLIST: {
    GET_CHECKLIST_INFO: 'get-checklist-info',
    GET_MY_CHECKLISTS: 'get-my-checklists',
    GET_COMPLETED_CHECKLISTS: 'get-completed-checklists',
    GET_PENDING_CHECKLISTS: 'get-pending-checklists',
  },
  MEMO: {
    GET_MEMO_LIST: 'get-memo-list',
    GET_MEMO_DETAIL: 'get-memo-detail',
    GET_FAVORITE_MEMOS: 'get-favorite-memos',
    GET_ARCHIVED_MEMOS: 'get-archived-memos',
    GET_SHARED_MEMOS: 'get-shared-memos',
  },
};

• 장점: 키 문자열은 한 곳에 모인다.
• 단점: 배열 키 규약을 벗어나기 쉽고, 정적 문자열만 관리해 스코프/무효화 범위가 불명확해진다. 무엇보다 쿼리 옵션과 분리되어 있어 중복/불일치 위험이 남는다.
• 결론: 반복되는 함수 사용을 한눈에 보기←라는 니즈를 충족시키기 어려워 제외

C. TanStack queryOptions만으로 순수 팩토리

import { queryOptions } from '@tanstack/react-query';

const fetchTodos = async (filters: string) => { /* ... */ };
const fetchTodo  = async (id: number) => { /* ... */ };

export const todoQueries = {
  all:   () => ['todos'] as const,
  lists: () => [...todoQueries.all(), 'list'] as const,
  list:  (filters: string) =>
    queryOptions({
      queryKey: [...todoQueries.lists(), { filters }] as const,
      queryFn: () => fetchTodos(filters),
      staleTime: 5_000,
    }),

  details: () => [...todoQueries.all(), 'detail'] as const,
  detail:  (id: number) =>
    queryOptions({
      queryKey: [...todoQueries.details(), id] as const,
      queryFn: () => fetchTodo(id),
      staleTime: 5_000,
    }),
};

• 장점: queryKey와 queryFn을 한 곳에서 관리해 응집도가 올라간다.