웹/앱 개발 · 가이드 · 2026-05-06 · 조회 207

TanStack Query 캐싱

TanStack Query의 캐싱은 AI 기반 웹 서비스의 사용자 경험(UX)을 혁신적으로 개선하고, 백엔드 API 호출 비용을 절감하여 수익성을 높이는 핵심 전략입니다. 데이터를 효율적으로 관리하고 즉시 사용자에게 제공함으로써, 로딩 시간을 최소화하고 서비스의 반응성을 극대화합니다. AI 개발 도구(Claude Code, Cursor 등)를 활용하면 복잡

# TanStack Query 캐싱: AI 서비스 성능과 수익을 동시에 잡는 비법

## 한눈에 요약 (5줄)
TanStack Query의 캐싱은 AI 기반 웹 서비스의 사용자 경험(UX)을 혁신적으로 개선하고, 백엔드 API 호출 비용을 절감하여 수익성을 높이는 핵심 전략입니다. 데이터를 효율적으로 관리하고 즉시 사용자에게 제공함으로써, 로딩 시간을 최소화하고 서비스의 반응성을 극대화합니다. AI 개발 도구(Claude Code, Cursor 등)를 활용하면 복잡한 캐싱 로직 구현을 자동화하여 개발 속도를 압도적으로 높일 수 있습니다. 이 가이드를 통해 한국 개발자/1인 창업자가 TanStack Query 캐싱을 실제 서비스에 적용하고, 성능 최적화 및 비용 절감으로 수익화 기회를 창출하는 방법을 단계별로 학습합니다.

## 왜 중요한가 (수익화/실무 연결)
AI 기반 서비스를 개발하고 운영하는 한국 개발자/1인 창업자에게 TanStack Query의 캐싱 전략은 단순한 기술 최적화를 넘어, 비즈니스 성패를 좌우하는 중요한 요소입니다.

1.  **사용자 경험(UX) 개선 및 이탈률 감소 → 수익 증대:**
    *   빠른 로딩 속도와 즉각적인 데이터 표시는 사용자 만족도를 크게 높입니다. AI 모델 추론 시간이 길어질 수 있는 상황에서도 캐싱된 데이터를 먼저 보여줌으로써 사용자는 서비스가 빠르다고 인식합니다. 이는 사용자 유지율을 높이고, 결과적으로 광고 수익, 구독 전환율, 유료 기능 사용률 등 서비스의 핵심 수익 지표를 개선하는 데 직접적인 영향을 미칩니다. 느린 서비스는 사용자를 잃는 지름길입니다.

2.  **백엔드 API 호출 비용 절감 → 순이익 증가:**
    *   AI 서비스는 종종 외부 API(예: LLM API) 또는 자체 구축한 추론 서버에 의존합니다. 이들 API는 호출 횟수에 따라 비용이 발생합니다. TanStack Query 캐싱을 통해 불필요한 API 호출을 줄이면, AWS Lambda, Vercel Edge Functions, OpenAI API 등에서 발생하는 비용을 획기적으로 절감할 수 있습니다. 1인 창업자에게는 운영 비용 절감이 곧 순이익 증가로 직결되는 매우 중요한 요소입니다.

3.  **개발 생산성 향상 및 빠른 시장 출시 (Time-to-Market):**
    *   TanStack Query는 데이터 fetching, 캐싱, 동기화, 로딩/에러 상태 관리 등 복잡한 비동기 로직을 추상화하여 개발자가 핵심 비즈니스 로직(예: AI 모델 연동, 데이터 처리)에 집중할 수 있게 돕습니다. AI 개발 도구와 함께 사용하면 캐싱 전략 구현 시간을 단축하고, 새로운 기능을 빠르게 빌드하여 시장에 출시할 수 있는 바이브 코딩 환경을 구축합니다.

