🚀 Next.js 심화 3장: Cache Invalidation — 화석을 깨부수는 철퇴

📋 목차

• 📌 이 문서를 읽기 전에
• 🤔 왜 알아야 하는가
• 🏗️ 비유로 먼저 이해하기
• 🧩 revalidatePath: 무식하게 도끼로 내려찍기 🟢
• 🌱 revalidateTag: 우아하고 정밀한 저격총 🟡
• 🛡️ router.refresh(): 유저 브라우저 속살 지우기 🔴
• 💥 에러 해결 카탈로그
• 🏁 이번에 배운 내용 총정리
• 📝 마무리 퀴즈
• 🔗 더 알아보기

📌 이 문서를 읽기 전에

⏱️ 예상 읽기 시간: 15분 (전체) / 핵심 파트만: 8분

🗺️ 이 문서의 배경 세계관: '영수네 커뮤니티'

• 영철(신입): "게시물 수정 버튼 누르고 서버 API로 DB 업데이트를 쏘고 나서 window.location.reload()로 새로고침을 갈겼는데, 화면엔 계속 똑같은 예전 글씨만 떠요! Next.js 서버의 영구 캐시(Data Cache)를 못 부수고 있다는 건 알겠어요. 어떻게 부수죠?"
• 영호(리드): "영철 님... 브라우저에서 '새로고침' 백날 눌러봐야, 빙하 속(서버)에서 영원히 잠든 얼음조각은 깨지지 않아요! 서버 코어 깊숙이 접근해서 revalidatePath 나 revalidateTag 라는 폭파 명령을 내려야만 비로소 얼음벽이 무너진다고요!"

🗺️ 이 문서의 흐름
정적 캐시 무효화의 필요성 → 경로 단위 파괴 → 태그 기반 파괴 → 실무 아키텍처

🎯 이 문서를 다 읽으면 할 수 있는 것

• CMS/어드민 사이트에서 [저장] 버튼이 눌리는 즉시, 퍼블릭 유저들이 보는 메인 정적 웹사이트의 특정 캐시만 우아하게 초기화해주는 웹훅(Webhook) 서버 API를 설계할 수 있다.
• 멍청한 revalidatePath 대신, 여러 페이지에 점조직처럼 흩어진 동일한 API 결과를 한 방에 부서뜨리는 tag 기반 Invalidation을 설정할 수 있다.

🤔 왜 알아야 하는가

Next.js App Router 아키텍처는 극단적인 캐싱(Caching)을 전제로 만들어졌어. 심화 1/2장에서 어떻게 하면 데이터를 가장 효율적으로 평생 얼려버릴 수 있을까를 배웠다면, 지금부터는 그 얼음을 "내가 원할 때, 원하는 부분만" 박살 내는 법(Invalidation)을 배워야 해.

데이터 생성(C), 수정(U), 삭제(D) 액션이 일어났을 때, 관련 화면의 캐시 껍질을 찢지 못하면 앱은 순식간에 낡은 정보(Stale Data) 만 뱉어내는 깡통이 돼. 프론트엔드의 체감 퀄리티의 90%는 이 "수정한 게 바로바로 화면에 반영되는가?" 에서 판가름 나지. 이것이 바로 시니어의 캐싱 통제력이야.

🏗️ 비유로 먼저 이해하기

🧒 5살에게 설명한다면? (칠판 지우기)

선생님(Next.js)이 칠판에 오늘 급식 메뉴(Data Cache)를 잔뜩 적어놨어. 아이들은 그걸 보고 환호하지.
영철이가 교무실에 가서 급식 메뉴를 "제육볶음"에서 "돈까스"로 바꿨어(DB 업데이트).

❌ 과거 (브라우저 새로고침)
영철이가 복도에서 아무리 "새로고침! 돈까스야!" 소리쳐봐야, 선생님의 칠판에는 여전히 제육볶음이 적혀있어.

✅ 현재 (revalidate 폭파 명령)
영철이가 선생님 귀에 대고 "선생님, 저기 2번째 줄(경로/태그) 급식 메뉴 낡았어요, 좀 지워주세요!" 라고 서버 내부 명령망으로 속삭여.
선생님이 그제야 "어쿠!" 하고 제육볶음을 지워버려(Cache Purge). 다음 아이가 칠판을 봤을 땐 제육이 없으니 요리사한테 뛰어가 "새 메뉴 줘!" 하고 돈까스 데이터를 진정으로 업데이트하게 되는 거야.

🧩 revalidatePath: 무식하게 도끼로 내려찍기 🟢

제일 직관적이고 무식(?)한 파괴 방식이야.
"특정 주소(경로)와 연관된 렌더링 화석과 데이터 캐시를 모조리 다 날려버려라!"

