📡 05. 데이터 변경과 캐시 무효화: `useMutation`과 `invalidateQueries`

📋 목차

• ☕️ 영철이의 고민: "데이터는 바꿨는데 화면이 안 바뀌어요!"
• 🤔 왜 알아야 하는가: 캐시 서버 동기화의 본질
• 1. 서버 통신의 마법사: useMutation
• 2. 부쉈으면 새로 고침하라: invalidateQueries
• 📝 배운 내용 점검하기 (Quiz)

"영철 님, 서버에 좋아요 반영은 잘 됐는데 왜 화면은 새로고침을 눌러야만 하트가 빨갛게 변하죠?"

☕️ 영철이의 고민: "데이터는 바꿨는데 화면이 안 바뀌어요!"

(화요일 오후, F5(새로고침) 키보드 샷건을 치기 직전인 영철)

🐣 영철: 아 리드 님! 방금 fetch로 '게시글 삭제하기' API 쏘고 200 OK 콘솔 찍히는 거까지 완벽하게 확인했거든요? 근데 삭제 버튼을 눌러도 리스트에서 바로 안 지워지고 떡하니 남아있어요. F5 눌러서 쌩으로 새로고침 해야지만 브라우저에서 사라진다니까요? 캐시가 너무 독한 거 아니에요?

🦁 영호: 서버(DB)에서 글을 지우는 행위(Mutation)는 성공했지만, 정작 우리가 들고 있는 로컬 캐시(식빵) 에게 "야! 저 글 지워졌으니까 니 데이터 버리고 서버에서 다시 스냅샷 따와!" 라고 명령을 안 내렸기 때문입니다.

🐣 영철: 어... 캐시는 알아서 업데이트되는 거 아니었어요?

🦁 영호: "GET 요청" 캐싱만 자동이죠. 언제 데이터를 부수고(POST, DELETE, PUT) 갱신할지는 우리가 직접 알려줘야 해요. useMutation과 invalidateQueries 콤보를 모르면 평생 유저한테 F5 새로고침만 강요하게 됩니다.

🤔 왜 알아야 하는가: 캐시 서버 동기화의 본질

프론트엔드에서 데이터를 서버에 보내서 변경(Create, Update, Delete)하는 행위를 통틀어 Mutation(돌연변이, 변형) 이라고 부릅니다.
우리는 앞서 useQuery로 데이터를 얌전히 가져오는(Read) 법만 배웠습니다.

하지만 커뮤니티 앱에서는 글을 쓰고, 지우고, 좋아요를 누릅니다. 이를 위해선 크게 두 단계 의 액션이 피처럼 이어져야 합니다.

1. 서버에 변경 요청을 날린다. (useMutation)
2. 변경이 완료되자마자, 과거에 불러왔던 오래된 리스트 데이터 캐시를 쓰레기통에 처박고 최신 목록을 다시 불러오게끔 강제한다. (invalidateQueries)

이 흐름(Flow)을 자유자재로 다루는 것이 5년 차 실무의 시작점입니다.

1. 서버 통신의 마법사: useMutation

영철이가 짰던 코드를 되짚어 봅시다.
보통 바닐라 JS에서는 버튼 온클릭 핸들러 안에 쌩 fetch나 axios를 쑤셔 넣습니다.

// ❌ 영철이의 순진한 돌연변이
const handleDelete = async (id) => {
  setIsLoading(true); // 에휴, 빙글빙글 스피너 띄우고
  try {
    await axios.delete(`/posts/${id}`);
    alert('삭제 완료!');
    // 영철: "다 끝났어... 근데 화면은 어떻게 다시 그리지? window.location.reload()?" 💥
  } catch (error) {
    alert('삭제 실패 ㅠㅠ');
  } finally {
    setIsLoading(false);
  }
}

이걸 React Query의 useMutation 훅으로 감싸면? 엄청나게 선언적인 코드로 변신합니다.

// ✅ 영호 리드의 우아한 Mutation 분리
const deletePostMutation = useMutation({
  mutationFn: (id: number) => axios.delete(`/posts/${id}`),
});
 
// 버튼 클릭 핸들러
const handleDelete = (id) => {
  deletePostMutation.mutate(id);
};
 
// 렌더링 뷰 (로딩, 에러 처리를 컴포넌트에 녹여냄)
return (
  <button 
    disabled={deletePostMutation.isPending} 
    onClick={() => handleDelete(1)}
  >
    {deletePostMutation.isPending ? '삭제 중...' : '삭제'}
  </button>
);

우리는 mutate라는 방아쇠(Trigger) 함수 하나만 땡기면 됩니다. isPending, isError, isSuccess 같은 사이드 이펙트 처리는 훅이 알아서 관리해 주죠.

💡 심층 해부: mutate vs mutateAsync의 차이

