4. 효율적으로 React Query Key 선언하기

이 글을 읽고 queryOptions API 글을 읽는 걸 추천합니다

---

1. 들어가기

Query Keys는 React Query에서 아주 중요한 핵심 개념이다.

queryKey 덕분에 라이브러리 내부적으로 데이터를 올바르게 캐싱하고 queryKey dependency가 변경될 때 자동으로 refetch 할 수 있다.

또한 mutations 후 수동으로 쿼리 무효화(invalidate)를 하기위해 필요하다.

 

밑줄 친 위 기능들을 하나씩 살펴보고,

각 기능을 효과적으로 수행하기 위해 필요한 효율적인 queryKey 선언 방법에 대해 알아보자.

2. queryKey 관련 기능

2.1. 데이터 캐싱

내부적으로 Query 캐시는 javascript 객체이다.

key: 직렬화된 queryKey , value: Query data 와 메타 정보

queryKey는 배열 [ ] 형태이며 배열의 원소는 string, object등이 들어갈 수 있다.

원소들의 순서가 다르면 서로 다른 key로 인식된다. (['todos', 'kuma'] 와 ['kuma', 'todos'] 는 서로 다르게 취급된다)

다만 원소가 객체일때, 해당 객체 내부 key의 순서가 달라져도 같은 쿼리로 간주된다.

// 쿼리 1
useQuery({
  queryKey: ['todos', { status: 'completed', page: 1 }],
  queryFn: fetchTodos,
})

// 쿼리 2
useQuery({
  queryKey: ['todos', { page: 1, status: 'completed' }],
  queryFn: fetchTodos,
})

// 두 쿼리는 같다

 

다만 key는 같더라도 value가 달라지만 다른 쿼리이다.

// 쿼리 1
useQuery({
  queryKey: ['todos', { status: 'completed', page: 1 }],
  queryFn: fetchTodos,
})

// 쿼리 2
useQuery({
  queryKey: ['todos', { status: 'pending', page: 1 }],
  queryFn: fetchTodos,
})

// 두 쿼리는 다르다.

 

또한 React Query가 캐시 목록에서 queryKey에 대응하는 value를 찾으면 이를 사용하기 때문에,

queryKey는 반드시 unique 해야한다.

또한 useQuery 와 useInfiniteQuery에 동일한 키를 사용할 수 없다는 점을 기억하자.

useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

// 🚨 useQuery와 queryKey가 동일하기 때문에 동작하지 않는다.
useInfiniteQuery({
  queryKey: ['todos'],
  queryFn: fetchInfiniteTodos,
})

// ✅ 다른 queryKey를 선언하자. 
useInfiniteQuery({
  queryKey: ['infiniteTodos'],
  queryFn: fetchInfiniteTodos,
})

 

2.2. 자동 Refetch

쿼리는 선언적이다.

이는 아무리 강조해도 지나치지 않는 매우 중요한 컨셉이다.

대부분의 사람들은 쿼리를 생각할때, 특히 refetching을 할때 명령적으로 생각한다.

기존 쿼리가 있을때 필터 조건을 걸 수 있을때 이런식으로 사용하고 싶을 수 있다.

function Component() {
  const { data, refetch } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  })

  // ❓ 매개변수를 넘기고 싶은데.. ❓
  return <Filters onApply={() => refetch(???)} />
}

 

하지만 이렇게 하면 안된다.

이는 refetch의 존재 목적이 아니다. - refetch의 목적은 같은 매개변수로 데이터를 다시 불러오는 것이다.

 

만약 필터와 같이 데이터를 변경하는 상태가 있는 경우, queryKey가 변경될 때마다 React Query가 자동으로 refetch 하므로, 해당 상태를 queryKey에 넣기만 하면 된다.

즉 쿼리에 필터를 적용하고 싶다면 클라이언트 상태를 변경하기만 하면 된다.

function Component() {
  const [filters, setFilters] = React.useState()
  const { data } = useQuery({
    queryKey: ['todos', filters],
    queryFn: () => fetchTodos(filters),
  })

  // ✅ 로컬 상태를 set하여 query를 가져오자.
  return <Filters onApply={setFilters} />
}

 

setFilters 호출을 통해 리렌더링이 되면 다른 filters(queryKey)가 쿼리에 전달되어 data가 refetch 된다.

따라서 선언적으로 refetch가 되는 것이다.

선언적인 queryKey에 관해서는 1. 실용적인 React Query 글에도 언급한 적이 있다.

 

2.3. Manual Interaction (수동 상호작용)

invalidateQueries 나 setQueriesData 같이 개발자가 수동으로 쿼리를 조작할 수 있는 메서드는 호출할 때 Query Fliters를 넣어줘야한다. Query Filters에는 조작할 쿼리를 특정하기위해 queryKey가 이용된다.

// 첫 원소가 posts로 시작하는 queryKey를 가진 모든 inactive 쿼리들을 제거한다.
queryClient.removeQueries({ queryKey: ['posts'], type: 'inactive' })

3. 효과적인 React Query Keys

3.1. Colocate

참고)  Kent C. Dodds의 Maintainability through colocation

