TanStack Query useMutation 저장 실습: 실패·재시도와 목록 갱신까지

import { useState } from 'react';
import {
  QueryClient,
  QueryClientProvider,
  useQuery,
  useQueryClient,
  useMutation
} from '@tanstack/react-query';

const wait = (ms = 400) => new Promise<void>((resolve) => setTimeout(resolve, ms));
const client = new QueryClient({
  defaultOptions: { queries: { retry: false, refetchOnWindowFocus: false } },
});

let saved: string[] = ['기존 작업'];
async function readRows() { await wait(); return [...saved]; }
async function saveTitle(title: string) {
  await wait();
  if (title === '실패') throw new Error('연습용 저장 실패');
  if (!title.trim()) throw new Error('제목을 입력하세요');
  saved = [...saved, title.trim()];
  return title.trim();
}
function Demo() {
  const [title, setTitle] = useState('새 작업');
  const queryClient = useQueryClient();
  const query = useQuery({ queryKey: ['saved'], queryFn: readRows });
  const mutation = useMutation({
    mutationFn: saveTitle,
    retry: false,
    onSuccess: async () => {
      await queryClient.invalidateQueries({ queryKey: ['saved'] });
      setTitle('');
    },
  });
  return (
    <main>
      <label>제목 <input value={title} onChange={(event) => setTitle(event.target.value)} /></label>
      <button disabled={mutation.isPending} onClick={() => mutation.mutate(title)}>저장</button>
      <button onClick={() => setTitle('실패')}>실패 입력</button>
      {mutation.isPending && <p>저장 중</p>}
      {mutation.isError && <p>{mutation.error.message}</p>}
      <ul>{query.data?.map((row, index) => <li key={index}>{row}</li>)}</ul>
    </main>
  );
}

export default function App() {
  return (
    <QueryClientProvider client={client}>
      <Demo />
    </QueryClientProvider>
  );
}

npm run dev
npm run build

mutationFn 만들기

app/lib/tasks-api.ts

type CreateTaskInput = {
  title: string;
};


export async function createTask(
  input: CreateTaskInput,
): Promise<Task> {
  const response = await fetch('/api/tasks', {
    method: 'POST',
    headers: {
      'Content-Type':
        'application/json',
    },
    body: JSON.stringify(input),
  });


  if (!response.ok) {
    throw new Error(
      '작업 저장에 실패했습니다.',
    );
  }


  return response.json();
}

queryFn과 마찬가지로 HTTP 오류를 직접 던집니다.

첫 useMutation

const mutation = useMutation({
  mutationFn: createTask,
});

실행할 때 mutate를 호출합니다.

mutation.mutate({
  title: 'TanStack Query 공부',
});

mutation 상태

isPending
→ 서버 변경 요청 진행 중


isError
→ mutationFn 실패


isSuccess
→ mutation 성공

버튼 중복 클릭을 막을 때 isPending을 활용할 수 있습니다.

<button
  type="submit"
  disabled={mutation.isPending}
>
  {mutation.isPending
    ? '저장 중...'
    : '추가'}
</button>

실패 재시도

mutation은 기본적으로 실패를 자동 재시도하지 않습니다. 아래 retry: 1은 재시도를 명시한 비교 예제이며 상단 독립 앱의 retry: false와 구분합니다. 동일한 저장을 반복해도 되는 요청인지와 실패 원인을 먼저 판단한 뒤 정책을 정합니다.

useMutation({
  mutationFn: createTask,
  retry: 1,
});

모든 오류를 무조건 재시도하는 것이 좋은 것은 아닙니다.

예를 들어 잘못된 입력으로 발생한 400 오류는 같은 요청을 다시 보내도 성공하지 않을 가능성이 큽니다.

실제 서비스에서는 오류 종류에 따라 retry 함수를 설계할 수 있습니다.

성공 후 목록 갱신

서버에는 새 작업이 저장됐지만 기존 [‘tasks’] 캐시는 자동으로 새 항목을 포함하지 않습니다.

QueryClient를 가져옵니다.

const queryClient = useQueryClient();

성공 후 목록 query를 invalidation합니다.

const mutation = useMutation({
  mutationFn: createTask,
  onSuccess: async () => {
    await queryClient.invalidateQueries({
      queryKey: taskKeys.lists(),
    });
  },
});

무효화된 active query는 다시 서버 데이터를 확인할 수 있습니다.

TaskForm 입력은 React state

입력 중인 title까지 Query cache에 넣을 이유는 없습니다.

const [title, setTitle] =
  useState('');

역할은 다음과 같습니다.

입력 중 문자열
→ React state


POST /api/tasks 상태
→ useMutation


작업 목록 원본
→ useQuery

TaskForm 예제

'use client';


import {
  useMutation,
  useQueryClient,
} from '@tanstack/react-query';
import { useState } from 'react';
import {
  createTask,
} from '../lib/tasks-api';
import {
  taskKeys,
} from '../lib/task-keys';


