[React, Next.js] TanStackQuery, 설치하고 리액트 코드에 적용하기!

 

실제로 서버를 운영할 생각이기에
서버 상태 관리를 위해
TanStackQuery 라이브러리를 넣어볼 생각이다.

 

 

 

 

https://lotto-magic-frontend.vercel.app/

로또 번호 생성 마법진

 

 

 

 

 

 

1. TanStackQuery

• 서버에서 받아오는 데이터를 관리해주는 라이브러리이다.
• 그 외 데이터 캐싱, 캐시 제어 등 데이터를 쉽고 효율적이게 관리해준다.
• React Query라는 이름으로 시작하지만 v4부터 Vue나 Svelte 등의 다른 프레임워크에서도 활용할 수 있도록 기능이 확장되며 TanStack Query라는 이름으로 변경되었다.
• 대표적인 기능으로 데이터 가져오기 및 캐싱 | 동일 요청의 중복 제거 | 신선한 데이터 유지 | 무한 스크롤, 페이지네이션 등의 성능 최적화 | 네트워크 재연결, 요청 실패 등의 자동 갱신이 있다.
• 데이터 캐싱
  : TanStack Query를 활용해서 데이터를 가져올 때는 항상 쿼리 키(queryKey)를 지정하게 된다. 쿼리 키와 일치하는 캐시된 데이터가 없을 때, 서버에서 새로운 데이터를 가져온다. 서버에서 데이터를 가져오면 그 데이터는 캐시되고 그 이후 요청부터는 개시된 데이터를 사용할 수 있다. 반대로 일치하는 캐시된 데이터가 있다면 서버에 요청하지 않고 캐시된 데이터를 사용한다. 같은 데이터를 가져오는 요청이 여러 번 발생해도, 캐시된 데이터를 사용하게 되어 중복 요청을 줄일 수 있다. 
• 데이터의 신선도
  : TanStack Query는 캐시한 데이터를 신선(Fresh)하거나 상한(Stale) 상태로 구분해 관리한다. 캐시된 데이터가 신선하다면 캐시된 데이터를 사용하고, 만약 데이터가 상했다면 서버에 다시 요청해 신선한 데이터를 가져온다. 데이터가 상하는 데까지 걸리는 시간은 staleTime 옵션으로 지정할 수 있다. 그리고 신선한지 상했는지 여부는 isStale로 확인할 수 있다.
• 현재 진행하고 있는 프로젝트 기준으로 MSW나 백엔드 API에서 받아오는 데이터가 있을 때 TanStack Query를 통해, 데이터 가져오기 | 로딩 상태 관리 | 에러 상태 관리 | 캐싱 | 다시 요청하기 등을 대신하게 할 수 있다.
  
  

 

 

---

 

 

 

 

2. 코드 비교로 보는 필요성

• TanStackQuery (X)

const [data, setData] = useState(null);
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState(null);

useEffect(() => {
    fetch('/api/result')
        .then((res) => res.json())
        .then((data) => {
            setData(data);
            setIsLoading(false);
        })
        .catch((err) => {
            setError(err);
            setIsLoading(false);
        });
}, []);

위의 코드를 간단히 설명해보겠다. data: null, isLoading: true, error: null 상태로 화면이 그려진다. 그리고 useEffect가 실행되면서 백엔드에 데이터를 요청한다. 첫번째 then에서 응답을 JSON 형태로 반환한다. 두번째 then에서 변환된 데이터를 setData에 넣고, setIsLoading(false)를 호출해 로딩이 끝났음을 알린다. catch로 네트워크 오류나 서버 에러가 발생하면 error 상태에 에러 내용을 저장하고 로딩을 종료한다.

프로젝트가 커지면 위의 코드처럼 로딩 상태, 에러 상태를 매번 직접 만들어줘야한다. 그래서 TanStackQuery를 써서 위의 코드를 훨씬 간단하게 만들 수 있다.

 

 

• TanStackQuery (O)

const { data, isLoading, isError } = useQuery({
    queryKey: ['result'],
    queryFn: getResult,
});

data는 서버에서 받아온 데이터가 된다. isLoading을 로딩 중인지를 나타낸다. isError는 에러가 났는지를 나타낸다. querKey는 이 데이터의 이름표고 queryFn은 실제 데이터를 가져오는 함수가 된다.

TanStackQuery를 사용하지 않았던 코드는 useState를 3개나 만들고 fetch의 성공,실패 시점마다 일일이 set함수를 호출해줘야 했다. TanStackQuery를 사용한 코드는 data, isLoading, isError 상태를 라이브러리가 내부적으로 알아서 관리하고 객체 형태로 던져준다. 개발자는 그냥 받아서 쓰기만 하면 된다.

