Queries

 

쿼리는 고유한 키에 연결된 비동기 데이터 소스에 대한 선언적 의존성이다. 쿼리는 Promise를 기반으로 하는 모든 종류의 함수(GET, POST 메서드 포함)와 함께 사용하여 서버로부터 데이터를 가져올 수 있다. 만약 서버의 데이터를 수정하는 경우에는 Mutations를 사용하는 것을 권장한다.

 

컴포넌트나 커스텀 훅에서 쿼리를 사용하려면, useQuery 훅을 최소한 다음 두 가지 인자와 함께 호출해야 한다.

1. 쿼리를 식별하는 고유한 키
2. 다음 중 하나를 수행하는 promise를 반환하는 함수
   • 데이터를 성공적으로 가져와 반환하거나
   • 에러를 발생시킴

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

function App() {
  const info = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })
}

 

고유 키는 애플리케이션 전반에 걸쳐 쿼리를 다시 가져오고, 캐싱하며, 공유하는 데 내부적으로 사용된다. 

 

useQuery가 반환하는 쿼리 결과에는 화면 템플릿 작업이나 데이터 사용에 필요한 모든 정보가 포함되어 있다.

const result = useQuery({ queryKey: ['todos'], queryFn: fetchTodoList })

 

result 객체에는 생산성을 높이기 위해 알아둬야 할 몇 가지 매우 중요한 상태가 포함되어 있다. 쿼리는 특정 시점에 다음 중 하나의 상태만을 가질 수 있다.

• isPending 또는 status === 'pending': 쿼리에 아직 데이터가 없는 초기 로딩 상태
• isError 또는 status === 'error': 쿼리 실행 중 에러가 발생한 상태
• isSuccess 또는 status === 'success': 쿼리가 성공했으며 data를 사용할 수 있는 상태

이러한 주요 상태 외에도 쿼리 상태에 따라 추가 정보를 사용할 수 있다.

 

• error: 쿼리가 isError 상태일 때, error 속성을 통해 에러 객체에 접근할 수 있다.
• data: 쿼리가 isSuccess 상태일 때, data 속성을 통해 성공적으로 가져온 데이터에 접근할 수 있다.
• isFetching: 어떤 상태에서든 쿼리가 데이터를 가져오는 중일 때(백그라운드 refetch 포함), isFetching 값은 true가 된다.

대부분의 경우, 먼저 isPending 상태를 확인하고, 그 다음 isError 상태를 확인한 뒤, 마지막으로 데이터가 성공적으로 로드되었다고 가정하고 화면을 렌더링하는 것으로 충분하다.

function Todos() {
  const { isPending, isError, data, error } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodoList,
  })

  if (isPending) {
    return <span>Loading...</span>
  }

  if (isError) {
    return <span>Error: {error.message}</span>
  }

  // We can assume by this point that `isSuccess === true`
  return (
    <ul>
      {data.map((todo) => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

 

boolean 값 대신 문자열로 상태를 확인하고 싶다면, status 상태를 사용할 수도 있다.

function Todos() {
  const { status, data, error } = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodoList,
  })

  if (status === 'pending') {
    return <span>Loading...</span>
  }

  if (status === 'error') {
    return <span>Error: {error.message}</span>
  }

  // also status === 'success', but "else" logic works, too
  return (
    <ul>
      {data.map((todo) => (
        <li key={todo.id}>{todo.title}</li>
      ))}
    </ul>
  )
}

 

TypeScript는 pending과 error 상태를 먼저 확인하면, 그 이후 코드에서 data의 타입을 undefined가 아닌 실제 데이터 타입으로 정확하게 추론해준다.

 

FetchStatus

 

status 필드 외에도, 다음과 같은 옵션을 가진 fetchStatus 속성도 제공된다.

• fetchStatus === 'fetching': 쿼리가 현재 데이터를 가져오는 중이다.
• fetchStatus === 'paused': 쿼리가 데이터를 가져오려고 했지만, 일시 중지되었다.
• fetchStatus === 'idle': 쿼리가 현재 아무 작업도 하지 않는 유휴 상태이다.

왜 두 개의 다른 상태가 필요한가? (status, fetchStatus)

 

백그라운드 refetch나 stale-while-revalidate 같은 로직 때문에 status와 fetchStatus의 모든 조합이 가능해진다.

 

• status가 success인 쿼리는 보통 fetchStatus가 idle이지만, 백그라운드 refetch가 발생하면 fetching이 될 수도 있다. (화면에 이전 데이터를 보여주면서, 백그라운드에서 조용히 새 데이터를 가져오는 상황)
• 컴포넌트가 처음 마운트되어 데이터가 없는 쿼리는 보통 status가 pending이고 fetchStatus는 fetching이지만 네트워크 연결이 없으면 paused 상태가 될 수도 있다.

따라서 쿼리가 실제로 데이터를 가져오지 않으면서도 pending 상태일 수 있다는 점을 기억해야 한다. 핵심적인 차이는 다음과 같다.

• status는 데이터에 대한 정보를 알려준다. 데이터가 있는가, 없는가?
• fetchStatus는 데이터를 가져오는 함수인 queryFn에 대한 정보를 알려준다. 요청 함수가 실행 중인가, 아닌가?

 

https://tanstack.com/query/latest/docs/framework/react/guides/queries

Queries | TanStack Query React Docs