🔥 네트워크 모드
TanStack Query는 네트워크 연결이 없을 때 쿼리와 변이가 어떻게 동작해야 하는지를 구분하기 위해 세 가지 다른 네트워크 모드를 제공합니다. 이 모드는 각 쿼리나 변이에 대해 개별적으로 설정하거나 쿼리/변이 기본값을 통해 전역적으로 설정할 수 있습니다.
TanStack Query는 주로 데이터 가져오기 라이브러리와 함께 사용되므로, 기본 네트워크 모드는 온라인입니다.
네트워크 모드: 온라인(online)
이 모드에서는 네트워크 연결이 있을 때만 쿼리와 변이가 실행됩니다. 이는 기본 모드입니다. 쿼리에 대한 가져오기가 시작되면, 네트워크 연결이 없어 가져오기를 할 수 없는 경우 항상 현재 상태(대기 중, 오류, 성공)를 유지합니다. 하지만 추가로 fetchStatus가 노출됩니다. 이는 다음 중 하나일 수 있습니다:
fetching: queryFn이 실제로 실행 중입니다 - 요청이 진행 중입니다.paused: 쿼리가 실행되지 않습니다 - 다시 연결될 때까지 일시 중지됩니다.idle: 쿼리가 가져오지 않고 일시 중지되지 않았습니다.
isFetching과 isPaused 플래그는 이 상태에서 파생되며 편의를 위해 노출됩니다.
로딩 스피너를 표시하기 위해 대기 중(pending) 상태만 확인하는 것으로는 충분하지 않을 수 있다는 점을 명심하세요. 쿼리가 처음 마운트되고 네트워크 연결이 없는 경우, 상태는 'pending'이지만 fetchStatus는 'paused'일 수 있습니다.
온라인 상태에서 쿼리가 실행되지만 가져오기가 진행되는 동안 오프라인 상태가 되면, TanStack Query는 재시도 메커니즘도 일시 중지합니다. 일시 중지된 쿼리는 네트워크 연결이 다시 생기면 계속 실행됩니다. 이는 refetchOnReconnect(이 모드에서도 기본적으로 true)와는 독립적입니다. 왜냐하면 이는 다시 가져오는 것이 아니라 계속하는 것이기 때문입니다. 그 사이에 쿼리가 취소된 경우에는 계속되지 않습니다.
네트워크 모드: 항상(always)
이 모드에서 TanStack Query는 항상 가져오기를 수행하고 온라인/오프라인 상태를 무시합니다. 이는 TanStack Query를 쿼리 작동을 위해 활성 네트워크 연결이 필요 없는 환경에서 사용하는 경우 선택하고 싶은 모드일 것입니다. 예를 들어, AsyncStorage에서 읽기만 하거나 queryFn에서 Promise.resolve(5)만 반환하려는 경우입니다.
- 네트워크 연결이 없어도 쿼리가 일시 중지되지 않습니다.
- 재시도도 일시 중지되지 않습니다 - 쿼리가 실패하면 오류 상태로 전환됩니다.
- 이 모드에서는 refetchOnReconnect의 기본값이 false입니다. 네트워크에 다시 연결되는 것이 더 이상 오래된 쿼리를 다시 가져와야 한다는 좋은 지표가 아니기 때문입니다. 원한다면 여전히 켤 수 있습니다.
네트워크 모드: 오프라인 우선(offlineFirst)
이 모드는 처음 두 옵션의 중간 지점으로, TanStack Query가 queryFn을 한 번 실행한 다음 재시도를 일시 중지합니다. 이는 오프라인 우선 PWA에서처럼 캐싱을 위해 요청을 가로채는 서비스 워커가 있거나 Cache-Control 헤더를 통해 HTTP 캐싱을 사용하는 경우에 매우 유용합니다.
이러한 상황에서는 첫 번째 가져오기가 오프라인 저장소/캐시에서 오기 때문에 성공할 수 있습니다. 그러나 캐시 미스가 발생하면 네트워크 요청이 나가고 실패할 것입니다. 이 경우 이 모드는 온라인 쿼리처럼 동작하여 재시도를 일시 중지합니다.
개발 도구
TanStack Query 개발 도구는 쿼리가 가져오기를 수행하려 하지만 네트워크 연결이 없는 경우 일시 중지 상태로 표시합니다. 또한 '오프라인 동작 모의(Mock)'를 위한 토글 버튼도 있습니다. 이 버튼은 실제로 네트워크 연결을 건드리지 않는다는 점을 주의하세요(브라우저 개발 도구에서 할 수 있습니다). 대신 OnlineManager를 오프라인 상태로 설정합니다.
문법
networkMode: 'online' | 'always' | 'offlineFirst'- 선택 사항
- 기본값은 '
online'입니다.