The 'use cache' Directive: Compiler Cache Boundaries and Dynamic I/O in Next.js 16

Архитектурная база#

В предыдущих версиях Next.js модель кэширования строилась на неявных эвристиках вокруг глобального fetch: методы запросов автоматически мемоизировались, а маршруты пытались статически скомпилироваться при сборке, если не обнаруживали явных вызовов динамических API. Это приводило к скрытым побочным эффектам: случайное добавление заголовка ломало статику всего маршрута, а мутации данных требовали сложного разбора многослойного кэша (Data Cache, Full Route Cache, Router Cache).

В Next.js 16 представлена парадигма Dynamic I/O и специализированная подсистема Cache Components.

Фундаментальный принцип новой архитектуры: все операции ввода-вывода (I/O) динамические по умолчанию. Если компоненту или функции требуется кэширование, разработчик явно объявляет это с помощью компиляторной директивы "use cache".

ЭВОЛЮЦИЯ ПАРАДИГМЫ КЭШИРОВАНИЯ NEXT.JS:
┌────────────────────────────────────────────────────────────────────────┐
│ Next.js 13-14 (Heuristic Caching):                                     │
│ [fetch() по умолчанию кэшируется] ──► Неявная статика ──► Побочные баги │
└────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│ Next.js 16 (Dynamic I/O & Cache Components):                           │
│ [Любой I/O по умолчанию динамический] ──► Явная директива "use cache"  │
│ ──► Компиляторная генерация ключей и изоляция RSC Flight Payload       │
└────────────────────────────────────────────────────────────────────────┘

В отличие от устаревшей функции unstable_cache, директива "use cache" является нативной инструкцией для компилятора Next.js (Turbopack / SWC). Компилятор переписывает AST функции или компонента, автоматически извлекая аргументы, переменные из замыкания и детерминированно связывая их с рантаймом кэширования.

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

Директива "use cache" формирует строгую изолированную границу вокруг асинхронного блока кода. Она может применяться на трех уровнях абстракции:

1. Уровень файла (File Level): Директива размещается в самом верху модуля. Все экспортируемые функции и серверные компоненты модуля автоматически оборачиваются в границы кэширования.
2. Уровень асинхронной функции (Function Level): Директива объявляется первой строкой внутри async function. Кэшируется результат возвращаемого значения (JSON-сериализуемые структуры данных: объекты, массивы, примитивы).
3. Уровень React Server Component (Component Level): Директива объявляется внутри асинхронного серверного компонента. Кэшируется скомпилированное поддерево RSC Flight Payload, что исключает повторный рендеринг вложенных серверных компонентов при последующих запросах.

Автоматическая генерация ключей (Cache Keys)#

При использовании unstable_cache разработчики вручную передавали массив строковых идентификаторов (keyParts), что постоянно приводило к коллизиям ключей или утечкам устаревших данных при изменении сигнатуры функции.

В директиве "use cache" компилятор генерирует композитный ключ кэша автоматически на основе трех составляющих:

• AST-хэш функции: Уникальный отпечаток скомпилированного тела функции и файла. Изменение кода функции автоматически делает старый кэш недействительным.
• Сериализованные аргументы: Значения всех входящих параметров вызова, приведенные к детерминированному бинарному представлению.
• Захваченные переменные замыкания (Lexical Scope Capture): Любые константы или переменные из внешней области видимости, к которым обращается функция, компилятор внедряет в ключ кэша.

АРХИТЕКТУРА СОСТАВНОГО КЛЮЧА КЭША:
┌────────────────────────────────────────────────────────────────────────┐
│ COMPOSITE CACHE KEY = HASH(                                           │
│   Build ID + Module Specifier + Function AST Fingerprint +             │
│   Deterministic_JSON(Captured Lexical Scope Variables) +               │
│   Deterministic_JSON(Runtime Arguments)                                │
│ )                                                                      │
└────────────────────────────────────────────────────────────────────────┘

Модификаторы директивы: shared, remote и private#

В распределенных инфраструктурах Next.js 16 поддерживает варианты спецификатора директивы:

• "use cache" — стандартное разделяемое серверное кэширование (Shared Server Cache). Кэш разделяется между всеми пользователями приложения.
• "use cache: remote" — явное указание сохранять результат во внешнем распределенном хранилище (L2/L3: Redis, Memcached, S3), минуя локальную память пода.
• "use cache: private" — контекстно-зависимый кэш (User/Session Scoped Cache). Привязывается к идентификатору сессии входящего запроса (Cookie/Authorization), исключая утечку персональных данных другим пользователям.

На практике применяется#

1. Каталог товаров с мультивалютным расчетом цен (Function Level)#

