Tanstack Query: 리액트 친화적인 비동기 상태 관리 툴에 대한 집중 분석

Tanstack Query 의 철학

Powerful asynchronous state management for TS/JS, React, Solid, Vue, Svelte and Angular

1. 지저분한 상태 관리

2. 수동 리패칭

3. 비동기 스파게티 코드

Tanstack Query 의 특징

DECLARATIVE & AUTOMATIC

💡 과정을 표현하는 절차형이 아니라, 원하는 결과를 표현하는 선언형 패러다임과 더불어 상태 관리에 필요한 각종 부수작업들을 알아서 처리해줍니다.

SIMPLE & FAMILIAR

💡 비동기를 처리할 수 있는 최신 JS 문법에 잘 어우러지고, 무겁고 복잡한 설정 코드를 작성할 필요가 없으므로 코드 표현이 간결해집니다.

EXTENSIBLE

💡 격리된 블랙박스로 인해 다른 영역에 영향을 끼치지 않으므로 모듈성이 좋으며, 비동기 상태 관리를 위한 여러가지 세부 설정이 가능해서 다양한 경우에 맞춰 유연하게 사용할 수 있습니다.

그 외 특징들

Tanstack Query의 동기

TanStack Query (FKA React Query) is often described as the missing data-fetching library for web applications, but in more technical terms, it makes fetching, caching, synchronizing and updating server state in your web applications a breeze.

1. 당신이 통제할 수 없는 원격에서 존재합니다.

2. 패칭과 업데이트를 위해서는 비동기 API가 필요합니다.

3. 공동 소유로 인해, 다른 사람에 의해 암시적으로 변경될 수 있습니다.

4. 조심하지 않으면 잠재적으로 오래된 데이터가 되기 십상입니다.

1. 캐싱

2. 요청 최적화 (동일한 요청이 동시다발적으로 발생하는 경우라던지)

3. 오래된 데이터를 백그라운드에서 업데이트

4. 데이터가 언제 낡아지는지 판단하기

5. 데이터 갱신을 최대한 빠르게 반영하기

6. 페이지네이션 및 레이지 로딩과 같은 성능 최적화

7. 메모리 관리와 가비지 컬렉팅

8. 구조적 공유를 통해 쿼리를 메모이징

1. 복잡하고 오해하기 쉬운 코드들을 간단한 몇줄의 코드로 대체할 수 있어 코드가 간결해집니다.

2. 유지보수성을 높여주고, 새로운 서버 상태를 클라이언트 상태와 연결할 때 걱정을 하지 않아도 됩니다.

3. 사용자로 하여금 어플리케이션이 더욱 빠르다고 느끼게 해주며, 더 반응성이 좋아집니다.

4. 대역폭을 절약하고 메모리 성능을 향상시킬 가능성을 제공합니다.

React와의 호환성

훅의 형태로 기능을 제공

Hook을 통해 서로 비슷한 것을 하는 작은 함수의 묶음으로 컴포넌트를 나누는 방법을 사용할 수 있습니다.

컴포넌트 구조에 맞춰짐

스스로 상태를 관리하는 캡슐화된 컴포넌트를 만드세요. 그리고 이를 조합해 복잡한 UI를 만들어보세요.

// 여기서는 글 목록만!
function PostList() {
	const { data: postList } = useQuery({
	  queryKey: ['post'],
	  queryFn: fetchPostList,
	});
}

// 여기서는 글만!
function Post(props) {
	const { id, img } = props;
	const { data: post } = useQuery({
	  queryKey: ['Post', id],
	  queryFn: fetchPost,
	});
}

React의 Suspense 와 함께 사용이 가능

function useBaseQuery(...) {
  // Handle suspense
  if (shouldSuspend(defaultedOptions, result)) {
    throw fetchOptimistic(defaultedOptions, observer, errorResetBoundary)
  }
}

구조적 공유

❓ <a href="https://tanstack.com/query/latest/docs/framework/react/guides/render-optimizations#structural-sharing">구조적 공유</a>란? 낡은 서버 상태와 새로운 서버 상태를 비교할 때, 이전 상태를 최대한 많이 유지하려고 하는 전략입니다. JSON 형태로 직렬화 가능한 데이터에 대해, 변경이 없는 부분은 얕은 복사를 통해 레퍼런스를 유지하여 리렌더링을 방지합니다.

