Кешування та ревалідація: 4 рівні кешу Next.js

Навіщо це потрібно#

У високонавантажених веб-застосунках затримка бази даних та зовнішніх мікросервісів безпосередньо визначає TTFB та користувацький досвід. Неконтрольоване виконання повторюваних SQL-запитів та HTTP-викликів перевантажує обчислювальні потужності сервера та призводить до вичерпання пулів з'єднань.

В архітектурі Next.js App Router реалізована багаторівнева система кешування, що об'єднує можливості ядра React та рантайму Next.js. Вона охоплює весь життєвий цикл даних — від дедуплікації викликів в оперативній пам'яті одного серверного рендеру до розподіленого зберігання статичних сторінок на CDN та кешування сегментів маршрутів у браузері клієнта.

Глибоке розуміння кожного рівня кешу, правил його деоптимізації та механізмів он-деманд інвалідації відрізняє розробника, який бореться із застарілими даними в продакшені, від архітектора, що проєктує консистентні та швидкі розподілені системи.

Ментальна модель#

У Next.js функціонують 4 незалежні рівні кешування, кожен з яких вирішує вузькоспеціалізовану задачу, має ізольовану область видимості та власний життєвий цикл:

1. Request Memoization (React): Кеш в оперативній пам'яті сервера на час генерації однієї відповіді. Запобігає дублюванню мережевих запитів між ізольованими серверними компонентами дерева.
2. Data Cache (Next.js): Постійний серверний кеш (диск, KV або Redis), що зберігає відповіді HTTP-запитів і результати важких обчислень між запитами різних клієнтів та сесій.
3. Full Route Cache (Next.js): Серверний кеш скомпільованого HTML-документа та бінарного графа RSC Flight Payload для статичних маршрутів.
4. Client Router Cache (Next.js / Browser): Кеш сегментів інтерфейсу в оперативній пам'яті вкладки браузера, що забезпечує миттєвий перехід між екранами без повторного звернення до сервера (Soft Navigation).

Нижче представлено інтерактивний симулятор потоку кешування. Перемикайте сценарії, щоб вивчити проходження запиту крізь усі 4 рівні:

Синтаксис та API#

1. Request Memoization (React)#

React автоматично дедуплікує виклики fetch з однаковим URL та однаковим набором опцій у межах одного дерева рендерингу серверних компонентів. Життєвий цикл цього кешу обмежений мілісекундами генерації відповіді.

[!IMPORTANT] Request Memoization не використовується спільно між користувачами та сесіями. Це оптимізація всередині окремого запиту єдиного дерева рендеру React Server Components. Для неї немає глобального прапорця вимкнення, проте її можна обійти, передавши унікальний AbortController (через властивість signal) у fetch.

// app/components/Header.tsx
export async function Header() {
  // Виконується реальний мережевий запит
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <header>Користувач: {user.name}</header>;
}

// app/components/Sidebar.tsx
export async function Sidebar() {
  // Дані миттєво витягуються з Request Memoization (RAM) без повторного HTTP-запиту
  const user = await fetch('https://api.internal/user/me').then(r => r.json());
  return <aside>Роль: {user.role}</aside>;
}

2. Data Cache (Керування мережевим кешем)#

У версіях Next.js 15+ стандартний fetch за замовчуванням є некешованим (cache: 'no-store'). Кешування на рівні Data Cache вмикається явно.

// 1. За замовчуванням у Next.js 15+: no-store (завжди свіжі дані з мережі)
const freshData = await fetch('https://api.internal/rates');

// 2. Персистентне кешування (зберігається до явної ревалідації)
const immutableData = await fetch('https://api.internal/dictionary', {
  cache: 'force-cache',
});

// 3. Time-based revalidation (Stale-While-Revalidate на 60 секунд)
const catalog = await fetch('https://api.internal/products', {
  next: { revalidate: 60 },
});

// 4. Тегування запитів для точкової On-demand інвалідації
const profile = await fetch('https://api.internal/user/10', {
  next: { tags: ['user-10', 'users'] },
});

3. On-demand Revalidation: revalidateTag та revalidatePath#

Для скидання застарілих даних за подією (Server Action, обробка Webhook) використовуються функції з модуля next/cache. Вони одночасно інвалідують записи в Data Cache та залежні сегменти у Full Route Cache.

'use server';