4.  **SEO 성능 향상:**
    *   웹 페이지 로딩 속도는 검색 엔진 최적화(SEO)의 중요한 요소 중 하나입니다. 캐싱을 통해 페이지 로딩 속도를 개선하면 검색 엔진 랭킹에 긍정적인 영향을 미쳐, 더 많은 잠재 사용자에게 서비스를 노출하고 유입을 늘릴 수 있습니다.

## 핵심 개념
TanStack Query 캐싱의 핵심은 `QueryClient`와 `QueryCache`를 중심으로 데이터의 상태(fresh, stale, inactive)를 관리하는 것입니다.

*   **`QueryClient`**: TanStack Query의 모든 캐싱 로직을 관리하는 중앙 허브입니다. 애플리케이션 전체에 단일 인스턴스를 생성하여 사용합니다.
*   **`QueryCache`**: 실제 쿼리 데이터를 저장하는 공간입니다. 각 쿼리는 고유한 `queryKey`를 가지며, 이 키를 기반으로 데이터가 캐시에 저장됩니다.
*   **`staleTime` (신선도 유지 시간)**:
    *   데이터가 "신선한(fresh)" 상태로 유지되는 시간입니다. 이 시간 동안에는 TanStack Query가 네트워크 요청 없이 캐시된 데이터를 즉시 반환합니다. `staleTime`이 지나면 데이터는 "오래된(stale)" 상태가 됩니다.
    *   기본값은 `0`으로, 데이터가 즉시 `stale` 상태가 됨을 의미합니다. 즉, 쿼리 인스턴스가 마운트될 때마다 백그라운드에서 데이터를 다시 가져오려고 시도합니다.
    *   **활용**: 자주 변하지 않는 데이터(예: 서비스 약관, 고정된 AI 모델 정보)는 `staleTime`을 길게 설정하여 불필요한 네트워크 요청을 줄일 수 있습니다.
*   **`cacheTime` (캐시 유지 시간)**:
    *   쿼리 인스턴스가 더 이상 사용되지 않아 "비활성(inactive)" 상태가 된 후, 캐시에서 데이터가 제거되기까지 기다리는 시간입니다. 이 시간이 지나면 데이터는 가비지 컬렉션(garbage collection) 대상이 됩니다.
    *   기본값은 `5 * 60 * 1000` (5분)입니다.
    *   **활용**: 사용자가 페이지를 잠시 이탈했다가 돌아왔을 때, 이전에 본 데이터를 빠르게 다시 표시하기 위해 `cacheTime`을 적절히 설정할 수 있습니다.
*   **`refetchOnWindowFocus`, `refetchOnReconnect`, `refetchInterval`**:
    *   데이터가 `stale` 상태일 때, 특정 이벤트(창 포커스, 네트워크 재연결) 발생 시 자동으로 데이터를 다시 가져올지 여부를 설정합니다. `refetchInterval`은 일정 시간 간격으로 데이터를 다시 가져오도록 설정합니다.
*   **Query Invalidation (쿼리 무효화)**:
    *   특정 `queryKey`에 해당하는 캐시 데이터를 강제로 `stale` 상태로 만들고, 해당 쿼리를 사용하는 모든 컴포넌트에서 데이터를 다시 가져오도록 트리거하는 기능입니다. 데이터 변경(예: `useMutation`으로 데이터 생성/수정/삭제) 시 캐시를 최신 상태로 유지하는 데 필수적입니다.

## 실전 적용 예시 (한국 환경)
**예시: AI 기반 '한국어 뉴스 요약 및 분석 서비스'**

당신이 개발하는 AI 뉴스 요약 서비스는 사용자가 특정 키워드를 입력하면, AI 모델이 실시간으로 뉴스를 분석하고 요약하여 제공합니다. 이 서비스에서 TanStack Query 캐싱은 다음과 같이 활용될 수 있습니다.

