#25. Caching in Route Handlers

Next.js의 “라우트 핸들러(Route Handler)”의 캐싱 동작 특성

 

현재시간을 출력해 주는 API 응답을 이용하여, 캐싱 동작 확인

import { NextResponse } from "next/server";

// 응답 캐쉬를 STATIC으로(갱신안함) <
export const dynamic = "force-static";

//export const revalidate = 10;

// 항상 요청 시점 실행을 강제
// export const dynamic = "force-dynamic";


// 빌드 시 한 번 실행됨
// const now = new Date().toLocaleTimeString();

export async function GET() {
  return NextResponse.json({ time: new Date().toLocaleTimeString() });
  // return NextResponse.json({ time: now });
}

⚙️ Next.js 캐시 정책 요약 (v15/v16 기준)

항목기본 캐시 동작강제 설정비고

Page (page.tsx)	Static	export const dynamic = "force-dynamic" 으로 변경 가능	서버컴포넌트 SSR/SSG 제어용
Route Handler (route.ts)	Dynamic	export const dynamic = "force-static" 으로 캐시 시도 가능, 단 요청 의존 시 무시됨	API 응답용
fetch() 호출	기본 Static 캐시	{ cache: "no-store" } or { next: { revalidate: 0 }} 로 강제 동적화 가능
cookies()/headers() 호출	Static → 자동으로 Dynamic 전환	캐싱 불가	요청별 쿠키/헤더가 다르기 때문

---

🧪 예제 비교

(1) 완전 정적 — 시간이 고정됨 ✅

 

// app/api/time-static/route.ts
import { NextResponse } from "next/server";

export const dynamic = "force-static";

const now = new Date().toLocaleTimeString(); // 빌드 시 한 번 실행됨

export async function GET() {
  return NextResponse.json({ time: now });
}

• 위 코드는 빌드 시점의 시간이 고정되어 응답됨
• 즉, 한 번 빌드 후에는 계속 같은 시간이 나옴 (완전 SSG)

---

(2) 요청마다 갱신 — 시간이 계속 바뀜 ⏱️

 

// app/api/time-dynamic/route.ts
import { NextResponse } from "next/server";

export const dynamic = "force-dynamic";

export async function GET() {
  return NextResponse.json({ time: new Date().toLocaleTimeString() });
}

• force-dynamic은 요청 시마다 실행(SSR)
• 모든 요청에 대해 새 시간이 반환됨

---

(3) Revalidate 예시 — 일정 주기로 자동 갱신 ⏳

 

// app/api/time-revalidate/route.ts
import { NextResponse } from "next/server";

// 10초 단위 재생성 (ISR)
export const revalidate = 10;

export async function GET() {
  return NextResponse.json({ time: new Date().toLocaleTimeString() });
}

• 최초 요청 시 실행되고,
• 10초 이후에 다시 요청이 들어오면 새 캐시 생성
• ISR(Incremental Static Regeneration) 형태

---

🧠 핵심 요약

설정실행 시점설명

dynamic = "force-static"	빌드 시 1회	완전 정적 (요청 시 실행 안 함)
dynamic = "force-dynamic"	요청 시마다	SSR / 실시간 실행
revalidate = N	일정 주기	ISR: 캐시+주기적 갱신
cookies()/headers() 사용 시	자동 Dynamic	Static 강제 불가

---

✅ 정리된 결론

현재 예제에서 “시간이 매번 새로 찍히는 이유”는
new Date()가 요청 시마다 실행되기 때문이며,
force-static은 이 함수를 “빌드 시점”에 한 번만 실행하도록 해야 효과가 있습니다.

즉, 고정된 시간 응답을 원하면 이렇게 수정하세요 👇

 

import { NextResponse } from "next/server";

export const dynamic = "force-static";

const fixedTime = new Date().toLocaleTimeString(); // build-time capture

export async function GET() {
  return NextResponse.json({ time: fixedTime });
}