문제상황

API 호출에 사용되는 파라미터 스펙이 바뀌면서 클라이언트 코드에도 새로운 파라미터를 반영해야 했다.

useQuery 훅의 queryKey에 새 파라미터를 추가했지만, 다른 컴포넌트(또는 유틸)에서 캐시 무효화를 위해 호출하던 invalidateQueries 쪽은 그대로 두는 실수가 있었다.

그 결과 데이터가 갱신되지 않는 버그가 발생했다.

문제 배경

• 이전 상황

  // 대회에 속한 팀 목록을 불러오는 useQuery
  useQuery<TeamListItemResponseDto[]>({
      queryKey: ['teams', user?.id ?? 'guest'], ...
  
  // 다른 컴포넌트에서 캐시 무효화
  queryClient.invalidateQueries({ queryKey: ['teams', user?.id ?? 'guest'] });
  

• 변경 사항

  // 대회에 속한 팀 목록을 불러오는 useQuery
  return useQuery<TeamListItemResponseDto[]>({
      queryKey: ['teams', contestId, user?.id ?? 'guest'], ...
  
  // 다른 컴포넌트에서 캐시 무효화
  queryClient.invalidateQueries({ queryKey: ['teams', user?.id ?? 'guest'] });
  

<aside> 💡

useQuery로 API를 호출하는 부분에서 queryKey가 변경되었지만 캐시 무효화 부분에서는 이를 반영하지 않아 버그가 발생하였다.

</aside>

현재 프로젝트에서는 queryKey를 어떻게 관리하고 있을까?

우선 useQuery를 커스텀 훅으로 분리한 코드가 별로 없고, 모두 컴포넌트 내에서 직접 관리하는 형태이다.

또한, queryKey의 값이 일관적이지 않고, 해당 부분을 맡은 개발자가 임의로 지정하여 사용하는 경우가 대부분이다.

개인적으로 URI를 queryKey로 사용하는 것이 익숙하여 이를 공통적으로 적용하면 좋겠다는 생각을 했다.

하지만 이를 적용하더라도 위에서 발생한 문제가 해결되지는 않는다.

쿼리 키는 정적인 경우도 있지만 파라미터에 따라 동적으로 변화할 수 있어야하므로 이를 관리하는 객체를 만들어 적용하는 아이디어를 떠올렸지만 최선의 방법인지에 대한 확인이 없어 관련 레퍼런스를 찾아보기로 했다.

레퍼런스

Query Key Factory | TanStack Query React Docs

Querykey factory에서 Query factory로 | 5kdk 개발 블로그

찾아보니 TanStack Query v4에서 QueryKeyFactory라는 라이브러리를 소개하는 글을 발견했고, 추가적으로 v5의 queryOptions를 활용하여 키와 쿼리를 통합 관리하느 Query factory에 대한 소개글도 확인할 수 있었다.