1.  **`staleTime` 활용: 이미 요약된 뉴스에 대한 즉각적인 응답**
    *   사용자가 "반도체 산업 동향" 키워드로 뉴스 요약을 요청했습니다. AI 모델이 요약 결과를 생성하고, 이 결과는 캐시에 저장됩니다.
    *   `staleTime`을 5분으로 설정했다면, 5분 이내에 같은 키워드로 다시 요청이 들어왔을 때, 네트워크 요청 없이 캐시된 요약 데이터를 즉시 반환합니다. 이는 AI 모델 추론 시간을 기다릴 필요 없이 사용자에게 즉각적인 경험을 제공하여, 서비스가 매우 빠르다는 인상을 줍니다.
    *   **수익화 연결**: AI 모델 API 호출 비용 절감. 사용자 만족도 증가로 서비스 재방문율 및 구독 전환율 향상.

2.  **`cacheTime` 활용: 페이지 이탈 후 재방문 시 빠른 로딩**
    *   사용자가 "금융 시장 분석" 요약을 본 후 다른 페이지로 이동했다가 1분 뒤 다시 해당 요약 페이지로 돌아왔습니다.
    *   `cacheTime`이 30분으로 설정되어 있다면, 비록 `staleTime`이 지났더라도 데이터는 여전히 캐시에 남아있습니다. 따라서 페이지 로딩 시 캐시된 데이터를 즉시 보여주고, 백그라운드에서 최신 데이터를 비동기적으로 가져와 업데이트합니다. 사용자는 빈 화면을 보지 않고 이전에 보던 내용을 빠르게 다시 볼 수 있습니다.
    *   **수익화 연결**: 사용자 이탈 방지, 서비스 사용 시간 증가.

3.  **Query Invalidation 활용: 최신 뉴스 반영 및 데이터 일관성 유지**
    *   관리자가 새로운 "속보" 뉴스를 시스템에 등록했습니다. 이 뉴스는 "AI 기술 동향" 키워드와 관련이 있습니다.
    *   새로운 뉴스 등록(`useMutation`)이 성공적으로 완료되면, `queryClient.invalidateQueries(['newsSummary', 'AI 기술 동향'])`를 호출하여 해당 키워드의 캐시 데이터를 무효화합니다.
    *   이제 "AI 기술 동향" 요약 페이지를 보고 있는 사용자나 새로 접근하는 사용자는 최신 뉴스가 반영된 요약 데이터를 다시 가져오게 됩니다.
    *   **수익화 연결**: 항상 최신 정보를 제공하여 서비스의 신뢰도와 가치를 높임.

## AI 도구 활용법 (Claude Code/Cursor/MCP)
AI 개발 도구는 TanStack Query 캐싱 전략을 빠르게 구현하고 최적화하는 데 강력한 조력자가 됩니다. "바이브 코딩" 관점에서 AI와 함께 빠르게 빌드하는 방법을 소개합니다.

1.  **초기 설정 코드 자동 생성:**
    *   **프롬프트 예시:** "React 프로젝트에 TanStack Query를 설정하는 `QueryClientProvider` 코드와 기본 `queryClient` 설정을 만들어줘. `staleTime`은 5분(300000ms), `cacheTime`은 30분(1800000ms)으로 설정하고, Devtools도 포함해줘."
    *   **AI의 응답 활용:** AI는 `main.tsx` 또는 `App.tsx`에 적용할 수 있는 완전한 설정 코드를 제공합니다. 이를 복사하여 붙여넣기만 하면 기본적인 캐싱 환경이 갖춰집니다.

