[피드줍줍] 피드백 데이터 동기화 문제 트러블 슈팅

우디(박연기)·2025년 9월 16일
우테코피드줍줍
post-thumbnail

피드줍줍 이용하기

1. 문제 상황

관리자 페이지에서 피드백 처리나 삭제를 하면 서버에 API 요청을 보내고, 낙관적 업데이트를 적용한 뒤 오류 시 되돌리는 방식을 사용하고 있었다.
하지만 이렇게 하면 다른 컴포넌트에서 피드백 리스트와 연관된 데이터(패널의 완료·미처리 건수, 총 건의 수)가 갱신되지 않는 문제가 발생했다.

몹프로그래밍을 하면서 POST 요청 이후에는 대부분 리패칭이 필요하다는 점을 알게 되었고, 이를 위해 리패칭 함수를 만들기로 했다

피드백 상태 변경되어도 통계가 변경되지 않는 문제

2. 한계점

피드백 리스트는 무한 스크롤 구조로 되어 있어, 데이터를 불러올 때마다 서버에서 hasNext와 nextCursorId를 받아 상태로 저장한다.

const fetchMore = async (size: number = DEFAULT_SIZE) => {
  const response = await apiClient.get<{ data: ResponseData }>(requestUrl);
  const responseData = response.data;

  setItems((prev) => [...prev, ...responseData[key]]);
  setHasNext(responseData.hasNext);
  setCursorId(responseData.nextCursorId);
};

문제는 리패칭을 하려면 처음부터 현재 페이지까지 전부 요청해야 한다는 점이다.

예를 들어, 10번의 무한스크롤 요청이 있었다면 리패칭 시 10번의 API 호출을 순차적으로 해야 한다.

이 경우 POST 요청 이후 데이터를 다시 불러오는 동안 긴 로딩 상태가 발생한다.

이를 해결하기 위해 매 요청 시 받은 nextCursorId를 useRef로 따로 저장하는 방법을 고려했다. 이렇게 하면 리패칭 시 상태값 대신 참조값을 이용해, 이전 페이지들의 커서 아이디를 추적할 수 있다.

하지만 이 방식도 다음과 같은 문제를 가진다.

  • 구현 복잡도가 높음 (페이지 수만큼 요청 반복)
  • 로딩 상태가 길어져 UX 저하
  • 피드백 리스트뿐 아니라 POST 요청이 있는 모든 API에 대해 리패칭 로직을 별도로 구현해야 하는 번거로움

이런 한계를 보완하기 위해, 이전 데이터를 캐싱해 두고 리패칭 중에는 캐싱된 데이터를 우선 보여주는 방법도 고민했다.

이렇게 하면 사용자는 로딩 없이 기존 화면을 볼 수 있고, 백그라운드에서 새로운 데이터를 받아온 뒤 교체할 수 있다.

다만, 이 역시 캐싱 로직을 직접 구현해야 하고, API별로 별도의 캐싱·리패칭 처리가 필요해 중복 코드와 유지보수 부담이 커질 수 있다.

3. Tanstack Query 필요성

이러한 문제를 해결하기 위해 Tanstack Query를 도입하게 되었다.

Tanstack Query는 다음과 같은 이점을 제공한다.

  • 자동 캐싱 및 동기화: 서버 상태를 캐싱하고, 변경 시 자동으로 최신 상태로 동기화
  • 간단한 리패칭: 특정 키로 데이터를 관리해 POST, PUT, DELETE 이후 해당 키의 데이터만 손쉽게 invalidate & refetch 가능
  • UI 로딩 최소화: 기존 데이터는 유지하면서 백그라운드에서 새로운 데이터를 불러오기 때문에 사용자 경험 향상
  • 중복 코드 감소: API마다 별도의 리패칭 로직을 작성할 필요 없이, invalidateQueries 한 줄로 동일 로직 처리

결과적으로 Tanstack Query를 사용하면 낙관적 업데이트와 리패칭 문제를 단순화할 수 있고,

무한스크롤 데이터도 기존 데이터를 유지한 채 새 데이터를 가져오는 UX를 구현하기가 훨씬 수월해진다.

4. 초기 세팅

  1. @tanstack/react-query 와 @tanstack/react-query-devtools를 다운받는다.

    • react-query-devtools은 리액트 쿼리 개발 도구를 지원한다.

    • react-query-devtools 사용법 보기

      기본적으로 npm run dev로 실행하면 오른쪽 하단에 야자수 아이콘이 생성된다.

      해당 버튼을 클릭하면 현재 캐싱되고 있는 데이터 목록을 보여준다.

      배열로 들어가 있는 값들이 캐싱 키값이다. 해당 리스트를 클릭하면 아래와 같이 보이게 된다.

      캐싱된 데이터를 확인할 수 있고 useQuery를 사용할 때 설정한 세팅값도 확인할 수 있다.

  2. index.tsx에 사용

    root.render(
	**// QueryClientProvider 사용**
  <QueryClientProvider client={queryClient}> 
  
    <ErrorModalProvider>
      <ThemeProvider theme={theme}>
        <Sentry.ErrorBoundary>
          <ModalProvider>
            <RouterProvider router={router} />
            
            **// 개발 환경일 때만 ReactQueryDevtools 사용**
            {process.env.NODE_ENV === 'development' && (
              <ReactQueryDevtools initialIsOpen={false} />
            )}
            
          </ModalProvider>
        </Sentry.ErrorBoundary>
      </ThemeProvider>
    </ErrorModalProvider>
  </QueryClientProvider>
);