export default function TaskForm() {
  const [title, setTitle] =
    useState('');


  const queryClient =
    useQueryClient();


  const mutation = useMutation({
    mutationFn: createTask,
    retry: 1,
    onSuccess: async () => {
      setTitle('');


      await queryClient
        .invalidateQueries({
          queryKey:
            taskKeys.lists(),
        });
    },
  });


  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();


        const value = title.trim();
        if (!value) return;


        mutation.mutate({
          title: value,
        });
      }}
    >
      <label htmlFor="task-title">
        새 작업
      </label>


      <input
        id="task-title"
        value={title}
        onChange={(event) =>
          setTitle(
            event.target.value,
          )
        }
      />


      <button
        type="submit"
        disabled={
          mutation.isPending
        }
      >
        {mutation.isPending
          ? '저장 중...'
          : '추가'}
      </button>


      {mutation.isError ? (
        <p>
          {mutation.error.message}
        </p>
      ) : null}
    </form>
  );
}

학습 완료 체크리스트

• useMutation과 useQuery 역할을 구분할 수 있습니다.
• mutationFn으로 POST 요청을 분리할 수 있습니다.
• mutation pending/error 상태를 UI에 연결할 수 있습니다.
• retry를 상황에 맞게 설정할 수 있습니다.
• mutation 성공 후 관련 query를 invalidation할 수 있습니다.

'use client';
import { useState } from 'react';
import TaskListClient from './TaskListClient';
import type { TaskStatus } from '../lib/tasks-api';
import TaskDetailClient from './TaskDetailClient';
import TaskForm from './TaskForm';
export default function TaskDashboard() {
  const [status, setStatus] = useState<TaskStatus>('all');
  const [selected, setSelected] = useState<string | null>(null);
  return (
    <main>
      <h1>TaskFlow Query</h1>
      <label>필터 <select value={status} onChange={(event) => setStatus(event.target.value as TaskStatus)}>
        <option value="all">전체</option><option value="active">진행 중</option><option value="completed">완료</option>
      </select></label>
      <TaskForm />
      <TaskListClient status={status} onSelect={setSelected} />
      {selected && <TaskDetailClient taskId={selected} />}
    </main>
  );
}

 'use client';
import { useState, type FormEvent } from 'react';
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { createTask } from '../lib/tasks-api';
import { taskKeys } from '../lib/task-keys';
export default function TaskForm() {
  const [title, setTitle] = useState('');
  const [fail, setFail] = useState(false);
  const client = useQueryClient();
  const mutation = useMutation({
    mutationFn: () => createTask(title, fail),
    onSuccess: async () => { setTitle(''); await client.invalidateQueries({ queryKey: taskKeys.all }); },
  });
  function submit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    if (title.trim().length >= 2) mutation.mutate();
  }
  return (
    <form onSubmit={submit}>
      <label htmlFor="task-title">새 작업</label>
      <input id="task-title" value={title} onChange={(event) => setTitle(event.target.value)} minLength={2} maxLength={100} required />
      <label><input type="checkbox" checked={fail} onChange={(event) => setFail(event.target.checked)} />실습 저장 실패</label>
      <button disabled={mutation.isPending}>추가</button>
      {mutation.isPending && <p role="status">저장 중입니다.</p>}
      {mutation.isError && <p role="alert">{mutation.error.message}</p>}
    </form>
  );
}

query-step-05-cache-time

app/lib/tasks-api.ts
app/tasks/TaskForm.tsx

POST 요청 상태와 목록 갱신을 직접 관리

useMutation
→ pending / error / success


onSuccess
→ task 목록 invalidation

npm run build

✓ 1~5. 조회·캐시 기반
→ 6. useMutation
○ 7. 화면 갱신 문제 진단
○ 8~11. 페이지·낙관적 업데이트·캐시 동기화
○ 12~15. SSR·Hydration

query-step-06-mutation

다음 학습

다음 글에서는 mutation이 성공했는데 화면이 바뀌지 않는 대표적인 상황을 queryKey 불일치, invalidation 범위, setQueryData 기준으로 진단합니다.

다음 프로젝트 단계: TanStack Query 화면 갱신 문제 해결: 데이터 변경 후 UI가 바뀌지 않을 때

공식 문서

• Mutations: https://tanstack.com/query/latest/docs/framework/react/guides/mutations
• Query Invalidation: https://tanstack.com/query/latest/docs/framework/react/guides/query-invalidation

글 소개·학습 준비·전체 목차

TanStack Query · 6 / 15 · 필수 학습 · useMutation

useMutation은 저장 요청의 대기·실패·성공을 구분합니다. 저장이 성공해도 기존 목록 캐시는 자동으로 새 항목을 포함하지 않으므로 onSuccess에서 정확한 목록 키를 무효화하고 다시 조회합니다. 아래 모형에서 실패 입력과 수정 후 재저장을 각각 확인합니다.

상단은 메모리 기반 비동기 함수로 저장 중·실패·성공 후 갱신을 독립 실습합니다. 하단에서는 TaskFlow의 POST /api/tasks를 mutationFn에 연결합니다.

이번 글에서 배우는 내용

• useMutation 기본 구조
• mutationFn
• mutate와 mutateAsync
• isPending, isError, isSuccess
• retry 옵션
• 성공 후 invalidateQueries
• TaskForm 로컬 state와 서버 mutation 역할 분리

목차