```javascript
    // src/main.tsx (또는 App.tsx)
    import React from 'react';
    import ReactDOM from 'react-dom/client';
    import App from './App.tsx';
    import './index.css';
    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient({
      defaultOptions: {
        queries: {
          staleTime: 1000 * 60 * 5, // 5분
          cacheTime: 1000 * 60 * 30, // 30분
          refetchOnWindowFocus: true, // 창 포커스 시 stale 데이터 자동 refetch (기본값)
          refetchOnMount: true, // 컴포넌트 마운트 시 stale 데이터 자동 refetch (기본값)
        },
      },
    });

ReactDOM.createRoot(document.getElementById('root')!).render(
      <React.StrictMode>
        <QueryClientProvider client={queryClient}>
          <App />
          <ReactQueryDevtools initialIsOpen={false} /> {/* 개발 도구 추가 */}
        </QueryClientProvider>
      </React.StrictMode>,
    );
    ```

2.  **기존 `fetch` API 호출을 `useQuery`로 전환:**
    *   **프롬프트 예시:** "다음 `fetch` API 호출 코드를 TanStack Query의 `useQuery` 훅으로 전환해줘. `queryKey`는 `['newsSummary', keyword]`로 하고, 로딩, 에러, 데이터 상태를 처리하는 컴포넌트 예시도 함께 보여줘."
    *   **AI의 응답 활용:** AI는 기존 비동기 로직을 `useQuery`의 패턴에 맞춰 변환해주며, `isLoading`, `isError`, `data` 등의 상태를 활용하는 컴포넌트 구조를 제안합니다.

```javascript
    // 기존 fetch 코드 (예시)
    // const fetchNewsSummary = async (keyword) => {
    //   const response = await fetch(`/api/news-summary?keyword=${keyword}`);
    //   if (!response.ok) throw new Error('Failed to fetch summary');
    //   return response.json();
    // };

// AI가 생성한 useQuery 전환 코드
    import { useQuery } from '@tanstack/react-query';

interface NewsSummary {
      id: string;
      keyword: string;
      summary: string;
      timestamp: string;
    }

function NewsSummaryComponent({ keyword }: { keyword: string }) {
      const { data, isLoading, isError, error } = useQuery<NewsSummary, Error>({
        queryKey: ['newsSummary', keyword],
        queryFn: () => fetchNewsSummary(keyword),
        enabled: !!keyword, // keyword가 있을 때만 쿼리 실행
      });

if (isLoading) return <div>AI가 뉴스를 요약 중입니다...</div>;
      if (isError) return <div>오류 발생: {error?.message}</div>;
      if (!data) return <div>요약된 뉴스가 없습니다.</div>;

return (
        <div>
          <h2>'{data.keyword}' 뉴스 요약</h2>
          <p>{data.summary}</p>
          <small>마지막 업데이트: {new Date(data.timestamp).toLocaleString()}</small>
        </div>
      );
    }
    ```

3.  **캐싱 전략 최적화 및 디버깅 가이드 요청:**
    *   **프롬프트 예시:** "우리 AI 뉴스 요약 서비스에서 특정 페이지의 데이터가 너무 자주 새로고침되는 것 같아. TanStack Query의 `useQuery` 설정에서 캐싱 전략을 최적화하는 방법을 제안해줘. 특히 `staleTime`, `refetchOnWindowFocus`, `refetchInterval`을 조절하는 방법을 알려주고, Devtools로 확인하는 방법도 설명해줘."
    *   **AI의 응답 활용:** AI는 현재 상황에 맞는 최적화된 `useQuery` 옵션 조합을 제안하고, 각 옵션의 의미와 Devtools에서 `stale` 상태 및 `cacheTime`을 확인하는 방법을 상세히 설명해줍니다.

4.  **Query Invalidation 코드 작성:**
    *   **프롬프트 예시:** "사용자가 새로운 뉴스를 등록했을 때, '모든 뉴스 목록' 쿼리를 무효화하여 최신 목록을 가져오도록 하는 `useMutation`과 `queryClient.invalidateQueries`를 활용한 코드를 작성해줘."
    *   **AI의 응답 활용:** AI는 데이터 변경 후 캐시를 무효화하는 표준 패턴을 제시하여 데이터 일관성을 유지할 수 있도록 돕습니다.

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

