🧨 Next.js 심화 3장: Cache Invalidation — 화석을 무효화하는 철퇴

📋 목차

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

📌 이 문서를 읽기 전에

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

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

• 영철(신입): "게시물 수정 버튼을 누르고 서버 API에서 DB 업데이트까지 성공했는데, window.location.reload()를 해도 예전 글씨만 떠요. 이제 서버 캐시를 갱신해야 한다는 건 알겠는데, 어떤 API를 골라야 할까요?"
• 영호(리드): "좋아요. 이제 질문이 훨씬 정확해졌네요. 경로가 낡았으면 revalidatePath, 데이터 정체성이 낡았으면 revalidateTag나 updateTag를 검토하세요. 브라우저 새로고침은 서버 캐시 정책을 바꾸지 못합니다."

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

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

• CMS/어드민 사이트에서 [저장] 버튼이 눌리는 즉시, 퍼블릭 유저들이 보는 메인 정적 웹사이트의 특정 캐시만 우아하게 초기화해주는 웹훅(Webhook) 서버 API를 설계할 수 있다.
• 경로 단위 revalidatePath와 데이터 단위 revalidateTag/updateTag를 구분해, 여러 페이지에 흩어진 동일 데이터의 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" 경로와 관련된 캐시를 다시 검증 대상으로 표시한다.
  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(...)
 
  // stale-while-revalidate 방식으로 태그가 붙은 캐시를 갱신한다.
  revalidateTag('bestseller-list', 'max')
 
  return Response.json({ success: true })
}

사용자가 방금 수정한 값을 즉시 봐야 하는 Server Action 흐름이라면 updateTag('bestseller-list')가 더 어울릴 수 있다. revalidateTag('tag', 'max')는 낡은 값을 잠깐 보여주면서 배경에서 새 값을 준비하는 stale-while-revalidate 성격에 가깝다.

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

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

클라이언트 단에서 직접 "나 방금 글 지웠는데, 화면 좀 즉시 다시 그려주라!" 라고 명령하고 싶다면 어떻게 해야 할까?
바로 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) 쪽에 revalidatePath('/posts')나 관련 태그 갱신이 없다면?
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 활용), 내가 타격한 태그 이름표의 철자가 정확히 일치하는지 점검할 것.

🏁 이번에 배운 내용 총정리

📝 마무리 퀴즈

Q1. 상품 가격이 홈, 검색 결과, 관심 상품 페이지에 모두 노출된다. 관리자 저장 후 어떤 무효화가 가장 정밀할까?

✅ 정답: 상품 데이터를 가져오는 지점에 같은 태그를 붙이고 revalidateTag('product-10', 'max') 또는 즉시 만료가 필요하면 updateTag('product-10')를 호출한다.

💡 상세 해설: revalidatePath('/')는 홈 경로만 겨냥한다. 같은 상품이 여러 경로에 흩어져 있으면 경로 기준 무효화는 빠뜨리기 쉽다. 태그는 데이터의 정체성을 기준으로 묶으므로 더 정밀하다. 다만 최신 Cache Components 모델에서 revalidateTag는 stale-while-revalidate 성격이므로, 방금 수정한 관리자가 즉시 새 값을 봐야 한다면 Server Action 안에서 updateTag를 고려한다.

Q2. router.refresh()를 눌렀는데도 화면이 낡은 데이터를 다시 받는다. 무엇을 의심해야 할까?

✅ 정답: 클라이언트 Router Cache만 비웠고, 서버의 Data Cache나 Full Route Cache가 아직 갱신되지 않았을 가능성이다.

💡 상세 해설: router.refresh()는 현재 브라우저 세션의 RSC Payload를 다시 요청하게 만든다. 하지만 서버가 여전히 낡은 캐시를 들고 있으면 사용자는 같은 낡은 응답을 다시 받는다. 영호가 말한 순서는 "서버 캐시를 무효화하고, 필요하면 클라이언트 화면을 새로 요청한다"이다.

Q3. 영철이의 테스트 타임: 글 작성 Server Action이 성공하면 방금 작성한 글 상세로 이동한다. 사용자가 자기 글을 바로 봐야 한다면 어떤 갱신 전략이 어울릴까?

✅ 정답: 글 목록/상세에 붙은 태그를 즉시 만료하는 updateTag 또는 필요한 경로의 revalidatePath를 Server Action 안에서 호출한 뒤 이동한다.

💡 상세 해설: 작성 직후는 read-your-own-writes가 중요한 순간이다. 배경 갱신으로 잠깐 낡은 목록을 보여줘도 되는 CMS 공개 목록과 다르다. Server Action은 데이터 변경과 캐시 갱신을 같은 서버 흐름에 둘 수 있으므로, 성공 조건이 확정된 뒤 태그나 경로를 갱신해야 한다.

🐣 영철이의 퇴근 일기

오늘은 캐시 무효화를 "캐시를 끄는 일"로 보면 안 된다는 걸 배웠다. revalidatePath는 화면 경로를 기준으로 넓게 치고, 태그 기반 갱신은 데이터의 정체성을 기준으로 좁게 친다. 그리고 사용자가 방금 바꾼 값을 바로 봐야 하는지, 조금 늦게 반영되어도 되는지에 따라 선택도 달라진다.

💡 "무효화 전략은 데이터 변경 코드의 일부다. 저장 로직과 떨어져 있으면 언젠가 낡은 화면이 생긴다."

다음부터는 저장 액션을 만들 때 PR 설명에 "어떤 캐시를 갱신하는가"를 꼭 적겠다. 홈만 새로고침해서 통과시키는 대신, 같은 데이터가 숨어 있는 목록과 상세, 내 페이지까지 같이 검증해야겠다.

🔗 더 알아보기

• Next.js Docs: Caching - Revalidating