TanStackQuery를 사용하지 않았던 코드는 컴포넌트가 나타나면 데이터를 가져오라는 식의 명령형 방식이었다. 그러나 TanStackQuery를 사용한 코드는 이 데이터는 result라는 키를 가지고 getResult 함수로 가져온다고 정의만 해두는 선언적 방식이다. 

useQuery는 동일한 키(result) 요청 시 메모리에 저장된 값을 즉시 반환(캐싱)하고 네트워크 장애 시 자동으로 여러 번 재시도를 한다. 브라우저 창을 다시 포커스하거나 네트워크가 재연결될 때 자동으로 업데이트를 하고 동일한 API 요청이 동시에 여러 개 발생해도 한 번만 호출한다.

 

 

 

 

---

 

 

 

 

 

3. TanStackQuery 설치

• TanStackQuery 설치 명령어 (npm을 사용 중인 경우)
  
  

프로젝트 내 터미널에 적는다

npm i @tanstack/react-query

 

 

• React Query Devtools 설치 (필수 아님) 

npm i @tanstack/react-query-devtools

 

개발 중에 React Query가 어떤 데이터를 캐싱하고 있는지 눈으로 보고 싶다면 Devtools를 설치하면 된다. 이는 선택사항이다!

 

 

 

 

---

 

 

 

 

4. TanStackQuery 코드 작성

• QueryProvider.tsx 파일 만들기
  
  

 

 

• QueryProvider 전체 코드

'use client';

import { ReactNode, useState } from 'react';
import {
    QueryClient,
    QueryClientProvider,
} from '@tanstack/react-query';

type QueryProviderProps = {
    children: ReactNode;
};

export default function QueryProvider({ children }: QueryProviderProps) {
    const [queryClient] = useState(
        () =>
            new QueryClient({
                defaultOptions: {
                    queries: {
                        staleTime: 1000 * 30,
                        retry: 1,
                        refetchOnWindowFocus: false,
                    },
                    mutations: {
                        retry: 0,
                    },
                },
            })
    );

    return (
        <QueryClientProvider client={queryClient}>
            {children}
        </QueryClientProvider>
    );
}

앱 전체에서 React Query를 쓸 수 있도록 QueryClientProvider로 감싸야 한다. 공식 문서에 보면 QueryClient를 만들고, QueryClientProvider로 감싸는 구조를 기본 사용법능로 안내한다. 글 맨 아래에 링크를 첨부하겠다. 그 안에 보면 각자 프로젝트에 맞춰서 설치할 수 있게 명령어도 잘 나와있다.

 

 

• 설명이 포함된 코드

'use client';

import { ReactNode, useState } from 'react';
import {
    QueryClient,
    QueryClientProvider,
} from '@tanstack/react-query';

type QueryProviderProps = {
    // 컴포넌트의 하위 요소들을 받기 위한 타입 정의
    children: ReactNode;
};

export default function QueryProvider({ children }: QueryProviderProps) {

    // QueryClient 인스턴스를 useState로 관리
    // 컴포넌트가 리렌더링될 때마다 새로운 클라인트가 생성되는 것을 막아줌
    // 초기값 생성 함수 (() = new QueryClient)를 사용하여 딱 한 번만 생성되도록 함
    const [queryClient] = useState(
        () =>
            new QueryClient({

                // 전역 기본 옵션을 설정
                defaultOptions: {
                    queries: {
                        // 데이터가 신선하다고 간주되는 시간 (30초)
                        // 이 시간 동안은 동일한 쿼리를 요청하면 캐시를 사용함
                        staleTime: 1000 * 30,
                        // 요청 실패 시 자동으로 재시도하는 횟수, 한번만 시도함
                        retry: 1,
                        // 브라우저 탭을 다시 클릭했을 때 데이터를 새로고침할지 정하는데
                        // false로 설정해서 네트워크 비용 줄임
                        refetchOnWindowFocus: false,
                    },
                    // 데이터 생성, 수정, 삭제 요청 시 옵션으로
                    // 에러 발생 시 사용자에게 바로 알리는 것이 좋다고 생각해서 재시도를 0으로 설정
                    mutations: {
                        retry: 0,
                    },
                },
            })
    );

    // Provider로 하위 컴포넌트를 감싸서 Queryclient를 공급
    return (
        <QueryClientProvider client={queryClient}>
            {children}
        </QueryClientProvider>
    );
}

 

 

• layout.tsx

    return (
        <html lang="ko">
        <body className={`${geistSans.variable} ${geistMono.variable}`}>
        <MswProvider>
            <QueryProvider>
                {children}
            </QueryProvider>

            <MagicToaster />
        </MswProvider>
        </body>
        </html>
    );
}