Context API와의 통합

🚨 QueryClient 는 참조-안전하게 사용하길 권장합니다. 가장 좋은 방법은 App 외부에 쿼리 클라이언트 인스턴스를 생성하는 것입니다. (<a href="https://tkdodo.eu/blog/react-query-fa-qs#2-the-queryclient-is-not-stable">참고</a>)

간단하게 쓰기 쉽지만 잘 쓰긴 쉽지 않음 (개인적인 생각)

Deep Dive

❗ 공식 문서에 나와있는 예제는 여기서 설명하지 않도록 하겠습니다.

1. 쿼리 키를 대하는 자세

Treat the query key like a dependency array

• 의존성 배열이 바뀌면 훅이 동작하는 것 처럼, 쿼리 키가 바뀌면 리패치 함수가 불립니다.

• 로컬 상태에 의존하는 쿼리 함수에 대해, 둘을 동기화해줍니다. 마치 useEffect 내부의 로직이 의존성 배열의 상태와 동기화되는 것 처럼요.

2. initialData를 이용해 매끄럽게 화면 바꾸기

type State = 'all' | 'open' | 'done';
type Todo = {
  id: number
  state: State
};
type Todos = ReadonlyArray<Todo>;

const fetchTodos = async (state: State): Promise<Todos> => {
  const response = await axios.get(`todos/${state}`)
  return response.data
};

const useTodosQuery = (state: State) =>
  useQuery({
    queryKey: ['todos', state],
    queryFn: () => fetchTodos(state),
    initialData: () => {
      const allTodos = queryClient.getQueryData<Todos>([
        'todos',
        'all',
      ])
      const filteredData =
        allTodos?.filter((todo) => todo.state === state) ?? []

      return filteredData.length > 0 ? filteredData : undefined
    },
  });

3. 서버 상태와 클라이언트 상태를 분리하라

    const App = () => {
      const { data } = useQuery({
        queryKey: ['key'],
        queryFn,
        staleTime: Infinity,
      })

      return data ? <MyForm initialData={data} /> : null
    }

    const MyForm = ({ initialData }) => {
      const [data, setData] = React.useState(initialData)
      ...
    }

4. 쿼리 캐시를 로컬 상태 매니저로 사용하지 마라

🚨 추가로, setQueryData 를 사용하는 경우 쿼리 키가 반드시 정확히 일치해야 합니다. (<a href="https://tkdodo.eu/blog/react-query-fa-qs#1-query-keys-are-not-matching">참고</a>)

5. 단순한 래핑 함수라도 유용할 수 있다

// 2번에 나온 예제 코드
const useTodosQuery = (state: State) =>
  useQuery({
    queryKey: ['todos', state],
    queryFn: () => fetchTodos(state),
  });

• 데이터 패칭 로직을 UI와 분리할 수 있습니다.

• 쿼리를 다루는 로직들을 하나의 파일에서 관리할 수 있습니다.

• 변경이 필요할 때, 수고가 덜 듭니다.

6. 서버 상태를 변형하기

// 패치 함수 내에서 서버 상태를 변형하는 경우
const fetchTodos = async (): Promise<Todos> => {
  const response = await axios.get('todos')
  const data: Todos = response.data

  return data.map((todo) => todo.name.toUpperCase())
};

const useTodosQuery = () =>
  useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  });

// select 옵션을 이용해 서버 상태를 변형하는 경우
const useTodosQuery = (select) =>
  useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    select,
  });

const useTodosCount = () => useTodosQuery((data) => data.length);
const useTodo = (id) => useTodosQuery((data) => data.find((todo) => todo.id === id));

7. 극한으로 리렌더링 최적화하기

💡 저자는 “불필요한 리렌더링” 보다, “필요한 리렌더링을 놓치는 것”을 더 경계라하고 조언합니다.

{ status: 'success', data: 2, isFetching: true }
{ status: 'success', data: 2, isFetching: false }

8. 쿼리 상태 확인하기

• success : 쿼리가 성공해서 data 가 존재하는 경우

• error : 쿼리가 실패해서 error 가 존재하는 경우

• pending : 캐시된 데이터가 없고, 쿼리가 아직 완료되지 않은 경우

• isStale : 캐싱된 데이터가 invalidate 하거나, staleTime 이 지나버린 경우 true