interface NewNews {
      title: string;
      content: string;
      keyword: string;
    }

const handleSubmit = (e: React.FormEvent) => {
        e.preventDefault();
        const form = e.target as HTMLFormElement;
        const newNews: NewNews = {
          title: form.title.value,
          content: form.content.value,
          keyword: form.keyword.value,
        };
        mutation.mutate(newNews);
      };

return (
        <form onSubmit={handleSubmit}>
          <input name="title" placeholder="뉴스 제목" required />
          <textarea name="content" placeholder="뉴스 내용" required />
          <input name="keyword" placeholder="키워드 (예: AI 기술 동향)" required />
          <button type="submit" disabled={mutation.isLoading}>
            {mutation.isLoading ? '등록 중...' : '뉴스 등록'}
          </button>
        </form>
      );
    }
    ```

## 단계별 실습
AI 뉴스 요약 서비스를 가정하여 TanStack Query 캐싱을 적용하는 실습입니다.

**준비물:**
*   Node.js (LTS 버전)
*   Visual Studio Code (또는 선호하는 IDE)
*   AI 개발 도구 (Claude Code, Cursor, MCP 등)

**단계 1: React 프로젝트 생성 및 TanStack Query 설치**

1.  Vite를 사용하여 React 프로젝트를 생성합니다.
    ```bash
    npm create vite@latest tanstack-query-caching-demo -- --template react-ts
    cd tanstack-query-caching-demo
    npm install
    ```
2.  TanStack Query와 Devtools를 설치합니다.
    ```bash
    npm install @tanstack/react-query @tanstack/react-query-devtools
    ```
3.  (선택 사항) 가상 API 서버를 위해 `msw`를 설치합니다. (실제 백엔드가 없을 경우 유용)
    ```bash
    npm install msw --save-dev
    npx msw init public/ --save
    ```

**단계 2: `QueryClientProvider` 설정**

`src/main.tsx` 파일을 열고, AI 도구에 "TanStack Query를 React 앱에 설정하는 `QueryClientProvider` 코드와 기본 `queryClient` 설정을 만들어줘. `staleTime`은 5분, `cacheTime`은 30분으로 설정하고, Devtools도 포함해줘."라고 요청하여 코드를 생성하고 적용합니다.

```typescript
// src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App.tsx';
import './index.css';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5, // 5분
      cacheTime: 1000 * 60 * 30, // 30분
      refetchOnWindowFocus: true,
    },
  },
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  </React.StrictMode>,
);
```

**단계 3: 가상 API 연동 (msw 활용)**

`msw`를 설정하여 뉴스 요약 API를 모의(mock)합니다.
`src/mocks/handlers.ts` 파일을 생성하고 다음 내용을 추가합니다.

```typescript
// src/mocks/handlers.ts
import { http, HttpResponse } from 'msw';

const newsSummaries: Record<string, { keyword: string; summary: string; timestamp: string }> = {};

export const handlers = [
  http.get('/api/news-summary', ({ request }) => {
    const url = new URL(request.url);
    const keyword = url.searchParams.get('keyword');

if (!keyword) {
      return HttpResponse.json({ error: 'Keyword is required' }, { status: 400 });
    }

// 실제 AI 모델 추론을 시뮬레이션하기 위한 지연 시간
    return new Promise((resolve) => {
      setTimeout(() => {
        if (!newsSummaries[keyword]) {
          const summary = `${keyword}에 대한 AI 분석 결과: 최근 ${keyword} 관련 동향은 이러이러하며, 주요 이슈는 A, B, C입니다. 앞으로의 전망은 긍정적입니다.`;
          newsSummaries[keyword] = {
            keyword,
            summary,
            timestamp: new Date().toISOString(),
          };
        }
        resolve(HttpResponse.json(newsSummaries[keyword]));
      }, 1500); // 1.5초 지연
    });
  }),

http.post('/api/news', async ({ request }) => {
    const newNews = await request.json();
    console.log('새로운 뉴스 등록:', newNews);
    // 실제 백엔드에서는 DB에 저장하고 캐시를 무효화하는 로직이 필요
    return HttpResponse.json({ message: '뉴스 등록 성공', news: newNews }, { status: 201 });
  }),
];
```

`src/mocks/browser.ts`를 생성하고 다음 내용을 추가합니다.

```typescript
// src/mocks/browser.ts
import { setupWorker } from 'msw';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);
```

`src/main.tsx`에 `msw`를 초기화하는 코드를 추가합니다.

```typescript
// src/main.tsx (상단에 추가)
async function enableMocking() {
  if (process.env.NODE_ENV !== 'development') {
    return;
  }
  const { worker } = await import('./mocks/browser');
  return worker.start();
}