사용법

주로 게시글 작성/수정 API(Route Handler app/api/... 내부)나, 다음 장에서 배울 서버 액션 단에서 사용 돼.

import { revalidatePath } from 'next/cache'
 
// 유저가 상품을 구매한 직후 실행되는 서버 로직이라 가정
export async function POST() {
  await db.purchaseItem(...) // 1. DB 업데이트 (수량 감소)
 
  // 2. 도끼로 경로 강타!
  // "/shop" 페이지의 통째로 구워진 화석 파일(HTML)과 그 안의 모든 Data Cache를 박살낸다!
  revalidatePath('/shop') 
  
  return Response.json({ success: true })
}

장단점

• 장점: 엄청나게 직관적임. "그냥 그 페이지 낡은 거 다 싹 지워!"
• 단점: 만약 /shop 페이지 안에 아무 잘못 없는(안 바뀐) 공지사항이나 배너 캐시 데이터까지 모조리 같이 날아가 버림.
  그리고 더 치명적인 건, /shop 에도 상품 목록이 있고 /mypage/recent 에도 상품 목록이 있다면? 도끼를 들고 다니며 저 경로들을 일일이 전부 노가다로 적어서 파괴명령을 내려야 해.

🌱 revalidateTag: 우아하고 정밀한 저격총 🟡

Next.js 코어 팀이 가장 미는 우아하고 완벽한 해결책이야.
"아무리 여러 파일과 여러 주소에 흩어져있어도, 똑같은 '이름표(Tag)'를 달고 있는 캐시들만 골라서 핀셋으로 저격해 폭파한다!"

1) 명찰 붙이기 (데이터를 가져올 때)

이건 page.tsx든 어디든 fetch를 하는 녀석에게 꼬리표를 달아주는 거야.

// app/shop/page.tsx
const res = await fetch('https://api.my.com/bestseller', {
  next: { tags: ['bestseller-list'] } // 🏷️ 이 통신 결과물 덩어리 캐시에 'bestseller-list'라는 이마표를 붙인다!
})

// app/mypage/page.tsx
const res2 = await fetch('https://api.my.com/bestseller?limit=3', {
  next: { tags: ['bestseller-list'] } // 🏷️ 완전 다른 페이지인데 여기도 같은 이마표를 붙인다!
})

2) 저격 탕! (데이터가 수정될 때)

어드민 서버에서 베스트셀러 상품 1개를 강제로 교체(수정)했어. 이때 웹훅(Webhook) 서버에서 단 한 발의 총알만 쏘면 돼.

import { revalidateTag } from 'next/cache'
 
export async function POST() {
  await db.updateBestseller(...) 
  
  // 🔫 저격 탕!
  // "/shop" 이고 "/mypage" 이고 나발이고 묻지도 따지지도 않고 
  // Next.js 전역에서 'bestseller-list' 명찰이 붙은 모든 얼음 조각만 싹다 찾아내 파괴함!
  revalidateTag('bestseller-list') 
  
  return Response.json({ success: true })
}

이게 바로 마이크로서비스 아키텍처(MSA) 급의 우아한 캐시 분산 통제술(Cache Orchestration)이야.

🛡️ router.refresh(): 유저 브라우저 속살 지우기 🔴

위 두 개의 폭탄 결재선(Path, Tag)은 전부 서버(Node.js 단) 에서만 발동 가능한 무기들이야.
클라이언트 컴포넌트(use client) 내부의 onClick 이벤트에서는 저 폭탄 스위치를 함부로 누를 수가 없어! (보안 정책 상)

클라이언트 단에서 직접 "나 방금 글 지웠는데, 화면 좀 즉시 다시 그려주라!" 라고 명령하고 싶다면 어떻게 해야 할까?
바로 Next.js의 클라이언트 라우터 훅에 달린 refresh() 메서드를 사용하는 거야.

'use client'
import { useRouter } from 'next/navigation'
 
export default function DeleteButton({ id }) {
  const router = useRouter()
 
  const handleDelete = async () => {
    // 1. 컴포넌트 내부에서 백엔드 삭제 API 호출 
    await fetch(`/api/posts/${id}`, { method: 'DELETE' }); 
    
    // 2. 브라우저야! 네 메모리(Router Cache)에 띄워둔 낡은 HTML 껍데기를 버려!
    // 그리고 강제로 화면 깜빡임(F5) 없이 백그라운드로 서버가 주는 최신 렌더링 뷰를 다시 긁어와!
    router.refresh(); 
  }
 
  return <button onClick={handleDelete}>글 삭제</button>
}