• fetching : 초기 pending 상태를 포함해서, 패칭 함수가 실행중이거나 백그라운드 리패칭이 실행중인 경우 true

• paused : 네트워크 오프라인등의 이유로 쿼리 함수를 진행할 수 없는 경우 true. 만약 네트워크가 연결되면 자동으로 패칭을 재시도함.

• idle : 쿼리가 일시정지되지 않았으면서, 패칭중이 아닐 때 true

• isRefetching : 초기 pending 상태를 제외하고, 백그라운드 리패칭이 실행중인 경우 true

🚨 success 상태와 error 상태는 상호배타적이라고 생각하기 쉽지만, 일부 경우에는 공존이 가능합니다. (<a href="https://tkdodo.eu/blog/status-checks-in-react-query#background-errors">참고</a>) 저자는 이런 경우 재시도 메커니즘에 의해 안좋은 유저 경험을 제공할 수 있으므로, 데이터 이용가능성을 우선적으로 확인하는 것을 권장합니다.

8. 기본 에러 타입 지정하기

declare module '@tanstack/react-query' {
  interface Register {
    defaultError: AxiosError
  }
}

9. Typescript 에서 안전하게 쿼리 비활성화하기

import { useQuery, skipToken } from '@tanstack/query'

// id가 유효한 경우에만 패치 함수를 실행
function useGroup(id: number | undefined) {
  return useQuery({
    queryKey: ['group', id],
    queryFn: () => fetchGroup(id),
    enabled: Boolean(id),
  })
}

// 마찬가지로 id가 유효한 경우에만 패치 함수를 실행
function useGroup(id: number | undefined) {
  return useQuery({
    queryKey: ['group', id],
    queryFn: id ? () => fetchGroup(id) : skipToken,
  })
}

10. 효과적인 쿼리 키

This is not only error-prone, but it also makes changes harder in the future

const todoKeys = {
  all: ['todos'] as const,
  lists: () => [...todoKeys.all, 'list'] as const,
  list: (filters: string) => [...todoKeys.lists(), { filters }] as const,
  details: () => [...todoKeys.all, 'detail'] as const,
  detail: (id: number) => [...todoKeys.details(), id] as const,
}

// 🕺 remove everything related to the todos feature
queryClient.removeQueries({
  queryKey: todoKeys.all
})

// 🚀 invalidate all the lists
queryClient.invalidateQueries({
  queryKey: todoKeys.lists()
})

// 🙌 prefetch a single todo
queryClient.prefetchQueries({
  queryKey: todoKeys.detail(id),
  queryFn: () => fetchTodo(id),
})

11. 동기적으로 쿼리 캐시 미리 채워놓기

• placeholderData

• initialData

function Component() {
  // ✅ status will be success even if we have not yet fetched data
  const { data, status } = useQuery({
    queryKey: ['number'],
    queryFn: fetchNumber,
    placeholderData: 23,
  })

  // ✅ same goes for initialData
  const { data, status } = useQuery({
    queryKey: ['number'],
    queryFn: fetchNumber,
    initialData: () => 42,
  })
}

1. initialData 는 캐시에 영속적으로 존재하며, placeholderData 는 캐시에 영속적으로 존재하지 않습니다.
1. 하나의 쿼리 클라이언트는 하나의 캐시 엔트리를 가지므로, 특정 쿼리 키에 initialData 가 설정된다면, 이후 설정값은 무시됩니다.
2. 반면 placeholderData 는 (컴포넌트 별로) 하나의 쿼리 키에 여러 값을 지닐 수 있습니다.

2. placeholderData 는 가짜 값이기 때문에 항상 백그라운드 리패칭이 수행되며, 실제 쿼리 데이터가 받아와지면 교체됩니다. 반면에 initialData 는 진짜 값이기 때문에 staleTime 설정에 따라 백그라운드 리패칭이 수행되지 않을 수 있습니다.

💡 저자의 추천 방식! 다른 쿼리로부터 초기 값을 설정해야 할 땐 <code>initialData</code> 를, 그 외엔 <code>placeholderData</code> 를 쓴다고 합니다.

🚨 <code>initialData</code> 는 기본적으로 신선한 데이터로 판단하기 때문에, 낡아지는 시점을 잘 지정해주는게 좋습니다. 만약 쿼리 캐시로부터 <code>initialData</code> 를 설정한다면, <code>initialDataUpdatedAt</code> 속성을 같이 지정해주세요.

