"서버에서 한 번만", useAsyncData 데이터 페칭의 본질

Nuxt 4 환경에서 블로그 포스트나 API 데이터를 가져올 때 가장 핵심이 되는 컴포저블은 단연 useAsyncData다. 일반적인 Vue 3 Single Page Application(SPA)의 데이터 페칭 방식을 Nuxt(SSR)에 그대로 대입하면 중복 호출과 화면 깜빡임이라는 치명적인 성능 저하를 마주하게 된다. 본 글에서는 이를 우회하고 우아한 데이터 파이프라인을 구축하는 아키텍처적 방법을 다룬다.

1. SSR의 고질적 문제: 중복 호출(Double Fetching)과 하이드레이션

기존 Vue 3 + Vite(SPA) 환경에서는 컴포넌트가 마운트된 후(onMounted) 브라우저가 직접 API를 호출하는 것이 정석이었다. 그러나 서버 사이드 렌더링(SSR) 환경인 Nuxt에서는 코드가 서버에서 한 번, 브라우저에서 한 번, 총 두 번 실행되는 특성을 가진다.

• 일반 $fetch()의 한계: 서버가 페이지를 빌드할 때 API를 호출하고, 브라우저가 HTML을 넘겨받은 뒤 똑같은 API를 또 호출한다. 불필요한 네트워크 오버헤드가 발생할 뿐만 아니라, 서버 데이터와 클라이언트 데이터의 동기화 타이밍 차이로 인해 하이드레이션 미스매치(Hydration Mismatch) 에러가 발생한다.
• useAsyncData의 해결책: 서버에서 데이터를 최초로 가져오면, 그 결과물을 payload라는 내장 임시 저장소에 공유 상태(State)로 박제하여 브라우저로 함께 토스한다. 브라우저는 네트워킹을 생략하고 이 저장소에서 데이터를 즉시 꺼내 재사용하므로 네트워크 요청을 단 1번으로 최적화한다.

2. useAsyncData 구조 및 핵심 반환 객체

useAsyncData는 단순한 데이터 호출 래퍼(Wrapper)를 넘어, 요청의 수명 주기와 로딩 상태를 선언적으로 관리할 수 있는 반응형 객체들을 반환한다.

const { data, status, error, refresh } = await useAsyncData(
        'main-posts-feed',                      // 1. 애플리케이션 전역 고유 키 (Unique Key)
        () => queryCollection('docs_ko').all(), // 2. 비동기 데이터를 반환하는 콜백 함수
        options                                 // 3. 성능 및 동작 제어를 위한 옵션 객체
)

• data: 비동기 함수가 최종 반환한 데이터가 담긴 Vue 3 Ref 객체다.
• status: 현재 데이터 페칭의 상태를 실시간 문자열로 제공한다. ('idle', 'pending', 'success', 'error')
• refresh: 페이지 전체를 새로고침하지 않고, 특정 이벤트(예: 버튼 클릭) 시점에 데이터를 수동으로 다시 불러와서 UI를 갱신하는 고차 함수다.

3. 실무 아키텍처를 위한 고급 옵션 (Options) 파이프라인

useAsyncData의 세 번째 인자인 options 객체를 활용하면 프론트엔드 레벨에서 서빙되는 데이터 구조를 극적으로 경량화할 수 있다.

① default 패턴을 이용한 초기 런타임 에러 방지

비동기 데이터가 도착하기 전, data.value는 기본적으로 null 상태다. 이때 템플릿이나 computed에서 배열 메서드(.map())를 호출하면 에러가 터진다. default 옵션으로 초기 상태를 보장하는 것이 안전하다.

💡 데이터 안정성 확보default 옵션을 배열 구조(() => [])로 정의하면 v-for 루프나 가공 함수가 데이터 로딩 중에도 크래시 없이 안전하게 실행된다.

② transform을 통한 네트워크 페이로드 경량화

Content 모듈이나 외부 CMS에서 넘겨주는 원본 데이터 중, 현재 컴포넌트 렌더링에 꼭 필요한 필드만 필터링하여 보관할 수 있다. 브라우저가 전달받는 payload 메모리 크기가 줄어들어 전체적인 성능과 메모리 효율이 극대화된다.

// 본문(body) 내용 등 무거운 필드를 제외하고 목록용 데이터만 슬라이싱하는 예시
const { data: postsSummary } = await useAsyncData('posts-summary', () => queryCollection('docs').all(), {
  transform: (rawPosts) => rawPosts.map(post => ({
    title: post.title,
    description: post.description,
    to: post._path
  }))
})

4. Nuxt 4 Content 모듈 최적화 실무 패턴

블로그 메인 피드처럼 정제된 가공 데이터가 필요할 때, 별도의 외부 computed 파이프라인으로 결합도를 높이기보다 useAsyncData 콜백 내부에서 await 후 인라인으로 최종 형태를 빌드하여 반환하는 패턴이 스코프 관리 측면에서 가장 이상적이다.

const { data: formattedPosts } = await useAsyncData('main-posts-feed', async () => {
  // 1. 비동기 쿼리를 통해 raw 데이터 배열을 온전히 확보
  const rawPosts = await queryCollection('docs_ko')
    .order('date', 'DESC') // 최신순 정렬
    .all()

  // 2. 확보된 순수 배열을 하이드레이션 이전에 즉시 맵핑 및 가공
  return rawPosts.map(post => ({
    ...post,
    image: post.image || '[https://nuxt.com/assets/blog/nuxt-icon/cover.png](https://nuxt.com/assets/blog/nuxt-icon/cover.png)',
    date: formatDate(post.date), // 날짜 포맷 레이어 적용
    to: post._path,
  }))
}, {
  default: () => [], // 초기 렌더링 안정성 확보
})

5. 결론 및 체크리스트

Nuxt 4 아키텍처에서 useAsyncData를 다룰 때는 다음 세 가지 규칙을 항상 준수해야 정교한 하이브리드 웹 애플리케이션을 완성할 수 있다.

1. 고유 ID 규칙: 첫 번째 인자인 key는 서비스 전역 컨텍스트 상에서 단 하나만 존재해야 한다. 키가 중복될 경우 서로 다른 컴포넌트 간에 데이터 오버라이트 현상이 발생한다.
2. 비동기 타이밍 스코프: 콜백 블록 내부에서 맵핑 함수를 쓸 때는 반드시 대상을 await로 명확하게 평가(Evaluation)하여 비동기 프로미스 객체에 직접 .map()을 요청하는 실수를 방지해야 한다.
3. 미니멀 데이터 유지: 블로그 목록 화면에서 굳이 들고 있을 필요가 없는 무거운 마크다운 객체 구조는 transform 또는 인라인 매퍼를 통해 철저히 걷어내어 가벼운 상태를 유지해야 한다.