[리액트쿼리] useQuery (공홈 번역)

공식 홈페이지 문서를 번역한 내용입니다.

출처
https://tanstack.com/query/v4/docs/guides/queries

useQuery

Query Basics

쿼리는 고유 키에 연결된 데이터의 비동기 소스에 대한 선언적 종속성입니다. 쿼리는 Promise 메서드를 통해(GET, POST 메서드를 포함한) 서버에서 데이터를 페치하는데 사용될 수 있습니다. 메서드가 서버에서 데이터를 수정한다면 Mutations 를 사용하는 것을 추천합니다.

컴포넌트나 커스텀 훅에서 쿼리를 구독하려면 다음 항목들과 함께 useQuery 훅을 사용하세요.

• 쿼리의 고유키
• 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 오브젝트는 몇 가지 중요한 상태가 포함되어 있습니다. 쿼리는 주어진 순간에 오직 하나의 상태가 될 수 있습니다.

• isLoading 또는 status === 'loading' - 쿼리가 아직 데이터가 없음
• isError 또는 status === 'error' - 쿼리가 에러 상태임
• isSuccess 또는 status === 'success' - 쿼리가 성공하고 데이터를 사용가능함

이런 중요한 상태들을 넘어서, 쿼리 상태에 대해 더 많은 중요한 정보들을 이용할 수 있습니다.

• error - 쿼리가 isError 상태면, error 프로퍼티를 통해 에러 객체를 사용할 수 있습니다.
• data - 쿼리가 success 상태면, 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>
  )
}

boolean 값이 싫다면 'status' 상태에서도 사용할 수 있습니다.

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

  if (status === 'loading') {
    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>
  )
}

타입스크립트는 loading, error 값에 접근하기 전에 데이터의 타입을 정확하게 줄여줄 것입니다.

FetchStatus

게다가 status 외에도, result 오브젝트에서 추가적인 fetchStatus 프로퍼티를 다음과 같은 옵션을 통해 얻을 수 있습니다.

• fetchStatus === 'fetching' - 쿼리가 현재 페치중
• fetchStatus === 'paused' - 쿼리가 페치를 원하지만 잠시 중지중
• fetchStatus === 'idle' - 쿼리가 아무것도 안하는중

Why two different states?

백그라운드 리페치와 유효기간 재검증 로직은 status 와 fetchStatus 의 모든 조합을 가능하게 만듭니다. 예를 들어,

• success 상태의 쿼리는 보통 fetchStatus의 idle 이 되지만, 백그라운드 리페치가 일어나는 중이라면 여전히 fetching 상태일 것이다.
• 데이터를 마운트하지 않는 쿼리는 loading 상태에 있고, fetchStatus의 fetching 상태에 있겠지만, 네트워크 연결이 없다면 paused 상태에 있을 것이다.

따라서 쿼리는 실질적인 데이터 페칭없이는 loading 상태에 있을 것입니다.

• status : 데이터가 있는지 없는지에 대한 정보를 줍니다.
• fetchStatus : queryFn 이 작동하는지 안하는지에 대한 정보를 줍니다.