[TanStakQuery] Queries

쿼리 기본 사항(Query Basics)

쿼리는 고유 키(unique key)에 연결된 비동기 데이터 소스에 대한 선언적 종속성(declarative dependency)입니다. 쿼리는 서버에서 데이터를 가져오기 위해 모든 프로미스 기반 메서드(GET 및 POST 메서드 포함)와 함께 사용할 수 있습니다. 메서드가 서버의 데이터를 수정하는 경우 대신 Mutations을 사용하는 것이 좋습니다.

컴포넌트 또는 커스텀 훅에서 쿼리를 구독하려면 useQuery 훅을 최소한 다음과 함께 호출하세요:

• 쿼리의 고유 키(unique key)
• 프로미스를 리턴하는 함수:
  • 데이터를 확인하는 함수, 또는
  • 오류를 던지는 함수

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

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

제공한 고유 키는 애플리케이션 전체에서 쿼리를 다시 가져오고, 캐싱하고, 공유하기 위해 내부적으로 사용됩니다.

useQuery가 반환하는 쿼리 결과에는 템플릿 및 기타 데이터 사용에 필요한 쿼리에 대한 모든 정보가 포함되어 있습니다:

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

result 객체에는 생산성을 높이기 위해 알아야 할 몇 가지 매우 중요한 상태가 포함되어 있습니다. 쿼리는 주어진 순간에 다음 상태 중 하나에만 있을 수 있습니다:

• isLoading or status === 'loading' - 쿼리에 아직 데이터가 없습니다.
• isError or status === 'error' - 쿼리에서 오류가 발생했습니다.
• isSuccess or status === 'success' - 쿼리가 성공했으며 데이터를 사용할 수 있습니다.

이러한 기본 상태 외에도 쿼리 상태에 따라 더 많은 정보를 사용할 수 있습니다:

• error - 쿼리가 isError 상태인 경우 error 속성을 통해 오류를 사용할 수 있습니다.
• data - 쿼리가 isSuccess 상태인 경우 data 속성을 통해 데이터를 사용할 수 있습니다.

대부분의 쿼리에서는 일반적으로 isLoading 상태를 확인한 다음 isError 상태를 확인한 다음 마지막으로 데이터를 사용할 수 있다고 가정하고 성공 상태를 렌더링하는 것으로 충분합니다:

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

  if (isLoading) {
    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>
  )
}

데이터에 액세스하기 전에 loading, erro를 확인한 경우 TypeScript는 data 유형을 올바르게 좁힐 수 있습니다.

FetchStatus

status 필드, result 객체 외에도 다음 옵션이 있는 추가 fetchStatus 프로퍼티를 얻을 수 있습니다:

• fetchStatus === 'fetching' - 쿼리가 현재 가져오는 중입니다.
• fetchStatus === 'paused' - 쿼리를 가져오려고 했지만 일시 중지되었습니다. 이에 대한 자세한 내용은 네트워크 모드(Network Mode) 가이드를 참조하세요.
• fetchStatus === 'idle' - 쿼리가 현재 아무 작업도 수행하지 않고 있습니다.

왜 두 개의 다른 상태일까요?(Why two different states?)

백그라운드 refetches 및 stale-while-revalidate 로직을 사용하면 status 및 fetchStatus에 대한 모든 조합이 가능합니다. 예:

• success 상태의 쿼리는 일반적으로 idle 상태인 fetchStatus이지만 백그라운드 refetch가 발생하면 fetching일 수도 있습니다.
• 마운트되고 데이터가 없는 쿼리는 일반적으로 loading 상태이고 fetchStatus를 가져오는 중이지만 네트워크 연결이 없는 경우 paused일 수도 있습니다.

따라서 쿼리가 실제로 데이터를 가져오지 않고 loading 상태에 있을 수 있다는 점에 유의하세요. 경험상:

• status는 data에 대한 정보를 제공합니다: 데이터가 있습니까, 없습니까?
• fetchStatus는 queryFn에 대한 정보를 제공합니다: 실행 중인지 아닌지?

Further Reading

상태 확인을 수행하는 다른 방법은 Community Resources를 참조하세요.

Reference

• Queries | TanStack Query Docs