본문으로 건너뛰기

네트워크 모드

TanStack Query는 네트워크에 연결되어 있지 않을 때 Queries와 Mutations가 어떻게 동작해야 하는지 구분하기 위해 세 가지 네트워크 모드를 제공합니다. 이 모드는 각 Query / Mutation에 개별적으로 설정하거나 쿼리 / 뮤테이션 기본값을 통해 전역으로 설정할 수 있습니다.

TanStack Query는 데이터 가져오기 라이브러리와 함께 데이터를 가져오는 데 가장 흔히 사용되므로, 기본 네트워크 모드는 온라인입니다.

네트워크 모드: 온라인​

이 모드에서는 네트워크에 연결되어 있지 않으면 쿼리와 뮤테이션이 실행되지 않습니다. 이것이 기본 모드입니다. 쿼리의 가져오기가 시작된 후 네트워크 연결이 없어 가져오기를 수행할 수 없으면, 해당 쿼리는 항상 현재의 state(pending, error, success)에 그대로 머뭅니다. 하지만 fetchStatus도 추가로 제공됩니다. 이는 다음 중 하나일 수 있습니다:

  • fetching: queryFn이 실제로 실행 중이며 요청이 처리 중입니다.
  • paused: 쿼리가 실행되고 있지 않으며, 연결이 다시 설정될 때까지 paused 상태입니다.
  • idle: 쿼리가 데이터를 가져오는 중이 아니며 일시 중지되지도 않았습니다

isFetching 및 isPaused 플래그는 이 상태에서 파생되며 편의를 위해 노출됩니다.

로딩 스피너를 표시할 때 pending 상태를 확인하는 것만으로는 충분하지 않을 수 있다는 점에 유의하세요. 쿼리가 처음 마운트되고 네트워크에 연결되어 있지 않으면 state: 'pending' 상태이지만 fetchStatus: 'paused'일 수 있습니다.

온라인 상태여서 쿼리가 실행되었지만 가져오기가 계속 진행되는 동안 오프라인 상태가 되면 TanStack Query는 재시도 메커니즘도 일시 중지합니다. 일시 중지된 쿼리는 네트워크 연결을 다시 확보하면 실행을 계속합니다. 이는 refetchOnReconnect와 무관합니다(이 모드에서는 이 값도 기본적으로 true입니다). 이는 refetch가 아니라 continue이기 때문입니다. 그동안 쿼리가 취소되었다면 계속 실행되지 않습니다.

네트워크 모드: 항상​

이 모드에서 TanStack Query는 항상 데이터를 가져오고 온라인 / 오프라인 상태를 무시합니다. 쿼리가 작동하는 데 활성 네트워크 연결이 필요하지 않은 환경에서 TanStack Query를 사용한다면 이 모드를 선택하는 것이 좋습니다. 예를 들어 AsyncStorage에서 읽기만 하거나 queryFn에서 Promise.resolve(5)를 반환하기만 하려는 경우입니다.

  • 네트워크에 연결되어 있지 않으므로 쿼리는 절대 paused되지 않습니다.
  • 재시도도 일시 중지되지 않으며, 실패하면 Query가 error 상태로 전환됩니다.
  • 이 모드에서 refetchOnReconnect의 기본값은 false입니다. 네트워크 재연결은 더 이상 stale 상태인 쿼리를 다시 가져와야 한다는 좋은 지표가 아니기 때문입니다. 원한다면 여전히 활성화할 수 있습니다.

네트워크 모드: offlineFirst​

이 모드는 처음 두 옵션의 중간 지점으로, TanStack Query가 queryFn을 한 번 실행한 다음 재시도를 일시 중지합니다. 오프라인 우선 PWA처럼 캐싱을 위해 요청을 가로채는 serviceWorker가 있거나 Cache-Control 헤더를 통해 HTTP 캐싱을 사용하는 경우 매우 유용합니다.

이러한 상황에서는 첫 번째 가져오기가 오프라인 저장소/캐시에서 이루어지므로 성공할 수 있습니다. 하지만 캐시 미스가 발생하면 네트워크 요청이 전송되었다가 실패하며, 이 경우 이 모드는 online 쿼리처럼 동작하여 재시도를 일시 중지합니다.

DevTools​

네트워크 연결이 없어 가져오기를 수행할 수 없는 경우 TanStack Query DevTools는 쿼리를 paused 상태로 표시합니다. _오프라인 동작 모의 실행_을 위한 토글 버튼도 있습니다. 이 버튼은 실제로 네트워크 연결에 영향을 주지 않으며(이는 브라우저 DevTools에서 수행할 수 있습니다), OnlineManager를 오프라인 상태로 설정한다는 점에 유의하세요.

시그니처​

  • networkMode: 'online' | 'always' | 'offlineFirst'
    • 선택 사항
    • 기본값은 'online'입니다