enableMocking().then(() => {
  ReactDOM.createRoot(document.getElementById('root')!).render(
    <React.StrictMode>
      <QueryClientProvider client={queryClient}>
        <App />
        <ReactQueryDevtools initialIsOpen={false} />
      </QueryClientProvider>
    </React.StrictMode>,
  );
});
```

**단계 4: `useQuery` 적용 및 캐싱 확인**

`src/App.tsx`를 수정하여 뉴스 요약 컴포넌트를 만듭니다.

```typescript
// src/App.tsx
import { useState } from 'react';
import { useQuery, useQueryClient, useMutation } from '@tanstack/react-query';

interface NewsSummary {
  keyword: string;
  summary: string;
  timestamp: string;
}

interface NewNews {
  title: string;
  content: string;
  keyword: string;
}

// 뉴스 요약 API 호출 함수
const fetchNewsSummary = async (keyword: string): Promise<NewsSummary> => {
  console.log(`Fetching news summary for: ${keyword}`); // 네트워크 요청 시 콘솔 출력
  const response = await fetch(`/api/news-summary?keyword=${keyword}`);
  if (!response.ok) {
    throw new Error(`뉴스 요약 실패: ${response.statusText}`);
  }
  return response.json();
};

// 새로운 뉴스 등록 API 호출 함수
const createNews = async (newNews: NewNews) => {
  console.log('Sending new news to API:', newNews);
  const response = await fetch('/api/news', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(newNews),
  });
  if (!response.ok) throw new Error('뉴스 등록 실패');
  return response.json();
};

function NewsSummaryDisplay({ keyword }: { keyword: string }) {
  const { data, isLoading, isError, error, isFetching } = useQuery<NewsSummary, Error>({
    queryKey: ['newsSummary', keyword],
    queryFn: () => fetchNewsSummary(keyword),
    enabled: !!keyword, // keyword가 있을 때만 쿼리 실행
  });

if (!keyword) return <div style={{ marginTop: '20px' }}>키워드를 입력하여 뉴스 요약을 확인하세요.</div>;
  if (isLoading) return <div style={{ marginTop: '20px' }}>AI가 '{keyword}' 뉴스를 요약 중입니다...</div>;
  if (isError) return <div style={{ color: 'red', marginTop: '20px' }}>오류 발생: {error?.message}</div>;
  if (!data) return <div style={{ marginTop: '20px' }}>요약된 뉴스가 없습니다.</div>;

return (
    <div style={{ border: '1px solid #ccc', padding: '15px', borderRadius: '8px', marginTop: '20px' }}>
      <h3>'{data.keyword}' 뉴스 요약 {isFetching ? '(새로고침 중...)' : ''}</h3>
      <p>{data.summary}</p>
      <small>마지막 업데이트: {new Date(data.timestamp).toLocaleString()}</small>
    </div>
  );
}

function NewsCreator() {
  const queryClient = useQueryClient();
  const [title, setTitle] = useState('');
  const [content, setContent] = useState('');
  const [keyword, setKeyword] = useState('');

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    mutation.mutate({ title, content, keyword });
  };