5. useQuery와 useInfinityScroll 사용

현재 데이터 동기화가 필요한 피드백 리스트 불러오기(무한 스크롤)과 조직 통계 가져오는 것(일단 get)을 useQuery와 useInfinityScroll을 이용하여 수정해보자.

useQuery

export default function useUserOrganizationsStatistics() {
  const [statistics, setStatistics] = useState<StatisticsProps>({
    reflectionRate: '0',
    confirmedCount: '0',
    waitingCount: '0',
    totalCount: '0',
  });

  useEffect(() => {
    const getData = async () => {
      const response = (await getOrganizationStatistics({
        organizationId: 1,
      })) as GetOrganizationStatistics;
      setStatistics(response.data);
    };

    getData();
  }, []);

  return { statistics };
}
const EMPTY: StatisticsProps = {
  reflectionRate: '0',
  confirmedCount: '0',
  waitingCount: '0',
  totalCount: '0',
};

export default function useUserOrganizationsStatistics() {
  const { data = EMPTY } = useQuery({
    queryKey: ['organizationStatistics', 1],
    queryFn: () => getOrganizationStatistics({ organizationId: 1 }),
    select: (res: GetOrganizationStatistics) => res.data,
  });

  return { statistics: data };
}

이전에는 useEffect를 사용해 마운트 시 데이터를 가져오고, useState로 직접 상태를 관리했지만, useQuery를 사용하면 훨씬 간단하고 직관적인 코드로 변경할 수 있다.

useQuery는 다음과 같이 동작한다.

  1. 훅 호출 시 즉시 queryFn 실행
  2. 캐시된 데이터가 있으면 먼저 반환 후, 백그라운드에서 최신 데이터 패칭
  3. 캐시가 없으면 로딩 상태를 거쳐 패칭 후 반환

useQuery 주요 옵션

  1. queryKey

    • 캐싱과 식별에 사용되는 고유 키
    • 동일한 queryKey로 호출 시, 이미 캐싱된 데이터를 반환
    • 리패칭 시에도 이 키를 사용

    queryKey와 동일하게 저장된 모습

  2. queryFn

    • 실제 데이터 패칭 함수
    • 기존 API 호출 로직을 그대로 사용 가능

  3. select

    • queryFn의 반환값을 가공할 수 있는 콜백
    • 현재 서버 응답 구조상 res.data만 추출하여 필요한 데이터 형태로 반환

useInfinityScroll

import { useInfiniteQuery } from '@tanstack/react-query';
import { apiClient } from '@/apis/apiClient';
import { ApiResponse } from '@/types/notification.types';

const DEFAULT_SIZE = 10;
const MAX_RETRY_COUNT = 3;

interface UseCursorInfiniteScrollParams<Key extends string> {
  url: string; // 예: /api/items?foo=bar
  key: Key; // 응답에서 아이템 배열의 키
  size?: number; // 페이지 사이즈 (기본 10)
  enabled?: boolean; // false면 패칭 비활성화
}

export default function useCursorInfiniteScroll<
  T extends object,
  Key extends string,
  ResponseData extends Record<Key, T[]> & {
    hasNext: boolean;
    nextCursorId: number;
  },
>({
  url,
  key,
  size = DEFAULT_SIZE,
  enabled = true,
}: UseCursorInfiniteScrollParams<Key>) {
  const query = useInfiniteQuery({
    queryKey: ['infinity', key, url],
    enabled: enabled && Boolean(url),
    retry: MAX_RETRY_COUNT,
    initialPageParam: null as number | null,
    queryFn: ({ pageParam }) =>
      fetchCursorPage<ResponseData>({
        url,
        size,
        pageParam,
      }),
    getNextPageParam: (lastPage) =>
      lastPage?.hasNext ? lastPage?.nextCursorId : undefined,
  });

  const items = query.data?.pages.flatMap((p) => p[key] as T[]) ?? [];

  return {
    items,
    fetchMore: query.fetchNextPage,
    hasNext: query.hasNextPage,
    loading: query.isFetchingNextPage,
  };
}

export async function fetchCursorPage<ResponseData>(params: {
  url: string;
  size: number;
  pageParam: number | null;
}): Promise<ResponseData> {
  const { url, size, pageParam } = params;

  const queryString = new URLSearchParams({ size: String(size) });
  if (pageParam != null) queryString.append('cursorId', String(pageParam));

  const sep = url.includes('?') ? '&' : '?';
  const requestUrl = `${url}${sep}${queryString.toString()}`;

  const res = await apiClient.get<ApiResponse<ResponseData>>(requestUrl);

  const payload = res?.data as ResponseData;
  return payload;
}