12. 쿼리 키 변경 시, 매끄럽게 화면 바꾸기

function App() {
  const [query, setQuery] = useState('');
  const deferredQuery = useDeferredValue(query);

  return (
    <>
      <label>
        Search albums:
        <input value={query} onChange={e => setQuery(e.target.value)} />
      </label>
      <Suspense fallback={<h2>Loading...</h2>}>
        <SearchResults query={deferredQuery} />
      </Suspense>
    </>
  );
}

function SearchResults({ query }) {
	const { data: albums } = useSuspenseQuery({
	  queryKey: [...],
	  queryFn: () => fetchAlbums(query),
	});

  return (
    <ul>
      {albums.map(album => (
        <li key={album.id}>
          {album.title} ({album.year})
        </li>
      ))}
    </ul>
  );
}

import { keepPreviousData } from '@tanstack/react-query'

const { data, isPlaceholderData } = useQuery({
  queryKey: ['item', id],
  queryFn: () => fetchItem({ id }),
  // ⬇️ like this️
  placeholderData: keepPreviousData,
})

13. 에러를 핸들링하는 세가지 방법

1. 훅을 호출하는 주체가 에러를 보고 처리하는 방법

2. 에러를 던지는 방법

3. 에러 콜백을 이용하는 방법

// 훅을 호출하는 주체가 에러를 직접 처리하는 방법
function TodoList() {
  const todos = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos
  })

	// isError 를 이용해 판단할 수도 있지만, 8번의 "데이터 이용가능성"을 확인하는게 더 좋습니다.
  if (todos.isError) {
    return 'An error occurred'
  }
}

// 에러를 던지는 방법
function TodoList() {
  const todos = useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    // 해당 옵션에 true 를 주거나,
    throwOnError: true,
    // 함수를 줄 수 있습니다.
	  throwOnError: (error) => error.response?.status >= 500,
  })
}

// 에러 콜백을 이용하는 방법
const useTodos = () =>
  useQuery({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    // ⚠️ looks good, but is maybe _not_ what you want
    onError: (error) =>
      toast.error(`Something went wrong: ${error.message}`),
  })

const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error) =>
      toast.error(`Something went wrong: ${error.message}`),
  }),
})

14. mutation 하는 방법

useQuery is declarative, useMutation is imperative.

function AddComment({ id }) {
  const addComment = useMutation({
    mutationFn: (newComment) =>
      axios.post(`/posts/${id}/comments`, newComment),
  })

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault()
        addComment.mutate(
          new FormData(event.currentTarget).get('comment')
        )
      }}
    >
      <textarea name="comment" />
      <button type="submit">Comment</button>
    </form>
  )
}

// 캐시 무효화
const useAddComment = (id) => {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: ...,
    onSuccess: () => {
      // ✅ refetch the comments list for our blog post
      queryClient.invalidateQueries({
        queryKey: ['posts', id, 'comments']
      })
    },
  })
}

// 직접 캐시 업데이트
const useUpdateTitle = (id) => {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: ...,
    // 💡 response of the mutation is passed to onSuccess
    onSuccess: (newPost) => {
      // ✅ update detail view directly
      queryClient.setQueryData(['posts', id], newPost)
    },
  })
}

💡 onSuccess 함수는 async 함수를 받을 수 있습니다. 만약 쿼리 무효화를 기다리게 하고 싶다면, invalidateQueries가 반환하는 프로미스를 다시 반환하세요.

💡 프로미스를 반환하는 mutateAsync 함수도 있습니다.

15. Tanstack Query의 생명주기

1. 컴포넌트가 마운트되면 컴포넌트 함수가 호출되며, 훅이 호출됩니다.

2. 훅은 쿼리 옵저버를 생성하고, 옵저버는 쿼리 캐시 내부에 존재하는 쿼리를 구독합니다. (만약 쿼리가 없다면 생성합니다.)

3. 쿼리는 패치 함수를 호출하고, 이 과정에서 쿼리의 메타데이터 및 상태가 변합니다. 쿼리 옵저버는 이 변화를 감지합니다.

4. 변화를 감지한 옵저버는 컴포넌트를 리렌더링시킵니다.

5. 쿼리가 패칭을 완료하면, 옵저버에게 변경을 알려주고, 옵저버는 컴포넌트를 리렌더링합니다.

참고