리액트 쿼리의 StaleTime과 CacheTime

* 이 글은 2023년 11월 6일 업데이트되었습니다.

 

이 글은 TanStack Query v4를 기준으로 작성되었습니다.

2023년 11월 6일 기준 최신 버전인 v5에서는 cacheTime → gcTime으로 변경된 것을 참고해 주시기 바랍니다.

 

리액트 쿼리를 처음 사용할 때 헷갈릴 수 있는 개념 중 하나인 staleTime과 cacheTime에 대해 알아보도록 하겠습니다.

 

✎  staleTime

stale의 사전적 정의는 [신선하지 않은, (만든 지) 오래된]입니다.

말 그대로 staleTime은 데이터가 신선한 상태로 남아 있는 시간을 말합니다. 리액트 쿼리에서의 기본 값은 0입니다. 데이터를 페치해 오자마자 신선하지 않다고 간주하는 것이죠.

 

리액트 쿼리에서 데이터는 fresh한 데이터일 수도, stale한 데이터일 수도 있습니다.

fresh한 데이터라면, API 호출 없이 저장된(캐싱된) 데이터가 다시 사용됩니다.

stale한 데이터라면, 윈도우에 다시 포커스되었을 때나, 컴포넌트가 다시 마운트될 때나, 네트워크가 다시 연결되었을 때 등의 트리거가 발생했을 때 신선한 데이터를 다시 페치해 올 것입니다.

 

여기서 주목해야 할 점은 staleTime이 경과하더라도 네트워크 요청이 바로 이루어지는 것이 아니라, background refresh가 일어나기 위해서는 트리거가 필요하다는 점입니다.

 

 

✎  cacheTime

cacheTime은 비활성화된 쿼리가 캐시에서 삭제될 때까지의 시간을 말합니다. 리액트 쿼리에서의 기본 값은 300000으로, 5분입니다. 쿼리는 등록된 옵저버가 없는 즉시 삭제됩니다.

 

이 말은 즉슨, 해당 쿼리를 사용하는 모든 컴포넌트가 마운트 해제되는 시점에서 비활성 상태로 전환된다는 뜻입니다. 쉽게 말하자면 A 쿼리를 사용하는 모든 컴포넌트가 현재 사용자가 보고 있는 화면에 없다면 A 쿼리는 비활성화된 쿼리입니다.

 

캐싱 데이터를 사용할 수 있는 시간과 혼동될 수 있습니다. cacheTime의 개념에서 주의해야 할 부분은 cacheTime은 쿼리가 사용되고 있을 때는 아무것도 하지 않는다는 점입니다. 웹 페이지를 열고 그 페이지에서 영원히 작업할 수도 있습니다. 그럴 경우에 cacheTime은 리액트 쿼리의 동작 방식에 어떤 영향도 끼치지 않는다는 겁니다. cacheTime은 사용되지 않는 데이터를 삭제하는 것이기 때문에 가비지 콜렉션과 연관이 있습니다. 그래서 cacheTime은 5 버전부터는 gcTime으로 이름이 변경되었습니다.

 

 

 

✎ staleTime은 cacheTime보다 작게 설정하는 것이 좋다?

 

그런데 제가 올린 stack overflow의 질문 글을 살펴보면, staleTime을 cacheTime보다 길게 설정하는 것은 비합리적이라는 코멘트를 확인할 수 있습니다.

 

이와 같은 상황을 리액트 쿼리의 maintainer인 TkDodo는 staleTime이 Infinity, cacheTime이 0일 때의 예시를 들어 설명합니다. 이것은 기본적으로 캐시에 저장된 데이터가 있다면 데이터를 절대 refetch 하지 않고, 캐시에 있는 데이터가 사용되지 않는 즉시 바로 삭제된다고 합니다.

 

외에도 cacheTime을 staleTime보다 길게 설정해야 한다는 의견을 다른 블로그에서도 볼 수 있었는데요. 

 

 

 

 

위의 예시처럼 staleTime을 Infinity, cacheTime을 0으로 설정한다면 쿼리가 비활성화되는 즉시 캐시 데이터는 삭제됩니다.

그렇기 때문에 staleTime이 Infinity이기 때문에 설정 값만 보면 캐시에 저장된 데이터를 영구히 사용할 수 있는 것처럼 보이지만, 쿼리가 다시 활성화되는 경우에는 네트워크 요청이 필요하게 됩니다.

 

따라서, staleTime을 cacheTime보다 길게 설정하면, 설정한 staleTime보다 더 짧은 시간 안에 데이터를 다시 가져와야 하는 상황이 생기게 됩니다. 이러한 상황으로 인해, 리액트 쿼리의 time 설정을 효율적으로 사용하는 것이 어려워질 수도 있습니다.

 

 

✎  staleTime이나 cacheTime, 언제 조정하면 좋을까?

 

TkDodo는 cacheTime을 변경하는 경우는 거의 없었고, time 설정 중 하나를 조정하는 경우에는 보통 staleTime을 조정하여 해결했다고 합니다.

 

리액트 쿼리를 사용하면서 느꼈던 단점 중 하나는 (기본 설정으로 사용하는 경우) 네트워크 요청 횟수가 많아진다는 점이었습니다. 만일 변경이 자주 일어나지 않는 데이터라면, staleTime을 조정하여 불필요한 네트워크 요청 횟수를 줄여 사용할 수 있을 것입니다. 그러나 사용하는 데이터가 자주 변경되는 데이터라면, 기본 설정을 바꾸지 않는 걸 추천합니다. 

 

예를 들면 변경할 수 있는 사용자가 로그인한 유저 단 한 명일 경우(개인의 투두 리스트를 관리하는 경우, 프로필 수정 등)에는 staleTime을 Infinity로 설정하고, POST/UPDATE/DELETE 이벤트가 발생했을 경우에만 쿼리 무효화를 통해 새로운 데이터를 갱신하여 불필요한 HTTP Request 요청을 줄이고 효과적으로 서버 데이터를 관리할 수 있겠습니다.

 

 

 

 

✎  참고

Caching Examples | React Query | TanStack

Why cacheTime in React Query should always be bigger than staleTime

if staleTime is bigger than cacheTime in react query, what happen? - Stack Overflow

Practical React Query | TkDodo's blog