TanStack Query queryFn 사용법: 데이터 요청 로직 분리하기

중간부터 시작하는 전체 실습 파일

기존 Next.js Route Handler TaskFlow의 /tasks 화면과 /api/tasks를 이어서 확장합니다. 인증 없는 demo 메모리 저장소를 사용하는 로컬 실습이며 계정·외부 DB·API 키가 필요 없습니다. MSW를 활성화하지 않습니다. 서버를 다시 시작하면 데이터가 초기화됩니다.

• 시작본 다운로드 — query-step-02-provider.zip
• 완료본 다운로드 — query-step-03-queryfn.zip

이 글의 시작본은 직전 프로젝트 단계 완료본 전체입니다. 이미 직전 단계를 마쳤다면 그 폴더를 이어 쓰셔도 됩니다. Node.js 24.x와 npm을 사용하며 패키지 버전은 package-lock.json에 고정했습니다.

시작본에서 직접 바꾸기

시작본을 실행한 뒤 아래 변경 파일을 순서대로 수정합니다. 완료본의 같은 경로 파일에는 import와 입력 타입을 포함한 전체 코드가 있습니다.

1. app/lib/tasks-api.ts — 이전 단계에 없던 파일을 만듭니다.
2. app/tasks/TaskListClient.tsx — 기존 파일의 같은 위치를 갱신합니다.

변경 이유와 결과: 컴포넌트의 HTTP 검사를 app/lib/tasks-api.ts로 분리합니다. AbortSignal·response.ok와 배열 응답 검사를 함께 연결합니다.

완료본의 docs/changes.patch에서 시작·완료 차이를, docs/current-step.md에서 파일별 적용 위치를 확인할 수 있습니다. 아래 전체 파일을 같은 경로에 반영한 다음 실행하세요.

app/lib/tasks-api.ts 전체 파일

import type { Task } from './types';
export type TaskStatus = 'all' | 'active' | 'completed';
export type TaskPage = { items: Task[]; page: number; totalPages: number };
export type TaskCursorPage = { items: Task[]; nextCursor: string | null };
async function request<T>(url: string, options?: RequestInit): Promise<T> {
  const response = await fetch(url, options);
  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    throw new Error(typeof body.message === 'string' ? body.message : `HTTP ${response.status}`);
  }
  return response.json() as Promise<T>;
}
export async function getTasks(signal?: AbortSignal, status: TaskStatus = 'all', fail = false): Promise<Task[]> {
  const rows = await request<unknown>(`/api/tasks?status=${status}${fail ? '&fail=1' : ''}`, { signal });
  if (!Array.isArray(rows)) throw new Error('작업 배열 응답이 필요합니다.');
  return rows as Task[];
}
export const getTask = (id: string, signal?: AbortSignal) => request<Task>(`/api/tasks/${encodeURIComponent(id)}`, { signal });
export const createTask = (title: string, simulateFailure = false) => request<Task>('/api/tasks', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ title, simulateFailure }),
});
export const updateTask = (id: string, completed: boolean, simulateFailure = false) => request<Task>(`/api/tasks/${encodeURIComponent(id)}`, {
  method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ completed, simulateFailure }),
});
export const getTaskPage = (page: number, signal?: AbortSignal) => request<TaskPage>(`/api/tasks?page=${page}&pageSize=2`, { signal });
export const getTaskCursorPage = (cursor: string | null, signal?: AbortSignal) => request<TaskCursorPage>(`/api/tasks?cursor=${encodeURIComponent(cursor ?? '')}&pageSize=2`, { signal });

app/tasks/TaskListClient.tsx 전체 파일

'use client';
import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import type { Task } from '../lib/types';
import { getTasks, type TaskStatus } from '../lib/tasks-api';
export default function TaskListClient({ status = 'all', onSelect = () => {} }: {
  status?: TaskStatus; onSelect?: (id: string) => void;
}) {
  const [fail, setFail] = useState(false);
  const query = useQuery({
    queryKey: ['tasks'],
    queryFn: ({ signal }) => getTasks(signal, status, fail),
  });
  return (
    <section aria-label="서버 작업 목록">
      <label><input type="checkbox" checked={fail} onChange={(event) => setFail(event.target.checked)} />실습 조회 실패</label>
      <button onClick={() => void query.refetch()}>목록 다시 확인</button>
      {query.isFetching && <p role="status">요청 중입니다.</p>}
      {query.isPending ? <p>불러오는 중입니다.</p> : query.isError ? <p role="alert">{query.error.message}</p> : query.data.length === 0 ? <p>표시할 작업이 없습니다.</p> : (
        <ul>
          {query.data.map((task) => (
            <li key={task.id}>
              <button onClick={() => onSelect(task.id)}>{task.title}</button>
              <span> · {task.completed ? '완료' : '진행 중'}</span>
            </li>
          ))}
        </ul>
      )}
    </section>
  );
}

완료 확인

1. 시작본은 직전 완료본과 동일한 ZIP입니다. 압축을 푼 뒤 npm ci로 잠금 파일의 의존성을 설치합니다.
2. npm run dev 실행 후 http://localhost:3000/tasks를 엽니다.
3. 컴포넌트의 HTTP 검사를 app/lib/tasks-api.ts로 분리합니다. AbortSignal·response.ok와 배열 응답 검사를 함께 연결합니다.
4. npm run typecheck와 npm run build가 성공하면 다음 프로젝트 단계로 갑니다.

이 체크포인트는 TypeScript 검사·프로덕션 빌드와 실제 소스를 사용한 JSDOM/상태 시나리오 검증을 통과했습니다. 별도 실제 브라우저 화면 검수는 이 파일 검증 범위에 포함하지 않았습니다.

아래 부분 예제는 핵심 변경을 설명합니다. 실행에 필요한 전체 파일과 보조 타입·API는 위 완료본에서 확인하세요.