🔥 주의할 점!
router.refresh() 는 심화 1장에서 배운 [가장 첫 번째 방어막인 브라우저 단의 Router Cache] 만을 부숴버리는 행위야!
만약 백엔드 삭제 API(DELETE) 쪽에, 본질적인 Next.js 서버의 얼음을 부수는 revalidatePath('/posts') 로직이 안 들어가 있다면?
refresh() 명령을 백날 쳐서 브라우저가 서버에 HTML을 다시 달라고 조르더라도, 서버는 "어? 너 저번 낡은 화석 내가 갖고 있잖냐 가져라 ㅋ" 하고 낡은 화면을 다시 주게 되므로 영원히 지옥도를 맴돌게 돼. 항상 서버 무효화(revalidate) + 클라 무효화(refresh)는 원클릭 한 몸 세트로 가야 해.

💥 에러 해결 카탈로그

에러 메시지가 뜨면 Ctrl+F로 검색해봐.

❌ revalidateTag is not a function 혹은 서버 에러

원인: revalidateTag 등 캐시 파괴 지시자를 클라이언트 컴포넌트("use client") 영역에서 import 해서 버튼 onClick 함수 안에서 직접 부르려고 시전했음.
해결책: 이 파괴 함수는 보안상 오로지 [서버 액션(Server Actions)] 이나 Route Handlers(app/api/) 환경같이 안전한 Node.js 영역 내부에서만 수입(next/cache)해서 돌릴 수 있다.

❌ 태그 저격총을 쐈는데도 글씨가 안 변해요!

원인: fetch 통신부에 { next: { tags: ['my-tag'] } } 꼬리표를 명시하는 걸 깜빡했거나 오타가 난 경우.
해결책: 서버 캐시 덤프 로그를 찍어보고(logging: { fetches: { fullUrl: true } } config 활용), 내가 타격한 태그 이름표의 철자가 정확히 일치하는지 점검할 것.

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

배웠으면 한 번 비틀어서 확인해봐야 해.

1. 상황: 영철이가 쇼핑몰의 메인 상품 목록 페이지(/)와 개인 관심 상품 페이지(/mypage/like) 2곳에 노출되고 있는 item_id=10 번 상품의 가격을 관리자 페이지에서 10만 원에서 5만 원으로 수정(UPDATE)하는 API를 짰다. 만약 영철이가 revalidatePath('/') 도끼질 하나만 하고 끝냈다면, 고객 C가 /mypage/like 페이지에 들어갔을 때 이 상품 가격은 10만 원일까, 5만 원일까?

정답 및 해설:
고객 C는 여전히 낡고 비싼 10만 원짜리 버그 화면을 보게 된다.
revalidatePath('/') 는 오로지 루트(메인 홈페이지) 하나에 쌓인 컴포넌트 트리의 얼음 장벽만 깨부쉈기 때문이다. /mypage/like 쪽에 묻어있는 해당 상품 컴포넌트나 캐시는 영향을 받지 않았다.
이 참사를 막기 위해 상품 가격을 그리는 모든 fetch 단에 { next: { tags: ['item-10'] } } 처럼 고유 태그를 박아 둔 뒤, 관리자 저장 로직에서 revalidateTag('item-10') 한 발만 쐈어야 모든 은신처의 가격 표기가 정상 가격인 5만 원으로 갱신될 수 있다.

🐣 영철이의 퇴근 일기

오늘은 정말 넥스트의 '얼음 깨기(Invalidation)' 기술을 배우면서 감탄을 금치 못했어. 어제 만든 화석이 오늘까지 남아있어 당황했는데, 영호 리드 님이 알려주신 '정밀 타격(revalidateTag)' 덕분에 이제는 내가 원하는 부분만 콕 집어서 최신화할 수 있게 됐어!

💡 오늘의 교훈: "캐시를 만드는 것보다 더 중요한 건, 언제 어떻게 부술지 결정하는 것이다. revalidatePath 로 큼직하게, revalidateTag 로 정교하게 얼음을 깨자!"

가장 신기했던 건 브라우저의 기억력(router.refresh())과 서버의 기억력을 동시에 컨트롤해야 한다는 점이었어. 둘 중 하나라도 어긋나면 유저는 낡은 화면을 보게 된다는 사실에 정신이 번쩍 들더라. 오늘 너무 집중해서 일했더니 어깨가 뻐근하네. 퇴근하고 집 가서 시원한 맥주 한 캔 마시며 오늘 배운 '캐시 폭파' 로직을 다시 한번 머릿속으로 그려봐야겠어. 내일은 더 우아한 무효화 코드를 짜는 개발자가 될 거야! 🐣

🔗 더 알아보기

• Next.js Docs: Caching - Revalidating