return (
    <div style={{ border: '1px solid #eee', padding: '15px', borderRadius: '8px', marginTop: '30px', backgroundColor: '#f9f9f9' }}>
      <h3>새로운 뉴스 등록</h3>
      <form onSubmit={handleSubmit} style={{ display: 'flex', flexDirection: 'column', gap: '10px' }}>
        <input type="text" placeholder="뉴스 제목" value={title} onChange={(e) => setTitle(e.target.value)} required />
        <textarea placeholder="뉴스 내용" value={content} onChange={(e) => setContent(e.target.value)} required />
        <input type="text" placeholder="관련 키워드 (예: AI 기술 동향)" value={keyword} onChange={(e) => setKeyword(e.target.value)} required />
        <button type="submit" disabled={mutation.isLoading}>
          {mutation.isLoading ? '등록 중...' : '뉴스 등록'}
        </button>
      </form>
    </div>
  );
}

function App() {
  const [currentKeyword, setCurrentKeyword] = useState('');

return (
    <div style={{ maxWidth: '800px', margin: '30px auto', fontFamily: 'Arial, sans-serif' }}>
      <h1>AI 뉴스 요약 서비스</h1>

<input
        type="text"
        placeholder="요약할 키워드를 입력하세요 (예: AI 기술 동향)"
        value={currentKeyword}
        onChange={(e) => setCurrentKeyword(e.target.value)}
        style={{ width: '100%', padding: '10px', fontSize: '16px', borderRadius: '4px', border: '1px solid #ddd' }}
      />

<NewsSummaryDisplay keyword={currentKeyword} />
      <NewsCreator />
    </div>
  );
}