{children}이 QueryProvider에 감싸져 있다. children은 보통 개발자가 만든 페이지를 말한다. 지금 이 프로젝트에선 메인페이지, 로딩페이지, 결과 페이지가 children에 들어간다.

이 children을 QueryProvider로 감싸야 userQuery( ), useMutation( ), useQueryClient( )를 사용할 수 있다.

 

 

 

---

 

 

 

 

5. 메인페이지에 TanStackQuery 적용하기

• import

import { useMutation, useQuery } from '@tanstack/react-query';

 

• 선택 요소 불러오는 요청

const {
    data: optionData,
    isLoading: isLoadingOptions,
    isError: isOptionError,
} = useQuery({
    queryKey: ['lotto-options'],
    queryFn: getLottoOptions,
});

화면에 행운, 조상님의 도움 등 사용자가 요소를 선택할 수 있는 구간이 있다. 이런 요소들을 useQuery로 불러오도록 코드를 작성했다.

queryKey는 데이터의 이름으로 ReactQuery는 lotto-options라는 이름으로 관리한다. 아까 데이터의 신선하다고 판단하는 시간을 30초로 설정했다. 30초 안에 lotto-options 요청이 들어오면 React Query는 아까 가져온 데이터라고 판단하고 캐시가 있는 걸 확인한 뒤, 재활용한다. 

queryFn은 실제로 데이터를 가져오는 함수다. lotto-options 데이터를 가져올 때는 getLottoOptions 함수를 실행하도록 작성했다.

useQuery는 결과로 여러 상태를 준다. 서버에서 직접 받아오는 OptionData, 선택 요소를 가져오는 중인지 알려주는 isLoadingOptions, 데이터를 불러오다가 에러가 났는지 알려주는 isOptionsError가 있다.

 

 

• 로또 번호 생성 요청

const drawMutation = useMutation({
    mutationFn: drawLottoNumbers,

    onSuccess: (result) => {
        sessionStorage.setItem('lotto-result', JSON.stringify(result));
        router.push('/loading');
    },

    onError: (error) => {
        const message =
            error instanceof Error
                ? error.message
                : '결과를 생성하지 못했습니다.';

        showMagicToast(message);
    },
});

useMutation은 실행, 변경, 생성 요청이다. 사용자가 요소 3개를 선택하고 만들기 버튼을 누르면 실행이 된다.

mutationFn은 실제로 실행할 함수로, drawLottoNumbers 함수가 실행된다.

onSuccess는 요청이 성공하면 실행되는 부분이다. 만약 요청이 성공하면 로또 결과를 브라우저의 sessionStorage에 저장한다. 저장한 뒤 바로 로딩페이지로 보내고 결과페이지에 저장한 값을 꺼내 사용자에게 보여주도록 만들었다.

onError는 요청이 실패하면 실행되는 부분이다. 서버 요청 중에 문제가 생기면 토스트로 에러 메시지를 꺼내서 보여준다.

 

 

• 실제 실행되도록 하는 코드

    const handleCreateClick = () => {
        if (selectedOptions.length !== 3) {
            showMagicToast('요소 3가지를 선택해주세요.');
            return;
        }

        drawMutation.mutate({
            selectedOptions,
        });
    };

useMutation이 실제로 실행되는 부분이다. if문을 통과하면 drawlottoNumbers 함수에게 selectedOptions(선택한 요소)를 넘겨서 실행하도록 작성된 코드이다. 쉽게 설명하자면 사용자가 선택한 요소 3개가 API 함수로 전달되는 것이다.

만약 사용자가 행운, 내돈, 1등이필요해를 선택했다고 가정한다면, mutate로 넘어가는 값은 selectedOptions: ['행운', '내동', '1등이필요해']가 될 것이다. 그러면 drawLottoNumbers 함수가 이 값을 받아서 로또 번호 생성 요청을 처리한다.

 

 

• 중복 막기 

                    <button
                        type="button"
                        className={styles.createButton}
                        onClick={handleCreateClick}
                        disabled={drawMutation.isPending}
                    >
                        {drawMutation.isPending ? (
                            <>
                                결과 생성
                                <br />
                                중...
                            </>
                        ) : (
                            <>
                                쿵짝쿵짝
                                <br />
                                만들기
                            </>
                        )}
                    </button>

disabled={drawMutation.isPending}으로 코드를 작성해두었다. 평소에는 쿵짝쿵짝 만들기라는 버튼이 보이겠지만, 로또 번호 생성 중이면 isPending(mutation이 실행 중인지 알려주는 상태)이 true가 되면서 결과 생성 중이라고 바뀐다. 그리고 버튼을 눌리지 않게 된다. 

 

 

 

---

 

 

- TanStackQuery

Installation | TanStack Query React Docs