TanStack Query Query Key 직렬화 방식 분석: 동일 키 인식 메커니즘 파헤치기

핵심 기술

본 문서는 TanStack Query (구 React Query) 라이브러리에서 useQuery 함수 호출 시 전달되는 queryKey가 내부적으로 어떻게 저장되고 비교되어 동일한 쿼리로 인식되는지에 대한 메커니즘을 분석합니다. 핵심은 queryKey의 직렬화(Serialization) 과정과 JSON.stringify의 replacer 함수 활용에 있습니다.

기술적 세부사항

• QueryClientProvider: TanStack Query 사용의 시작점으로, QueryClient 인스턴스를 제공합니다.
• QueryCache: 모든 쿼리 데이터와 상태를 관리하는 핵심 캐시이며, Map<string, Query> 형태로 쿼리들을 저장합니다.
• Query Key의 문자열화: useQuery에 배열 형태로 전달된 queryKey는 QueryCache 내에서 고유한 문자열 키로 변환되어 저장 및 조회됩니다.
• hashKey 함수: 기본적으로 queryKey를 문자열로 직렬화하는 함수로, JSON.stringify와 커스텀 replacer 함수를 사용합니다.
  • replacer 함수: JSON.stringify의 두 번째 인자로, 직렬화 전에 값의 형식을 재구성합니다.
  • 객체 처리: 객체 내부의 키를 알파벳 순서로 정렬하고, undefined 값을 제거하여 일관된 문자열 표현을 만듭니다.
  • JSON 표준: undefined는 JSON 표준에 없으므로 JSON.stringify에서 기본적으로 제거되거나 null로 처리될 수 있습니다. replacer를 통해 커스텀 처리가 가능합니다.
• Query Key 비교 로직: 직렬화된 문자열 키를 사용하여 기존 쿼리를 조회하거나 새로 생성합니다. 이로 인해 객체 내 요소의 순서가 다르거나 undefined 값이 포함되어도 동일한 queryKey로 인식됩니다.

개발 임팩트

• TanStack Query의 쿼리 키 비교 방식에 대한 명확한 이해를 통해 예측 가능한 데이터 캐싱 및 조회를 보장할 수 있습니다.
• 복잡한 객체나 순서에 민감한 데이터를 queryKey로 사용할 때 발생할 수 있는 문제를 사전에 방지하고, 의도한 대로 동작하도록 할 수 있습니다.
• 커스텀 해싱 함수 구현 시 replacer 함수의 활용 방안에 대한 인사이트를 얻을 수 있습니다.

커뮤니티 반응

• 본문에서는 커뮤니티 반응에 대한 직접적인 언급은 없으나, TanStack Query와 같은 상태 관리 라이브러리는 개발자 커뮤니티에서 활발히 논의되고 활용되는 주제입니다.

톤앤매너

• 전문적이고 분석적인 톤으로, TanStack Query의 내부 동작 원리를 코드와 함께 명확하게 설명하고 있습니다. 개발자에게 실질적인 학습 가치를 제공합니다.