Что делают директивы use cache, use cache: private и use cache: remote?

Директивы use cache, use cache: private и use cache: remote

В Next.js 16 директива use cache аналогична use client и use server — она является сигналом компилятору об области кэширования. Три варианта директивы определяют, где и как хранится кэш.

use cache — публичный серверный кэш

Результат компонента или функции кэшируется на сервере и разделяется между всеми пользователями. Подходит для публичных данных: каталоги товаров, статичные страницы, навигация.

// Пример: публичный список категорий
import { cacheLife, cacheTag } from 'next/cache';

export async function CategoryList() {
  'use cache'; // shared server cache
  cacheLife('hours');
  cacheTag('categories');

  const categories = await db.categories.findMany({ orderBy: { name: 'asc' } });
  return (
    <ul>
      {categories.map(c => <li key={c.id}>{c.name}</li>)}
    </ul>
  );
}

use cache: private — пользовательский кэш

Кэш изолирован на уровне пользовательской сессии (например, по cookie сессии или user ID). Данные одного пользователя не видны другому. Подходит для профиля, истории заказов, персонализированных рекомендаций.

import { cookies } from 'next/headers';
import { cacheLife } from 'next/cache';

export async function UserDashboard() {
  'use cache: private'; // private user-scoped cache
  cacheLife('minutes');

  const cookieStore = await cookies();
  const userId = cookieStore.get('user_id')?.value;
  if (!userId) return null;

  const profile = await db.users.findUnique({ where: { id: userId } });
  return (
    <div>
      <h2>Привет, {profile?.name}</h2>
      <p>Баланс: {profile?.balance} руб.</p>
    </div>
  );
}

use cache: remote — внешнее кэш-хранилище

Результат сохраняется во внешнем хранилище (Redis, Vercel KV, другой distributed cache). Это важно для горизонтально масштабируемых деплоев, где несколько инстансов сервера должны делить один кэш.

// Настройка remote cache handler в next.config.ts
import type { NextConfig } from 'next';

const config: NextConfig = {
  experimental: {
    remoteCacheHandler: require.resolve('./cache-handler.js'),
  },
};
export default config;

// cache-handler.js (пример с Redis)
const { createClient } = require('redis');

const client = createClient({ url: process.env.REDIS_URL });
client.connect();

module.exports = class RemoteCacheHandler {
  async get(key) {
    const data = await client.get(key);
    return data ? JSON.parse(data) : null;
  }

  async set(key, data, options) {
    await client.setEx(key, options.revalidate ?? 3600, JSON.stringify(data));
  }

  async revalidateTag(tag) {
    // логика инвалидации по тегу
    const keys = await client.sMembers(`tag:${tag}`);
    await Promise.all(keys.map(k => client.del(k)));
  }
};

// Компонент с remote cache
async function GlobalPricingTable() {
  'use cache: remote'; // хранится в Redis, доступен всем инстансам
  cacheLife('hours');

  const pricing = await fetch('https://billing.example.com/pricing').then(r => r.json());
  return <table>{/* рендер таблицы */}</table>;
}

Сравнительная таблица

• use cache: in-memory на сервере, shared между пользователями, теряется при рестарте процесса
• use cache: private: изолирован по сессии, подходит для персональных данных
• use cache: remote: внешний distributed store, выживает рестарты, нужен для multi-instance деплоев

Подводные камни

• use cache без private для личных данных: ошибка приведёт к тому, что данные пользователя A увидит пользователь B — критическая уязвимость приватности.
• use cache: private требует идентификатора сессии: если cookie сессии отсутствует или изменяется, ключ кэша меняется и кэш не попадает.
• use cache: remote увеличивает latency: сетевой запрос к Redis добавляет 1-5 мс на каждый cache hit — для высоконагруженных страниц это важно.
• Сериализация пропсов как ключа: все три варианта используют входные данные компонента как часть ключа кэша — нельзя передавать Date, Set, Map или функции.
• Экспериментальный статус: вся система директив use cache в Next.js 16 — experimental; конкретные варианты private/remote могут быть переименованы до stable.
• Конфликт с Server Actions: нельзя вызывать Server Action из компонента с use cache напрямую — Server Actions всегда выполняются динамически.
• Отсутствие TTL для private-кэша: если не указать cacheLife, private кэш может жить неожиданно долго и показывать устаревшие персональные данные.

• Отвечать определением без production-сценария.
• Не называть runtime boundary, security boundary или failure mode.
• Игнорировать версию API, observability и тестовую проверку.

• Объясняет механизм своими словами и без выдуманных API.
• Называет реальные риски, диагностику и критерий корректности.
• Связывает ответ с текущей документацией и миграционными ограничениями.