본문으로 건너뛰기

중요한 기본값

기본적으로 TanStack Query는 적극적이지만 합리적인 기본값으로 구성됩니다. 때로는 사용자가 이러한 기본값을 알지 못하면 신규 사용자가 당황하거나 학습/디버깅이 어려워질 수 있습니다. TanStack Query를 계속 학습하고 사용하면서 이 점을 유념하세요:

  • 기본적으로 useQuery 또는 useInfiniteQuery를 통한 Query 인스턴스는 캐시된 데이터를 stale 상태로 간주합니다.

이 동작을 변경하려면 staleTime 옵션을 사용하여 전역 및 개별 쿼리 수준에서 쿼리를 구성할 수 있습니다. 더 긴 staleTime을 지정하면 쿼리가 데이터를 다시 가져오는 빈도가 줄어듭니다.

  • staleTime이 설정된 Query는 해당 staleTime이 경과할 때까지 fresh 상태로 간주됩니다.
    • 어떤 종류의 다시 가져오기도 트리거하지 않고 2분 동안 또는 Query가 수동으로 무효화될 때까지 데이터를 캐시에서 읽도록 하려면 staleTime을 예를 들어 2 * 60 * 1000으로 설정합니다.
    • Query가 수동으로 무효화될 때까지 다시 가져오기를 절대 트리거하지 않으려면 staleTime을 Infinity로 설정합니다.
    • Query가 수동으로 무효화되더라도 다시 가져오기를 절대 트리거하지 않도록 staleTime을 'static'으로 설정합니다.

'static'과 Infinity는 둘 다 오래된 상태에 따른 다시 가져오기를 방지하지만, 'static'가 더 엄격합니다. queryClient.invalidateQueries()는 staleTime: Infinity를 사용해 쿼리를 무효화할 수 있지만 staleTime: 'static'에는 영향을 주지 않습니다. "always"로 설정된 refetchOnMount, refetchOnWindowFocus, refetchOnReconnect도 'static'에 의해 차단됩니다. 앱이 실행되는 동안 변경될 수 없는 데이터, 즉 부팅 시 가져온 기능 플래그, 로그인 시 불러온 사용자 권한, 정적 참조 테이블에는 'static'을 사용하세요. 수동 무효화가 계속 작동하기를 원한다면 Infinity를 사용하세요.

  • stale 상태인 쿼리는 다음 경우 백그라운드에서 자동으로 다시 가져옵니다:
    • 쿼리의 새 인스턴스가 마운트됩니다
    • 창이 다시 포커스됨
    • 네트워크가 다시 연결됩니다

staleTime 설정은 과도한 다시 가져오기를 방지하는 데 권장되는 방법이지만, refetchOnMount, refetchOnWindowFocus 및 refetchOnReconnect 같은 옵션을 설정하여 다시 가져오는 시점을 맞춤 설정할 수도 있습니다.

  • 쿼리에 선택적으로 refetchInterval을 구성하여 주기적인 다시 가져오기를 트리거할 수 있으며, 이는 staleTime 설정과 독립적입니다. 자세한 내용은 폴링을 참조합니다.

  • useQuery, useInfiniteQuery 또는 쿼리 옵저버의 활성 인스턴스가 더 이상 없는 쿼리 결과는 "비활성"으로 표시되며, 나중에 다시 사용될 경우를 대비해 캐시에 남아 있습니다.

  • 기본적으로 "비활성" 쿼리는 5분 후에 가비지 컬렉션됩니다.

    이를 변경하려면 쿼리의 기본 gcTime을 1000 * 60 * 5밀리초가 아닌 다른 값으로 바꿀 수 있습니다.

  • 실패한 쿼리는 오류를 포착하여 UI에 표시하기 전에 지수 백오프 지연을 적용하여 자동으로 3번 재시도됩니다.

    이를 변경하려면 쿼리의 기본 retry 및 retryDelay 옵션을 3과 기본 지수 백오프 함수가 아닌 다른 값으로 바꿀 수 있습니다.

  • 기본적으로 쿼리 결과는 데이터가 실제로 변경되었는지 감지하기 위해 구조적으로 공유되며, 변경되지 않았다면 useMemo 및 useCallback과 관련된 값 안정화를 더 효과적으로 지원하도록 데이터 참조가 변경되지 않은 채 유지됩니다. 이 개념이 생소하게 느껴져도 걱정하지 마세요! 99.9%의 경우 이를 비활성화할 필요가 없으며, 별도의 비용 없이 앱의 성능을 높여 줍니다.

구조적 공유는 JSON 호환 값에서만 작동하며, 그 밖의 값 유형은 항상 변경된 것으로 간주됩니다. 예를 들어 큰 응답으로 인해 성능 문제가 발생한다면 config.structuralSharing 플래그로 이 기능을 비활성화할 수 있습니다. 쿼리 응답에서 JSON과 호환되지 않는 값을 다루면서도 데이터가 변경되었는지 감지하려면, config.structuralSharing에 자체 사용자 지정 함수를 제공하여 이전 응답과 새 응답에서 값을 계산하고 필요에 따라 참조를 유지할 수 있습니다.

추가 자료​

기본값에 관한 자세한 설명은 커뮤니티 리소스의 다음 글을 살펴보세요: