axios를 버리고 fetch와 QueryClient를 선택한 이유

프로젝트를 Pages Router에서 App Router로 마이그레이션하면서 가장 많이 고민한 부분은 "데이터를 어떻게 가져올 것인가" 였다.

기존에는 axios로 모든 요청을 처리했고, 그게 당연하다고 생각했다.

하지만 App Router로 전환하면서 두 가지 큰 변화를 겪었다.

서버 컴포넌트에서는 fetch를 써야 Next.js의 캐싱이 작동한다
클라이언트 컴포넌트의 비동기 상태는 React Query(TanStack Query)의 QueryClient로 관리한다

Pages Router + axios

Pages Router 시절의 데이터 패칭은 단순했다.

// pages/posts/index.jsx

export async function getServerSideProps() {
  const res = await axios.get('https://api.example.com/posts')
  return {
    props: { posts: res.data }
  }
}

export default function PostsPage({ posts }) {
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

클라이언트에서 요청이 필요할 때도 axios였다.

// 클라이언트 컴포넌트에서
useEffect(() => {
  axios.get('/api/user').then(res => setUser(res.data))
}, [])

문제가 없었다. 하지만 App Router로 넘어오면서 이 패턴이 흔들리기 시작했다.

App Router는 fetch를 직접 확장했다

Next.js 13부터 fetch Web API를 직접 확장해서 캐싱과 재검증(revalidation) 옵션을 추가했다.

fetch(url, {
  cache: 'force-cache',      // 캐싱 O — 빌드 타임 데이터처럼 동작
  cache: 'no-store',         // 캐싱 X — 항상 최신 데이터
  next: { revalidate: 60 },  // 60초마다 자동 재검증 (ISR)
  next: { tags: ['posts'] }, // 태그 기반 캐시 무효화
})

그리고 결정적인 이유

axios는 이 옵션을 지원하지 않는다.
axios로 서버 컴포넌트에서 요청하면 Next.js의 캐싱 시스템을 전혀 활용할 수 없다.

서버 컴포넌트 → fetch 전환

Before (axios)

// app/posts/page.jsx 

async function getPosts() {
  const res = await axios.get('https://api.example.com/posts')
  return res.data
}

export default async function PostsPage() {
  const posts = await getPosts()
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

After (fetch + 캐싱 전략)

// app/posts/page.jsx 

async function getPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 60 }, // 60초마다 재검증
  })

  if (!res.ok) {
    throw new Error('포스트를 불러오는 데 실패했습니다.')
  }

  return res.json()
}

export default async function PostsPage() {
  const posts = await getPosts()
  return <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

fetch 캐싱 전략 정리

cache: 'force-cache' 빌드 시 캐싱, 변경 없음 약관, 회사 소개 등

cache: 'no-store' 항상 새로 요청 실시간 재고, 알림 등

next: { revalidate: N } N초마다 재검증 뉴스, 블로그 포스트 등

next: { tags: ['key'] } 태그로 수동 무효화 관리자 페이지 연동 등

주의: fetch의 에러 처리는 직접 해야 한다

axios는 4xx, 5xx 응답에서 자동으로 에러를 던진다.
fetch는 네트워크 오류가 아니면 에러를 던지지 않는다. 직접 확인해야 한다.

// 이렇게 하면 404도 성공으로 처리
const res = await fetch('/api/posts')
const data = await res.json()

// 올바른 방법
const res = await fetch('/api/posts')
if (!res.ok) {
  throw new Error(`HTTP error! status: ${res.status}`)
}
const data = await res.json()

클라이언트 상태 → QueryClient 도입

서버 컴포넌트는 fetch로 해결됐다.
문제는 클라이언트 컴포넌트였다.

버튼 클릭, 검색, 페이지네이션처럼 사용자 인터랙션에 반응하는 데이터는 서버 컴포넌트로 처리할 수 없다.
그래서 React Query(TanStack Query)의 QueryClient를 사용하였다.

React Query는 서버 상태(Server State) 관리 라이브러리다.

QueryClient는 React Query의 핵심 인스턴스로, 캐시 저장소 역할을 한다.

App Router에서는 QueryClientProvider를 클라이언트 컴포넌트로 감싸야 한다.

// app/providers.jsx
'use client'

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

export default function Providers({ children }) {
  // useState로 감싸는 이유:
  // 컴포넌트마다 새 QueryClient를 만들지 않기 위해
  const [queryClient] = useState(() => new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 1000 * 60,      // 1분간 데이터를 "신선"하다고 판단
        gcTime: 1000 * 60 * 5,     // 5분간 캐시 유지
        retry: 1,                  // 실패 시 1회 재시도
        refetchOnWindowFocus: false, // 탭 포커스 시 자동 재요청 X
      }
    }
  }))

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

// app/layout.jsx
import Providers from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  )
}

useQuery로 데이터 가져오기

// app/posts/PostList.jsx
'use client'

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

async function fetchPosts() {
  const res = await fetch('/api/posts')
  if (!res.ok) throw new Error('Failed to fetch')
  return res.json()
}

export default function PostList() {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['posts'],       // 캐시 키 — 이 키로 캐시를 식별
    queryFn: fetchPosts,       // 실제 요청 함수
    staleTime: 1000 * 30,      // 30초간 캐시 유효
  })

  if (isLoading) return <p>로딩 중...</p>
  if (isError) return <p>에러: {error.message}</p>

  return <ul>{data.map(p => <li key={p.id}>{p.title}</li>)}</ul>
}

기존의 useState + useEffect + 로딩/에러 관리가 단 한 줄로 줄어든다.

queryKey의 중요성

queryKey는 캐시를 구분하는 고유 식별자다.

// 같은 키 = 같은 캐시 공유
useQuery({ queryKey: ['posts'], queryFn: fetchPosts })

// 키가 다르면 다른 캐시
useQuery({ queryKey: ['posts', userId], queryFn: () => fetchUserPosts(userId) })
useQuery({ queryKey: ['posts', { page: 2 }], queryFn: () => fetchPosts(2) })

같은 queryKey를 가진 쿼리가 여러 컴포넌트에서 실행되면, 실제 요청은 한 번만 일어난다.
나머지는 캐시에서 가져온다. 이게 React Query의 핵심 장점이다.

useMutation으로 데이터 수정하기

데이터를 변경(POST, PUT, DELETE)할 때는 useMutation을 쓴다.

// 포스트 생성 예시
'use client'

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

export default function CreatePostForm() {
  const queryClient = useQueryClient()

  const mutation = useMutation({
    mutationFn: async (newPost) => {
      const res = await fetch('/api/posts', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(newPost),
      })
      if (!res.ok) throw new Error('생성 실패')
      return res.json()
    },
    onSuccess: () => {
      // 포스트 목록 캐시를 무효화 → 자동으로 재요청됨
      queryClient.invalidateQueries({ queryKey: ['posts'] })
    },
  })

  const handleSubmit = () => {
    mutation.mutate({ title: '새 포스트', content: '...' })
  }

  return (
    <button onClick={handleSubmit} disabled={mutation.isPending}>
      {mutation.isPending ? '저장 중...' : '포스트 작성'}
    </button>
  )
}

내 생각

Pages Router에서 App Router로의 전환은 단순히 폴더 구조를 바꾸는 일이 아니었다.
"데이터를 어디서, 어떻게 가져올 것인가" 에 대한 패러다임이 바뀌는 일이었다.

fetch는 Next.js의 캐싱 시스템과 통합되어 서버 컴포넌트를 강력하게 만들어준다.
QueryClient는 클라이언트 상태를 선언적으로 관리하는식으로 사용한다.

App Router 로 변경하면서 - fetch 를 선택한 이유