• mutate: 뒷일은 리액트 쿼리에 맡기고 콜백함수(onSuccess, onError) 쪽에 로직을 태우는 "Fire and Forget" 방식. 대부분의 상황에서 권장됩니다.
• mutateAsync: 직접 파멸적 에러를 잡아야 하거나, 순차적 비동기 이벤트를 묶을 때(await 붙여서) 강제로 사용하는 방식. (TkDodo 아티클 #12 참고)

2. 부쉈으면 새로 고침하라: invalidateQueries

자, 방금 deletePostMutation이 무사히 끝났다고 가정합시다. DB에서는 글 번호 1번이 지워졌지만, 브라우저 화면(저 머나먼 캐시 금고)의 ['posts'] 쿼리는 아직 1번 글을 그득하게 품고 있습니다.

이때 onSuccess 콜백 안에서 영호 리드가 꺼내든 전가의 보도, invalidateQueries 가 등장합니다.

// 전역 캐시 접근을 위한 클라이언트 대빵 호출
const queryClient = useQueryClient();
 
const deletePostMutation = useMutation({
  mutationFn: (id) => axios.delete(`/posts/${id}`),
  // 🚀 비기: 삭제가 '성공(Success)'하면?
  onSuccess: () => {
    // 💡 "야! ['posts'] 라는 이름표 달고 있는 캐시 싹 다 쉰내나는 걸로 무효화(Invalidate)시켜!"
    queryClient.invalidateQueries({ queryKey: ['posts'] });
  },
});

invalidateQueries 의 동작 메커니즘은 예술적입니다.

1. ['posts'] 키를 가진 모든 쿼리 캐시를 즉시 상한(Stale) 상태로 강제 변경(마킹)합니다.
2. 만약 해당 목록 컴포넌트(useQuery(['posts']))가 화면 어딘가에 마운트(Active)되어 띄워져 있다면?
3. "어라? 나 방금 상했네? 다시 최신 데이터 따와야지!" 하고 백그라운드 리패칭(Refetching)을 자동 폭발 시킵니다.
4. 사용자는 버튼 클릭 후(약간의 pending...), 쓱- 하고 리스트에서 삭제된 최신 레이아웃을 마주하게 됩니다. 당연히 브라우저 흰 화면(F5)은 전혀 없습니다!

🐣 영철이의 퇴근 일기

와... 오늘 제대로 하나 터득했다.
내가 수동으로 데이터 배열 filter 돌려서 삭제한 객체 지워주고, 에러 났을 땐 롤백하고 생쑈를 하던 짓거리를... 그냥 서버에서 지웠으니 캐시한테 "가서 다 엎어버리고 최신 리스트 다시 따와(invalidateQueries)" 딱 한 마디 시키니까 마법처럼 화면이 갱신됐다.

💡 오늘의 교훈: "서버 갈구는 변향은 useMutation으로 우아하게 빼고, 일이 끝난 뒤엔 무조건 invalidateQueries로 캐시통을 발로 한번 뻥 차서 새로고침시켜주자!"

사실 onSuccess 안에서 쓸 거면 그냥 컴포넌트 새로 마운트시켜주면 안 되나 속으로 생각헀는데, 생각해보니 그렇게 하면 싱글 페이지 앱(SPA)의 매력(번뜩임 없이 부드러운 전환)이 완전히 사라지는 거구나. 아 무효화... 무효화 쎄게 한 판 치고 시원하게 맥주 마시러 간다! 🍻

📝 배운 내용 점검하기 (Quiz)

Q. 다음과 같은 상황에서 영철이가 특정 게시글의 좋아요(Like)를 누르는 돌연변이(Mutation)를 날렸습니다. 영철이는 다음과 같이 생각했습니다. "게시글 하나의 상태만 살짝 바뀐 거니까 굳이 서버에 또 다녀올 필요 없이 프론트엔드 쪽에서 직접 queryCache를 건드려 하트 개수를 올려버려야겠다!"

영호의 반응과 조언으로 가장 적절한 것은?

• A) "천재입니다, 영철 님! 네트워크 통신을 아끼려면 항상 그렇게 프론트단 로컬 캐시를 뜯어고쳐야 합니다."
• B) "아니오! 만약 좋아요 응답이 오기 직전에 누군가가 글 내용을 수정했다면 어떡하나요? 프론트엔드 캐시는 절대 수동 조작하지 말고, 무조건 invalidateQueries로만 갱신해야 동기화가 깨지지 않습니다."
• C) "mutateAsync를 사용해서 수동으로 컴포넌트의 로컬 상태(useState)에 담아 업데이트해야 합니다."

✅ 정답: B

💡 상세 해설:

• 원리 설명: TkDodo 아티클 #10에 따르면, QueryCache는 당신의 개인 로컬 상태 변수표가 아니라 '항상 서버의 최신 스냅샷을 뗘오기 위한 거울'이어야 합니다. 개발자가 캐시 데이터를 수동으로 수정해버리는 꼼수(setQueryData 강제 조작 등)를 남발하면, 향후 복잡한 백그라운드 리패칭 사이클과 엉켜서 디버깅이 죽어나는(Race Condition 폭발) 스파게티 시스템이 됩니다.
• 오답 피드백: "영철 님, 네트워크 콜 한번 더 쏘는 게 아까워서 캐시값을 직접 바꾸시면 안 됩니다! 그건 나중에 배울 진정한 낙관적 업데이트(Optimistic Update) 에서 제한적으로 쓰는 고오오급 비기고요, 일반적인 경우엔 쿨하게 invalidateQueries 딱 때려서 서버의 진짜 결과물로 덮어씌워야 안전합니다."
• 📌 핵심 기억법: 섣부른 캐시 직접 조작 금지! 부쉈으면 무효화 빔(invalidate) 발사!