모든 queryKey를 /src/utils/queryKeys.ts에 전역적으로 배치하는게 좋을까?

- src
  - features
    - Profile
      - index.tsx
      - queries.ts
    - Todos
      - index.tsx
      - queries.ts

 

다음과 같이 훅이 가까이 쓰이는 폴더에 fetch, useQuery, queryKey를 같은 파일에 함께 선언해보자.

나(영진)는 보통 useQuery를 감싸는 커스텀훅을 내보내고, queryKey도 필요하다면 그때 내보낸다.

 

+ 추가

queryKey는 관련된 기능의 공통 부모 폴더에 하나의 객체로 선언해두는게 좋아보인다.

3.3 쿼리 키 팩토리 사용하기 참조

3.2. queryKey 배열 원소 선언 순서

일반적인 key -> 구체적인 key 순서대로 선언하자.

다음은 필터링 가능한 list와 각 item별 상세 보기가 가능한 투두리스트의 queryKey 예시이다.

['todos', 'list', { filters: 'all' }]
['todos', 'list', { filters: 'done' }]
['todos', 'detail', 1]
['todos', 'detail', 2]

 

이렇게 선언하면 ['todos']와 관련된 모든 쿼리를 무효화할 수 있고, 정확한 queryKey를 알고있다면 특정 쿼리 하나를 타겟팅할 수 있다.

또한 mutation 결과(onSuccess, onError에서)에 따라 쿼리를 업데이트 할 수 있다.

// mutation 결과에 따라 query 업데이트 하기.
function useUpdateTitle() {
  return useMutation({
    mutationFn: updateTitle,
    onSuccess: (newTodo) => {
      // ✅ ['todos', 'detail', newTodo.id]인 캐시 업데이트
      queryClient.setQueryData(
        ['todos', 'detail', newTodo.id],
        newTodo
      )

      // ✅['todos', 'list'] 캐시 내부에 있는 todo.id에 해당하는 todo 업데이트
      queryClient.setQueriesData(['todos', 'list'], (previous) =>
        previous.map((todo) =>
          todo.id === newTodo.id ? newtodo : todo
        )
      )
    },
  })
}

 

하지만 위 방법은 복잡하고, list와 detail의 todo 형식이 많이 다른 경우에는 적용하기 까다로울 수 있다.

대신 모든 ['todos'] 캐시를 무효화하는 방법이 있다. (서버에 재요청)

// 캐시 무효화 하기.
function useUpdateTitle() {
  return useMutation({
    mutationFn: updateTitle,
    onSuccess: (newTodo) => {
      queryClient.setQueryData(
        ['todos', 'detail', newTodo.id],
        newTodo
      )

      // ✅ ['todos', 'list'] 캐시 무효화
      queryClient.invalidateQueries({
        queryKey: ['todos', 'list']
      })
    },
  })
}

 

URL에서 필터를 읽는 등의 방식으로 queryKey 를 구성하여 setQueryData를 수행할 수도 있다.

function useUpdateTitle() {
  // imagine a custom hook that returns
  // the current filters, stored in the url
  const { filters } = useFilterParams()

  return useMutation({
    mutationFn: updateTitle,
    onSuccess: (newTodo) => {
      queryClient.setQueryData(
        ['todos', 'detail', newTodo.id],
        newTodo
      )

      // ✅ 현재 위치한 list 업데이트
      queryClient.setQueryData(
        ['todos', 'list', { filters }],
        (previous) =>
          previous.map((todo) =>
            todo.id === newTodo.id ? newtodo : todo
          )
      )

      // 🥳 모든 list 무효화
      // 다만 active인 list는 refetch 하지 않는다 (refetchType: 'none')
      queryClient.invalidateQueries({
        queryKey: ['todos', 'list'],
        refetchType: 'none',
      })
    },
  })
}

(사실 위 예시는 이해못했음. 그냥 invalidateQueries 만 해도 되지않나? ['todos', 'list', { filters }]  캐싱을 하고싶은 건가?)

3.3. 쿼리 키 팩토리 사용하기

위 예제에서는 queryKey를 수동으로 선언해두었다.

이렇게 하면 더 세부적인 key를 추가하는 경우와 같이 변경하기가 여러워진다.

 

다음과 같이 어떤 기능과 관련된 queryKey 들은 객체 하나에 모두 모아두자.

const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
}

 

유연하고 독립적으로 키에 접근할 수 있다.

// 🕺 todo와 관련된 모든 쿼리를 제거한다.
queryClient.removeQueries({
  queryKey: todoKeys.all
})

// 🚀 모든 todo list를 무효화한다.
queryClient.invalidateQueries({
  queryKey: todoKeys.lists()
})

// 🙌 특정 todo 하나를 prefetch 한다.
queryClient.prefetchQueries({
  queryKey: todoKeys.detail(id),
  queryFn: () => fetchTodo(id),
})

 

각 기능별로 쿼리 키를 선언해두면 서버 상태로 한눈에 보기 쉬운 장점이 있을 것 같다.

 

Reference

https://tkdodo.eu/blog/effective-react-query-keys