[ TanStack Query ] TanStack Query (React Query)에 대해 알아보자.

참고사이트

• Transtack Query 공식 문서

TanStack Start Overview | TanStack Start React Docs

• HEROPY.DEV 님의 블로그

TanStack Query(React Query) 핵심 정리

 

🌴TanStack Query

Tanstack Query(이전 React Query)는 서버로부터 데이터 가져오기, 데이터 캐싱, 제어 등 데이터를 쉽고 효율적으로 관리할 수 있는 라이브러리이다.

 

기존에는 React Query라는 이름을 사용했지만, 이후 Vue, Solid, Svelete 등 다양한 프레임워크에서도 사용하면서 React를 제외하고 개발자명을 따와 Tanstack Query로 이름을 변경.

 

공식 문서에 다음과 같이 작성되어 있다.

웹 개발자를 위한 높은 퀄리티의 오픈소스.

 

강력한 비동기 상태관리 도구

💪🏻 대표 기능

✅ 데이터 가져오기 및 캐싱

✅ 동일 요청의 중복 제거

✅  신선한 데이터 유지

✅  무한 스크롤, 페이지네이션 등의 성능 최적화

✅  네트워크 재연결 요청, 실패 등의 자동 갱신

 

 

📦 데이터 캐싱

TanStack Query를 활용해서 데이터를 가져올 때는 항상 쿼리 키 (Query-Key)를 지정하게 된다.

이 쿼리-키는 캐시된 데이터와 비교해 새로운 데이터를 가져올지, 캐시된 데이터를 사용할지 결정하는 기준이 된다.

 

Query-key를 통해 요청을 보낼 때, 캐싱에 해당 키로 접근할 데이터가 있는지 확인 후, 없다면 서버로부터 데이터를 받아 캐싱한다.

 

그 이후, 쿼리 키로 일치하는 데이터가 있을 경우, 서버에 요청하지 않고 캐시된 데이터를 가져와 사용하게 된다.

이렇다면 같은 데이터를 가져오는 요청이 여러 번 발생해도, 캐시된 데이터를 사용하게 되어 중복 요청을 줄일 수 있다.

 

✨ 데이터의 신선도

TanStack Query는 캐시한 데이터를 신선(Fresh)하거나 상한(Stale) 상태로 구분하여 관리한다.

캐시된 데이터가 신선하다면 캐시된 데이터를 사용하고, 만약 데이터가 상했다면 서버에 다시 요청해 신선한(새로운) 데이터를 가져온다.

일종의 데이터 유통기한이라고 생각하면 쉽다.

 

데이터가 상하는데까지 걸리는 시간을 staleTime 옵션을 통해 지정할 수 있다.

그리고 신선한지 여부는 isStale로 확인 할 수 있다.

 

"use client"

import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function Home() {
  return (
    <QueryClientProvider client={queryClient}>
      <StaleData/>
    </QueryClientProvider>
  )
}

function StaleData() {
  const { data, isStale } = useQuery({
    queryKey: ['todo'],
    queryFn: async () => (await fetch('https://jsonplaceholder.typicode.com/todos/1')).json(),
    staleTime: 1000 * 3,
  })
  return <div className='flex flex-col items-center justify-center h-screen bg-gray-900 text-white'>
  <div>데이터 {isStale ? '🐛신선하지 않음' : '🍎신선함'}</div>
  <div>{JSON.stringify(data)}</div>
  </div>
}

 

해당 코드는 Stale을 3초로 지정했다. 

렌더링 후, 3초를 기다리면 3초 후에 사과가 상하는 것을 확인 할 수 있다.

(왼) 데이터를 받아온 후 신선한 화면 / (우) 데이터를 받고 3초 후 상한 화면

 

 

🚀 핵심 기능

TanStack Query를 시작하기 앞서, 프로젝트 범위를 <QueryClientProvider>로 랩핑해야한다.

import {
  QueryClient,
  QueryClientProvider,
} from '@tanstack/react-query'
import Children from '~/components/Children'

const queryClient = new QueryClient()

export default function Home() {
  return (
    <QueryClientProvider client={queryClient}>
      <Children/>
    </QueryClientProvider>
  )
}

💪🏻 useQuery

가장 기본적인 쿼리 훅으로, 컴포넌트에서 데이터를 가져올 때 사용한다.

const result = useQuery<T>(option)

 

option에는 객체형으로 많은 옵션들이 존재하는데 아래 링크에서 확인 할 수 있다.

@TanStack-Query/useQuery#Options

useQuery | TanStack Query React Docs

 

 

💪🏻 QueryKey

쿼리 키(query key)는 쿼리를 식별하는 고유한 값으로, 배열 형태로 지정한다.

다중 아이템 쿼리 키를 사용할 때는, 아이템의 순서가 중요하다.

// 단일 아이템 쿼리 키
useQuery({ queryKey: ['hello'] })

// 다중 아이템 쿼리 키
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2 }] })

// 서로 같은 쿼리
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2 }] })
useQuery({ queryKey: ['hello', 'world', 123, { b: 2, c: undefined, a: 1 }] })

// 서로 다른 쿼리
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2 }] })
useQuery({ queryKey: ['hello', 'world', 123, { a: 1, b: 2, c: 3 }] })
useQuery({ queryKey: ['hello', 'world'] })
useQuery({ queryKey: [123, 'world', { a: 1, b: 2, c: 3 }, 'hello'] })

 

현시점 작성자 분석

✅ 단일 아이템: 쿼리 키 배열에 하나의 키가 존재할 때,

✅ 다중 아이템: 쿼리 키 배열에 여러 키가 존재할 때,

✅ 서로 같은 쿼리: 배열 순서가 같고, 객체는 순서와 상관없이 키쌍이 맞을 때, (undefined는 제외)