export default App;
```

**실행 및 확인:**

1.  프로젝트를 실행합니다: `npm run dev`
2.  브라우저 개발자 도구(F12)를 열고 "Network" 탭을 확인합니다.
3.  웹 페이지에서 검색창에 "AI 기술 동향"을 입력합니다.
    *   처음에는 1.5초 지연 후 데이터가 나타나며, Network 탭에 `/api/news-summary?keyword=AI 기술 동향` 요청이 보일 것입니다.
4.  동일한 키워드를 다시 입력하거나, 잠시 다른 키워드를 입력했다가 다시 "AI 기술 동향"을 입력합니다.
    *   `staleTime` (5분) 이내라면, 데이터가 즉시 나타나고 Network 탭에 요청이 발생하지 않습니다. (`isFetching`은 `true`가 될 수 있지만, 화면은 즉시 업데이트됩니다.)
    *   `staleTime`이 지난 후 다시 "AI 기술 동향"을 입력하면, 데이터는 즉시 나타나지만 백그라운드에서 새로운 요청이 발생합니다 (Network 탭 확인).
5.  TanStack Query Devtools를 엽니다 (브라우저 좌측 하단에 아이콘).
    *   `newsSummary` 쿼리 키의 상태(stale, fresh, inactive)와 `staleTime`, `cacheTime`이 어떻게 작동하는지 시각적으로 확인할 수 있습니다.
6.  "새로운 뉴스 등록" 섹션에서 "AI 기술 동향" 키워드로 뉴스를 등록해봅니다.
    *   등록 성공 후, `queryClient.invalidateQueries`에 의해 `newsSummary` 쿼리 키가 무효화되고, `NewsSummaryDisplay` 컴포넌트가 최신 데이터를 다시 가져오는 것을 확인할 수 있습니다 (Network 탭에 다시 요청 발생).

## 자주 나는 오류
1.  **"데이터가 새로고침되지 않아요!"**:
    *   **원인**: `staleTime`을 너무 길게 설정했거나, `queryKey`가 예상과 다르게 설정되어 `invalidateQueries`가 제대로 작동하지 않는 경우. 또는 `refetchOnWindowFocus`, `refetchOnReconnect` 등의 옵션이 `false`로 설정된 경우.
    *   **해결**: `staleTime`을 적절히 조절하고, `queryKey`가 변경 시에도 일관성 있게 유지되는지 확인합니다. `invalidateQueries` 호출 시 `queryKey`가 정확한지 검토합니다. Devtools를 활용하여 쿼리 상태를 확인합니다.

2.  **"데이터가 너무 자주 새로고침돼요!"**:
    *   **원인**: `staleTime`이 `0` (기본값)이거나 너무 짧게 설정된 경우, 또는 `refetchOnWindowFocus`, `refetchOnMount`, `refetchInterval` 등이 불필요하게 활성화된 경우. `queryKey`가 불필요하게 자주 변경되는 경우.
    *   **해결**: `defaultOptions.queries.staleTime`을 서비스 데이터의 특성에 맞게 충분히 길게 설정합니다 (예: 1분, 5분). `refetchOnWindowFocus` 등의 옵션을 `false`로 설정하여 자동 새로고침을 제어할 수 있습니다.

3.  **`QueryClientProvider` 누락 또는 잘못된 위치**:
    *   **원인**: `useQuery` 훅을 사용하는 컴포넌트가 `QueryClientProvider`로 감싸져 있지 않거나, Provider가 `useQuery` 훅보다 하위에 위치하지 않은 경우.
    *   **해결**: `main.tsx` 또는 `App.tsx`의 최상단에 `QueryClientProvider`를 올바르게 설정했는지 확인합니다.

4.  **잘못된 `queryKey` 사용**:
    *   **원인**: `queryKey`가 고유하지 않거나, 의도와 다르게 변경되어 캐싱이 제대로 작동하지 않는 경우. 예를 들어, 동적 키워드를 사용해야 하는데 하드코딩된 키를 사용하는 경우.
    *   **해결**: `queryKey`는 배열 형태로 사용하며, 데이터의 고유성을 나타내는 모든 변수를 포함해야 합니다 (예: `['newsSummary', keyword]`). Devtools에서 쿼리 키 목록을 확인하여 예상대로 작동하는지 검증합니다.

## 다음에 볼 자료
*   **TanStack Query 공식 문서 (Caching 섹션)**: [https://tanstack.com/query/latest/docs/react/guides/caching](https://tanstack.com/query/latest/docs/react/guides/caching)
    *   캐싱의 심화 개념과 다양한 옵션을 상세히 학습할 수 있습니다.
*   **`useMutation`을 활용한 데이터 변경 및 캐시 업데이트 전략**:
    *   데이터를 생성, 수정, 삭제할 때 캐시를 어떻게 효율적으로 업데이트하고 무효화하는지 `useMutation`과 `onSuccess`, `onSettled` 등의 콜백을 통해 학습합니다.
*   **옵티미스틱 업데이트 (Optimistic Updates)**:
    *   데이터 변경 요청 시 서버 응답을 기다리지 않고 UI를 미리 업데이트하여 사용자 경험을 극대화하는 고급 캐싱 전략입니다. AI 서비스에서 사용자 입력에 대한 즉각적인 피드백을 제공하는 데 유용합니다.
*   **SSR/SSG 환경에서의 TanStack Query 활용**:
    *   Next.js와 같은 프레임워크에서 서버 사이드 렌더링(SSR) 또는 정적 사이트 생성(SSG) 시 TanStack Query 캐시를 미리 채워 넣는(Hydration) 방법을 학습하여 초기 로딩 성능을 더욱 향상시킵니다.

같은 카테고리 자료

TypeScript 5.x 신기능 shadcn/ui 커스터마이징 React 19 새 기능 Next.js 15 App Router

← 웹/앱 개발 목록 기술 자료 전체

TanStack Query 캐싱

같은 카테고리 자료

이런 기술을 우리 회사에 적용하려면?

회원 전용 기능입니다