import { revalidatePath, revalidateTag } from 'next/cache';
import { db } from '@/lib/db';
import { products } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export async function updateProductPrice(productId: string, newPrice: number): Promise<{ success: boolean }> {
  // 1. Мутація даних в основній базі даних
  await db.update(products).set({ price: newPrice }).where(eq(products.id, productId));

  // 2. Точкове скидання кешу за тегом (зачіпає всі запити з цим тегом у всьому застосунку)
  revalidateTag(`product-${productId}`);
  revalidateTag('catalog-list');

  // 3. Інвалідація конкретного маршруту
  revalidatePath(`/products/${productId}`, 'page');

  return { success: true };
}

Практичні патерни#

Патерн 1: Stale-While-Revalidate (SWR) під капотом#

При встановленні опції next: { revalidate: 60 } система працює за чітким протоколом:

1. Запит T = 0c (Cold Start): Промах кешу. Сервер очікує відповіді від джерела, віддає дані клієнту та зберігає їх у Data Cache з часовою міткою.
2. Запити T = 1..59c (Cache Hit): Усі користувачі миттєво отримують відповідь із Data Cache без звернення до БД.
3. Запит T = 60c+ (Stale Window): Дані визнаються застарілими (stale). Next.js миттєво віддає клієнту старі дані (TTFB не просідає), але в окремому фоновому воркері ініціює повторний запит до джерела.
4. Запит T = 62c+ (Cache Replaced): Після успішного завершення фонового запиту кеш перезаписується, і наступні користувачі отримують актуалізовану версію.

Патерн 2: Кешування ORM/SQL через unstable_cache та 'use cache'#

Прямі запити до баз даних (Prisma, Drizzle, pg) не використовують глобальний fetch, тому не потрапляють у Data Cache автоматично. Для них застосовується unstable_cache, або директива 'use cache' (Next.js 15.1+ з прапорцем dynamicIO).

import 'server-only';
import { unstable_cache } from 'next/cache';
import { db } from '@/lib/db';
import { projects } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export interface ProjectDTO {
  id: string;
  name: string;
  stars: number;
}

export const getCachedProject = (projectId: string) => {
  return unstable_cache(
    async (id: string): Promise<ProjectDTO | null> => {
      const record = await db.query.projects.findFirst({
        where: eq(projects.id, id),
      });
      return record ?? null;
    },
    ['project-detail-key', projectId], // Ключі кешу
    {
      revalidate: 3600, // 1 година
      tags: [`project-${projectId}`, 'projects'],
    }
  )(projectId);
};

Патерн 3: Opt-out та деоптимізація статичного Full Route Cache#

Маршрут автоматично перемикається зі статичного режиму (Static Generation) у динамічний (Dynamic Rendering при кожному запиті), якщо в його коді викликаються динамічні функції:

import { cookies, headers } from 'next/headers';

// Примусове вимкнення Full Route Cache на рівні всього сегмента
export const dynamic = 'force-dynamic';

export default async function AnalyticsPage() {
  // Асинхронне читання заголовків та cookies у Next.js 15+ робить рендер строго динамічним
  const headersList = await headers();
  const userAgent = headersList.get('user-agent') ?? 'unknown';

  const cookieStore = await cookies();
  const sessionId = cookieStore.get('sid')?.value;

  return (
    <main className="p-6">
      <h1>Системна аналітика</h1>
      <p>Клієнт: {userAgent}</p>
      <p>Сесія: {sessionId}</p>
    </main>
  );
}

Поширені помилки#

// ❌ ПОМИЛКА: Спроба читання cookies всередині кешованої функції
const getAuthData = unstable_cache(
  async () => {
    const cookieStore = await cookies(); // Викличе виняток DynamicServerError!
    return fetchUserData(cookieStore.get('token')?.value);
  },
  ['auth-user-key']
);

// ✅ ПРАВИЛЬНО: Передавайте динамічні дані у вигляді явних аргументів, що входять до ключа кешу
const getAuthData = (token: string) => 
  unstable_cache(
    async (authToken: string) => fetchUserData(authToken),
    ['auth-user-key', token]
  )(token);

// ❌ Помилка: Ключ кешу статичний, тому всі клієнти побачать дані першого запитаного ID
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user'] 
);

// ✅ Правильно: ID включений до складеного ключа кешу
const getUser = unstable_cache(
  async (id: string) => db.query.users.findFirst(eq(users.id, id)),
  ['user', id]
);

Порівняльний аналіз 4 рівнів кешу#

Питання для співбесіди#