✅ 서로 다른 쿼리: 배열 순서가 다르고, 객체는 순서 상관 없지만 키쌍이 다를 경우

 

"use client"

import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  
  return (
    <div className='flex flex-col items-center justify-center h-screen bg-gray-900 text-white'>
      <QueryClientProvider client={queryClient}>
        <TanstackComponent id={1} />
        <TanstackComponent id={2} />
      </QueryClientProvider>
    </div>
  )
}


type JsonPlaceholder = {
  userId: number
  id: number
  title: string
  completed: boolean
}

type TanstackComponentProps = {
  id?: number
}

function TanstackComponent({id}: TanstackComponentProps) {
  const { data, isStale } = useQuery<JsonPlaceholder>({
    queryKey: ['delay', id],
    queryFn: async () => {
      return (await fetch(`https://jsonplaceholder.typicode.com/todos${id ? `/${id}` : ''}`)).json();
    },
    staleTime: 1000 * 3,
  })

  return (
  <div className='flex flex-col items-center justify-center'>    
    <div>데이터 {isStale ? '🐛신선하지 않음' : '🍎신선함'}</div>
    <div>{JSON.stringify(data)}</div>
  </div>
  );
}

 

다음과 같이 jsonplaceholder 에서 ToDo 리스트를 가져올 때, id를 동적으로 적용하여 가져오고 싶을 때, 쿼리 키에 id값을 넣어주면 된다.

 

 

💪🏻queryFn

쿼리 함수(queryFn)는 데이터를 가져오느 비동기 함수로, 꼭 데이터를 반환하거나 오류를 던져야 한다.

던져진 오류는 반환되는 error 객체로 확인할 수 있다.

 

error는 기본적으로 null 이다.

 

API 요청 도중, 에러를 던져서 useQuery()로 에러를 받아 사용한다.

 

코드는 다음과 같다

"use client"

import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  
  return (
    <div className='flex flex-col items-center justify-center h-screen bg-gray-900 text-white'>
      <QueryClientProvider client={queryClient}>
        <TanstackComponent id={1}/>
        <TanstackComponent id={2}/>
      </QueryClientProvider>
    </div>
  )
}

type JsonPlaceholder = {
  userId: number
  id: number
  title: string
  completed: boolean
}

type TanstackComponentProps = {
  id?: number
}

function TanstackComponent({id}: TanstackComponentProps) {
  const { data, isStale, isPending, error } = useQuery<JsonPlaceholder>({
    queryKey: ['delay', id],
    queryFn: async () => {      
      const result = await fetch(`https://jsonplaceholder.typicode.com/todos${id ? `/${id}` : ''}/오류발생`);
      const data = await result.json();
      if(data.id !== 3) {
        throw new Error('에러 발생');
      }
      return data;

    },
    staleTime: 1000 * 3,
    retry: false,
  })

  if(isPending) {
    return <div className='text-green-400 p-3'>🟢 로딩중...</div>
  }

  if(error) {
    return <div className='text-red-500 p-3 font-bold'>⚠️ 에러 발생</div>
  }
  
  return (
  <div className='flex flex-col items-center justify-center'>    
    <div>데이터 {isStale ? '🐛신선하지 않음' : '🍎신선함'}</div>
    <div>{JSON.stringify(data)}</div>
  </div>
  );
}

 

좌) 데이터를 받기 전 Pending 상태 / 우) 데이터에 오류가 발생하여 오류 메시지 표시

 

💪🏻select

선택 함수(select)를 사용하면 가져온 데이터를 변형(선택) 할 수 있다.

쿼리 함수가 반환하는 데이터를 인수로 받아 선택 함수에서 처리하고 반환하여 최종 데이터가 된다.

최종 데이터 타입은 useQuery의 3번째 제네릭 타입으로 선언할 수 있다.

 

"use client"

import {
  QueryClient,
  QueryClientProvider,
  useQuery,
} from '@tanstack/react-query'

const queryClient = new QueryClient()

export default function App() {
  
  return (
    <div className='flex flex-col items-center justify-center h-screen bg-gray-900 text-white'>
      <QueryClientProvider client={queryClient}>
        <TanstackComponent id={1}/>
        <TanstackComponent id={2}/>
      </QueryClientProvider>
    </div>
  )
}

type JsonPlaceholder = {
  userId: number
  id: number
  title: string
  completed: boolean
}

type TanstackComponentProps = {
  id?: number
}

type returnType = {
  [key: string] : number
}

function TanstackComponent({id}: TanstackComponentProps) {
  const { data, isStale, isPending, error } = useQuery<JsonPlaceholder, Error, returnType>({
    queryKey: ['delay', id],
    queryFn: async () => {  
      const result = await fetch(`https://jsonplaceholder.typicode.com/todos${id ? `/${id}` : ''}`);
      const data = await result.json();
      if(!data.id) {
        throw new Error('에러 발생');
      }
      return data;

    },
    staleTime: 1000 * 3,
    select: data => ({ id: data.id }),
  })

  if(isPending) {
    return <div className='text-green-400 p-3'>🟢 로딩중...</div>
  }

  if(error) {
    return <div className='text-red-500 p-3 font-bold'>⚠️ 에러 발생</div>
  }
  
  return (
  <div className='flex flex-col items-center justify-center'>    
    <div>데이터 {isStale ? '🐛신선하지 않음' : '🍎신선함'}</div>
    <div>{JSON.stringify(data)}</div>
  </div>
  );
}

 

useQuery()에 반환 되는 타입들을 적어주고 세 번째는 최종 데이터를 넣어준 뒤

select를 통해 가져온 데이터를 다듬어 반환한다.

 

나는 id값만 가져와봤다.