[React Query] queryKey란?

오늘은 React Query에서 queryKey가 변경될 때 자동으로 API가 호출되는 원리에 대해 알아보려고 합니다.
처음에는 useEffect로 refetch()를 직접 호출해야 한다고 생각했는데, 알고 보니 React Query가 알아서 감지하고 API를 호출하더라고요!
그 이유를 코드와 함께 쉽게 설명해 보겠습니다.

 

■ queryKey란?

React Query에서 queryKey는 캐싱된 데이터를 구분하는 고유한 식별자 역할을 합니다.
즉, 같은 queryKey를 가진 쿼리는 동일한 데이터 그룹으로 취급되며, queryKey가 변경되면 React Query는 새로운 데이터가 필요하다고 판단하여 자동으로 API를 다시 호출합니다.

const useManagers = (reqDto: mngrGrdeData, page: number) => {
  return useQuery({
    queryKey: ["items", reqDto, page], // queryKey에 page 포함됨
    queryFn: async () => {
      const response = await getManagers(reqDto, page);
      console.log("API 호출");
      return response;
    },
    enabled: true, // 자동 실행 활성화
  });
};

위 코드에서 queryKey를 보면 ["items", reqDto, page]로 구성되어 있습니다.
여기서 중요한 점은 page가 포함되어 있다는 것!

 

■ page 값이 변경될 때 자동으로 API가 호출되는 이유

React Query는 내부적으로 queryKey가 변경되었는지 감지합니다.
그렇기 때문에, page가 변경되면 "items"이라는 그룹 내에서 기존 queryKey와 다른 queryKey가 생성됩니다.

즉,

• page = 1 → queryKey = ["items", reqDto, 1, 10]
• page = 2 → queryKey = ["items", reqDto, 2, 10]

이렇게 변경되면, React Query는 "아, 새로운 데이터가 필요하겠구나!" 하고 API를 자동으로 호출합니다.
즉, 별도의 useEffect 없이도 page 값이 변경될 때 자동으로 데이터를 다시 가져오는 것입니다.

 

■ useEffect 없이도 동작하니까, 불필요한 코드 제거 가능!

아래처럼 page 변경을 감지해서 refetch()를 호출하는 useEffect가 필요없습니다.

useEffect(() => {
  refetch();
}, [page]);

이미 queryKey에 page가 포함되어 있기 때문에, 이런 useEffect를 작성할 필요가 없습니다.
React Query가 알아서 API를 다시 호출해 주니까, 우리는 코드만 깔끔하게 정리하면 됩니다.

const { data } = useManagers(reqDto, page); // page가 변경되면 자동으로 데이터 요청

 

■ 결론

✔ queryKey에 포함된 값이 변경되면 React Query가 자동으로 API를 다시 호출함
✔ page 값이 변경되면 새로운 queryKey가 생성되면서 자동으로 API 요청이 이루어짐
✔ 불필요한 useEffect 없이도 page 변경만으로 데이터 갱신이 가능
✔ 자동 호출을 막으려면 queryKey에서 해당 값을 제거하거나 enabled: false를 설정