useInfiniteQuery

useInfiniteQuery는 페이지 단위 데이터를 가져올 때 사용하는 TanStack Query 훅이다.

즉 전체 데이터를 한 번에 가져오는 게 아니라

현재 페이지 데이터 가져오기
→ 다음 페이지 요청
→ 이어붙이기

방식으로 동작한다.

예를 들어

게시글 무한스크롤
댓글 목록
상품 리스트
SNS 피드

같은 UI에 적합하다.

기본 구조

const {
  data,
  isLoading,
  fetchNextPage,
  hasNextPage,
  isFetchingNextPage,
} = useInfiniteQuery<ArtResponse>(
  [queryKeys.ARTS, search],
  ({ pageParam = 0 }) => getArtsData(buildPayload(search, pageParam)),
  {
    getNextPageParam: (lastPage) => {
      const { number, totalPages } = lastPage.page;

      return number + 1 < totalPages
        ? number + 1
        : undefined;
    },
  }
);

처음엔 일반 useQuery랑 크게 다를 줄 알았다.

근데 핵심 차이는

페이지 상태를 내부적으로 계속 이어간다

는 점이었다.

data.pages 구조가 핵심

data는 실제로

data

data.pages[0]
data.pages[1]
data.pages[2]

의 형태다.

페이지 응답 자체를 배열로 관리한다.

fetchNextPage

다음 페이지 데이터를 요청하는 함수다.

fetchNextPage();

보통 스크롤이 하단에 도달했을 때 실행한다.

내부적으로

pageParam 관리
기존 pages 유지
다음 페이지 append

전부 처리한다.

hasNextPage

다음 페이지 존재 여부

를 나타낸다.

getNextPageParam

과 연결된다는 점이다.

getNextPageParam

다음 페이지 번호를 계산한다.

getNextPageParam: (lastPage) => {
  const { number, totalPages } = lastPage.page;

  return number + 1 < totalPages
    ? number + 1
    : undefined;
}

여기서 undefined를 반환하면:

다음 페이지 없음

으로 판단한다.

즉 hasNextPage도 자동으로 false가 된다.

IntersectionObserver

무한스크롤에서 거의 필수처럼 같이 등장하는 API다.

특정 요소가 화면에 보이는지 감지한다.

보통 리스트 맨 아래에

<div ref={loaderRef} />

같은 감지용 요소를 둔다.

그리고 이 요소가 화면에 보이면

fetchNextPage();

를 실행한다.

기본 흐름

useEffect(() => {
  const el = loaderRef.current;
  if (!el) return;

  const observer = new IntersectionObserver(
    (entries) => {
      const [entry] = entries;

      if (
        entry.isIntersecting &&
        hasNextPage &&
        !isFetchingNextPage
      ) {
        fetchNextPage();
      }
    },
    {
      root: null,
      rootMargin: '200px',
      threshold: 0,
    }
  );

  observer.observe(el);

  return () => observer.disconnect();
}, [fetchNextPage, hasNextPage, isFetchingNextPage]);

rootMargin

rootMargin: '200px'

이건

실제 바닥에 닿기 200px 전

부터 미리 감지한다는 의미다.

즉 사용자가 완전히 바닥에 도달하기 전에

다음 데이터 미리 요청

가능하다.

이걸 넣지 않으면 스크롤 끝에서 로딩 지연 체감이 생길 수 있다.

문제는 여기서부터

처음엔

isFetchingNextPage 있으면 충분하겠네?

싶었다.

근데 실제론 IntersectionObserver가 생각보다 짧은 시간에 여러 번 호출된다.

즉 이런 상황이 가능하다.

observer callback 실행
→ fetchNextPage 호출
→ 상태 업데이트 전
→ observer 또 호출
→ fetchNextPage 또 호출

결국

중복 요청

이 발생할 수 있다.

그래서 lock(ref)을 사용한다

const isFetchingNextPageLockedRef = useRef(false);

이걸 사용하면

즉시 동기적으로 lock 설정 가능

하다.

구현 구조

if (
  !entry.isIntersecting ||
  !hasNextPage ||
  isFetchingNextPage ||
  isFetchingNextPageLockedRef.current
) {
  return;
}

isFetchingNextPageLockedRef.current = true;

fetchNextPage().finally(() => {
  isFetchingNextPageLockedRef.current = false;
});

핵심은

React state 업데이트 기다리지 않고
즉시 lock

한다는 점이다.

왜 useRef를 쓰는가

useState는 비동기 렌더링 흐름을 가진다.

반면 useRef.current는

즉시 변경 가능
리렌더 없음
항상 최신 값 참조 가능

하다.

즉 observer 같은 비동기 callback 환경에서 안정적이다.

cancelRefetch

fetchNextPage({
  cancelRefetch: false,
});

//cancelRefetch=true
//→ 중복 요청 막나?

기본값: cancelRefetch = true

기본값은 true다.

즉 짧은 시간에

fetchNextPage
fetchNextPage
fetchNextPage

가 연속 호출되면
새 요청들이 계속 실행될 수 있다.

그리고 이전 요청 결과는 무시될 수 있다.

즉

"중복 요청 방지"

라기보다

"새 요청 허용"

에 더 가깝다.

cancelRefetch: false

무한스크롤에서는 이쪽이 더 직관적일 때가 많다.

fetchNextPage({
  cancelRefetch: false,
});

이렇게 하면

이전 fetchNextPage 진행 중
→ 추가 호출 무시

된다.

즉

한 번에 하나만 실행

구조가 된다.

지금 기준으로 무한스크롤 안정성은 보통

1. hasNextPage
2. isFetchingNextPage
3. ref lock
4. cancelRefetch: false

를 같이 사용한다.

각각 역할이 다르다

hasNextPage

다음 페이지 존재 여부

isFetchingNextPage

React Query 상태 기반

ref lock

즉시 동기적 잠금

cancelRefetch: false

React Query 내부 fetch 중복 제어

무한스크롤과 중복호출 방지