훅 파라미터

  • url: string
    • 요청 보낼 기본 URL (쿼리 포함 가능, 예: /api/items?foo=bar)
  • key: Key
    • 응답 객체에서 아이템 배열이 들어있는 필드명
    • 제네릭 ResponseData의 키와 일치해야 함 (예: items, notifications 등)
  • size: number = 10
    • 페이지 사이즈(한 번에 가져올 개수)
  • enabled: boolean = true
    • false면 패칭 비활성화 (조건 만족 시점에서만 불러오고 싶을 때 사용)

useInfiniteQuery 옵션

  • queryKey: ['infinity', key, url]
    • 캐시 식별 키. 같은 key+url 조합이면 캐시 공유/재사용
  • enabled: enabled && Boolean(url)
    • url이 유효하고 enabled가 true일 때만 패칭
    • 패칭할 때 조건을 작성하고 싶을 때 사용
  • retry: MAX_RETRY_COUNT
    • 실패 시 재시도 횟수 (여기선 3회)
  • initialPageParam: null
    • 첫 페이지의 커서 값. null이면 cursorId 없이 첫 페이지 요청
    • initialPageParam: null as number | null,
      • null as number을 사용한 이유: pageParam의 값이 초기에는 null이고, 다음부터는 숫자가 들어온다. 그래서 as number를 사용하여 number | null 이라고 알려줌
  • queryFn: ({ pageParam }) => fetchCursorPage({...})
    • 실제 패칭 함수. pageParam(커서Id)을 받아 size, url과 함께 요청
  • getNextPageParam: (lastPage) => lastPage.hasNext ? lastPage.nextCursorId : undefined
    • 다음 페이지 유무/커서 계산. undefined면 더 불러올 페이지 없음
    • 해당 함수가 반환하는 값이 pageParam으로 들어감

훅 리턴값

  • items: T[]
    • data.pages를 평탄화(flatMap)한 최종 아이템 배열 (ResponseData[key] 합침)
  • fetchMore: query.fetchNextPage
    • 다음 페이지 요청 트리거
  • hasNext: query.hasNextPage
    • 다음 페이지 존재 여부
  • loading: query.isFetchingNextPage
    • 다음 페이지를 가져오는 중인지 여부(초기 로딩은 query.isLoading 사용 가능)

6. useMutation을 사용하여 patch, delete 요청 처리하기

기존 코드

const handleConfirmFeedback = async (comment: string) => {
    const { feedbackId } = modalState;
    if (feedbackId) {
      onConfirmFeedback?.(feedbackId, comment);
      try {
        await patchFeedbackStatus({
          feedbackId,
          comment,
        });
      } catch (e) {
        showErrorModal(e, '에러');
      }
    }
    closeModal();
  };

useMutation을 사용한 코드

   const queryClient = useQueryClient();
 
 const confirmMutation = useMutation({
    mutationFn: ({
      feedbackId,
      comment,
    }: {
      feedbackId: number;
      comment: string;
    }) => patchFeedbackStatus({ feedbackId, comment }),
    onError: (e) => {
      showErrorModal(e, '에러');
    },
    onSuccess: () => {
      queryClient.invalidateQueries({
        queryKey: ['organizationStatistics', organizationId],
      });
      queryClient.invalidateQueries({ queryKey: ['infinity', 'feedbacks'] });
    },
  });
  
  const handleConfirmFeedback = async (comment: string) => {
    const { feedbackId } = modalState;
    if (!feedbackId) return;

    await confirmMutation.mutateAsync({ feedbackId, comment });
    closeModal();
  };

코드는 길어졌지만 선언형으로 작성되어 이해하기 쉬워졌다.

useMutation 옵션

  • mutationFn
    • PATCH, DELETE, POST, PUT 요청을 수행하는 함수
  • onError
    • API 요청이 실패했을 때 실행할 로직
  • onSuccess
    • API 요청이 성공했을 때 실행할 로직
    • 리패칭은 주로 이 옵션에서 처리
    • queryClient.invalidateQueries 함수를 사용해 특정 쿼리 키를 무효화할 수 있으며, 무효화된 쿼리는 자동으로 리패칭된다.
    • 예를 들어, 피드백 완료 버튼 클릭 후 요청이 성공하면 현재 코드에서는 피드백 리스트와 조직 통계의 쿼리 키를 무효화하여 해당 데이터가 최신 상태로 갱신되도록 한다.

7. 결과

데이터 동기화 완료!

profile
우디(박연기)
프론트엔드 개발하는 사람
이전 포스트

useSyncExternalStore

다음 포스트

[피드줍줍] 리액트 렌더링 최적화

1개의 댓글

comment-user-thumbnail
숳
2025년 9월 16일

멋있어요..

답글 달기