Сервис интернет-магазина запрашивает базовые цены из реляционной базы данных (PostgreSQL) и конвертирует их по матрице курсов валют. Директива на уровне функции гарантирует, что тяжелая математика и SQL-запрос выполняются только один раз для уникальной комбинации category и targetCurrency.

2. Кэширование скомпилированного RSC Flight Payload (Component Level)#

Серверный компонент документации запрашивает сырой Markdown из Git-репозитория, выполняет подсветку синтаксиса через Shiki и компилирует дерево компонентов. Директива на уровне компонента сохраняет в кэш не сырые данные, а готовый скомпилированный RSC Flight Payload. Браузер получает мгновенный стрим без повторного парсинга AST на стороне Node.js.

3. Изоляция микросервисного клиента (File Level)#

SDK взаимодействия с внутренним биллингом или ERP-системой. Размещение директивы в заголовке файла превращает весь модуль в кэширующий шлюз: все методы SDK автоматически защищают внутреннюю сеть компании от паразитных дублирующих запросов (Request Coalescing).

4. Персонализированный профиль сотрудника (use cache: private)#

Страница внутренней HR-системы отображает статистику отпусков и KPI сотрудника. Использование приватного модификатора позволяет закэшировать тяжелый агрегационный запрос на уровне изолированной пользовательской сессии без риска раскрытия приватных данных коллегам.

Как это работает#

Для включения поддержки Cache Components в Next.js 16 в конфигурационном файле объявляется экспериментальный флаг dynamicIO:

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    // Включение Dynamic I/O и компиляторных директив 'use cache'
    dynamicIO: true,
  },
};

export default nextConfig;

Паттерн 1: Кэширование на уровне асинхронной функции данных#

import { db } from '@/lib/db';

export interface ProductCatalogFilter {
  categoryId: string;
  currency: 'USD' | 'EUR' | 'GBP';
  inStockOnly: boolean;
}

// Функция с гранулярным кэшированием вычислений и запросов
export async function getCachedCatalog(filter: ProductCatalogFilter) {
  'use cache';

  // Компилятор автоматически генерирует ключ из filter.categoryId, 
  // filter.currency и filter.inStockOnly
  const products = await db.product.findMany({
    where: {
      categoryId: filter.categoryId,
      ...(filter.inStockOnly ? { inventory: { gt: 0 } } : {}),
    },
    select: {
      id: true,
      title: true,
      basePriceUSD: true,
    },
  });

  const exchangeRate = await db.exchangeRates.findUnique({
    where: { targetCurrency: filter.currency },
  });

  const rate = exchangeRate?.rate ?? 1.0;

  return products.map((item) => ({
    id: item.id,
    title: item.title,
    price: Math.round(item.basePriceUSD * rate * 100) / 100,
    currency: filter.currency,
  }));
}

Паттерн 2: Кэширование на уровне React Server Component#

В отличие от традиционных функций, кэширование серверного компонента сохраняет сгенерированный виртуальный DOM в формате React Flight Payload. Внутренние серверные зависимости не вызываются повторно.

import { getCachedCatalog } from '@/lib/catalog';
import { ExpensiveBadge } from '@/components/ExpensiveBadge';

interface ShowcaseProps {
  categoryId: string;
  featuredOnly?: boolean;
}

// Кэшируется скомпилированное поддерево Flight Payload
export async function ProductShowcase({ categoryId, featuredOnly = false }: ShowcaseProps) {
  'use cache';

  const items = await getCachedCatalog({
    categoryId,
    currency: 'USD',
    inStockOnly: true,
  });

  const displayItems = featuredOnly ? items.slice(0, 3) : items;

  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6 p-4">
      {displayItems.map((product) => (
        <article key={product.id} className="border border-border p-4 rounded-xl bg-bg-surface">
          <h3 className="font-semibold text-lg text-text-primary">{product.title}</h3>
          <p className="text-accent-cyan font-mono text-xl mt-2">
            ${product.price} {product.currency}
          </p>
          {/* Дочерние серверные компоненты также сериализуются в кэш */}
          <ExpensiveBadge productId={product.id} />
        </article>
      ))}
    </div>
  );
}

Сравнение механизмов кэширования в Next.js#

Распространённые ошибки#

// ❌ ОШИБКА: cookies() запрещен внутри shared кэша
export async function getBadUserData() {
  'use cache';
  const cookieStore = await cookies(); // Фатальная ошибка Dynamic I/O!
  return fetchUserData(cookieStore.get('token')?.value);
}

// ✅ ПРАВИЛЬНО: передача скалярного аргумента через границу
export async function getGoodUserData(authToken: string) {
  'use cache';
  return fetchUserData(authToken);
}

Вопросы с собеседований#