Cache Components и директива 'use cache'

В прошлой статье — «Статика, динамика и всё между ними» — маршрут выбирал из двух состояний: собраться целиком на этапе сборки или пересобираться на каждый запрос. Одно обращение к данным запроса переводило в динамику всю страницу — вместе с шапкой, футером и каталогом, которые у всех читателей одинаковые.

Cache Components меняют единицу измерения. Включает их флаг в настройках проекта — без него нет ни директивы, ни cacheLife, ни cacheTag.

// next.config.ts — в проекте объект уезжает через export default
const nextConfig = {
  // без этого флага нет ни "use cache", ни cacheLife, ни cacheTag
  cacheComponents: true
};

Дальше правило простое: то, что ждёт данных и не помечено, считается на каждый запрос; помеченное — кешируется. Разметка, которой ждать нечего, как была статикой, так и осталась. Директива ставится в трёх местах: первой строкой файла (тогда кешируются все его экспортируемые функции), первой строкой компонента или первой строкой обычной функции. Во всех трёх случаях функция обязана быть асинхронной.

// в проекте это import { cacheLife } from "next/cache";
declare function cacheLife(profile: string): void;

type Post = { id: string; title: string };
declare function loadPosts(): Promise<Post[]>;

// уровень данных: в кеш попадает то, что вернула функция
async function getPosts(): Promise<Post[]> {
  "use cache";
  cacheLife("hours");
  return loadPosts();
}

// уровень разметки: в кеш попадает отрисованный кусок дерева
async function PostList() {
  "use cache";
  cacheLife("hours");
  const posts = await getPosts();
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}

Разница между двумя функциями выше — в том, что складывается в кеш. У getPosts это массив объектов, у PostList — уже отрисованный кусок дерева, готовый к отправке в браузер. Директива одна и та же.

Что значит «единица — функция», видно на модели. Страница собирается из трёх частей: шапка одинакова для всех, каталог общий, корзина у каждого своя. Помечены первые две. Прежде чем запускать, посчитайте: сколько раз выполнится каждая часть за два запроса от разных читателей?

const cache = new Map<string, string>();
let headerRuns = 0;
let catalogRuns = 0;
let cartRuns = 0;

// модель "use cache": ключ — имя функции плюс её аргумент
function cached(name: string, arg: string, fn: (arg: string) => string): string {
  const key = name + ":" + arg;
  const hit = cache.get(key);
  if (hit !== undefined) return hit;
  const value = fn(arg);
  cache.set(key, value);
  return value;
}

const header = () => {
  headerRuns += 1;
  return "шапка";
};
const catalog = (page: string) => {
  catalogRuns += 1;
  return "каталог, страница " + page;
};
const cart = (user: string) => {
  cartRuns += 1;
  return "корзина: " + user;
};

function renderPage(user: string): string {
  return [
    cached("header", "", header),
    cached("catalog", "1", catalog),
    cart(user)
  ].join(" | ");
}

console.log(renderPage("аня"));
console.log(renderPage("боря"));
console.log(headerRuns, catalogRuns, cartRuns);

Шапка и каталог посчитались по одному разу на двоих, корзина — дважды. Страница при этом не «статическая» и не «динамическая»: она смешанная, и таких страниц в приложении большинство.

Страница перестала быть единицей кеша. Единица — функция; страница просто собрана из функций с разными сроками жизни.

Запись в кеше ищется по ключу, и Next собирает его из четырёх слагаемых: идентификатор сборки (после выката все записи считаются заново), идентификатор функции — хеш её места и сигнатуры в коде, сериализованные аргументы и, только в режиме разработки, хеш горячей перезагрузки.

«Сериализованные» — это не «те же самые объекты». Разница видна на модели: два вызова с разными объектами одинакового содержания. Сколько раз мы сходим в базу?

const store = new Map<string, string[]>();
let queries = 0; // сколько раз мы правда сходили в "базу"

function cached(fn: (filter: { category: string }) => string[]) {
  return (filter: { category: string }) => {
    // Next кладёт в ключ сериализованные аргументы, а не ссылку на объект
    const key = JSON.stringify([filter]);
    const hit = store.get(key);
    if (hit !== undefined) return hit;
    const value = fn(filter);
    store.set(key, value);
    return value;
  };
}

const getProducts = cached((filter) => {
  queries += 1;
  return [filter.category + ": 12 товаров"];
});

getProducts({ category: "tea" });
getProducts({ category: "tea" });
getProducts({ category: "cocoa" });
console.log(queries);

Два раза: { category: "tea" } и второй такой же объект дали один ключ. Это ровно то поведение, которого ждёшь от кеша, — и ровно то, которого не будет, если ключом сделать сам объект-фильтр.

const store = new Map<{ category: string }, string[]>();
let queries = 0;

function getProducts(filter: { category: string }): string[] {
  const hit = store.get(filter); // ключ — сама ссылка на объект
  if (hit !== undefined) return hit;
  queries += 1;
  const value = [filter.category + ": 12 товаров"];
  store.set(filter, value);
  return value;
}

getProducts({ category: "tea" });
getProducts({ category: "tea" });
getProducts({ category: "cocoa" });
console.log(queries);

Второе слагаемое неочевиднее: переменные, захваченные из внешней области. Функция помнит окружение, в котором родилась (это замыкания из части I), и Next такие переменные тоже связывает как аргументы — они попадают в ключ. Зачем, видно на кеше, который так не делает. Что напечатает вторая строка?

const store = new Map<string, string>();
let queries = 0;

// так пишут кеш руками: ключ собираем сами
function makeReport(userId: string) {
  return function report(period: string): string {
    const hit = store.get(period);
    if (hit !== undefined) return hit;
    queries += 1;
    const value = "отчёт за " + period + ", пользователь " + userId;
    store.set(period, value);
    return value;
  };
}

console.log(makeReport("1")("сентябрь"));
console.log(makeReport("2")("сентябрь"));
console.log(queries);

Отчёт первого пользователя достался второму: в ключе оказался только период, а userId остался в замыкании. У Next такого не выйдет — захваченная переменная входит в ключ, и у второго пользователя будет своя запись. Отсюда практическое следствие: чем крупнее вход, тем больше разных записей, поэтому в кешированную функцию передают идентификатор, а не весь объект пользователя.

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

Строка «только насквозь» — это приём, ради которого стоит запомнить таблицу: кешированная оболочка может обнимать динамическое содержимое, если она в него не заглядывает.

declare function cacheLife(profile: string): void;

async function CachedShell({ children }: { children: React.ReactNode }) {
  "use cache";
  cacheLife("days");
  // children не читаем и не разбираем: они проходят насквозь ссылкой,
  // поэтому внутри кешированной оболочки может жить динамика
  return (
    <div>
      <h1>Каталог</h1>
      {children}
    </div>
  );
}

Директива без cacheLife тоже работает — просто берётся профиль default, и срок жизни перестаёт быть виден в месте вызова. Поэтому в документации рекомендуют писать cacheLife в каждой кешируемой функции, даже когда числа вас устраивают.

Профиль — это три числа, и каждое отвечает за свой слой.

Встроенные профили названы по порядку величины. Числа ниже — из Next 16; в своём проекте их видно во всплывающей подсказке над cacheLife.

Два серверных числа проще один раз увидеть, чем прочитать. В модели ниже время двигается руками, revalidate — минута, expire — пять. Предскажите третью строку вывода: запрос пришёл на девяностой секунде, запись уже пора обновлять — что получит этот запрос?

let now = 0; // условные секунды: время двигаем руками, чтобы вывод не плавал
let computed = 0;
let entry: { value: number; at: number } | null = null;

const REVALIDATE = 60;
const EXPIRE = 300;

function compute(): number {
  computed += 1;
  return computed;
}

function read(): string {
  if (entry === null || now - entry.at > EXPIRE) {
    entry = { value: compute(), at: now };
    return "ждали расчёт -> " + entry.value;
  }
  if (now - entry.at > REVALIDATE) {
    const old = entry.value;
    entry = { value: compute(), at: now }; // обновление идёт после ответа
    return "отдали старое " + old + ", обновили в фоне";
  }
  return "отдали из кеша " + entry.value;
}

console.log(read());
now = 30;
console.log(read());
now = 90;
console.log(read());
now = 100;
console.log(read());
now = 500;
console.log(read());
console.log(computed);

Запрос, который запустил обновление, сам получил старое значение — и не ждал ни секунды. Ждать пришлось только последнему: к пятисотой секунде запись просрочена, отдавать нечего. Так и работает stale-while-revalidate: медленный расчёт достаётся фону, а читателю — то, что уже посчитано.

В модели нет stale: это число живёт в браузере читателя, а не в серверном кеше.

Кроме имён профиль можно задать объектом — для разового случая, — а свои имена объявляются в настройках рядом со встроенными.

declare function cacheLife(
  profile: string | { stale?: number; revalidate?: number; expire?: number }
): void;
declare function loadRates(): Promise<number>;

async function getRates(): Promise<number> {
  "use cache";
  // разовый случай: подходящего профиля в проекте нет
  cacheLife({ stale: 60, revalidate: 300, expire: 3600 });
  return loadRates();
}

// next.config.ts
const nextConfig = {
  cacheComponents: true,
  cacheLife: {
    // своё имя рядом со встроенными; пропущенные числа берутся из default
    editorial: {
      stale: 600, // 10 минут
      revalidate: 3600, // 1 час
      expire: 86400 // 1 сутки
    }
  }
};

Кешированная функция выполняется в изоляции: cookies(), headers() и searchParams ей недоступны. Запрет идёт по стеку вызовов — вспомогательная функция, которую она позвала, упадёт с той же ошибкой next-request-in-use-cache. Причина простая: запись кеша одна на всех, а данные запроса у каждого свои; мы только что видели, чем это кончается.

Рабочий приём — прочитать данные запроса снаружи и передать аргументом. Тогда значение честно войдёт в ключ, и общая запись появится у всех, у кого этот аргумент совпал.

declare function cacheLife(profile: string): void;
declare function cookies(): Promise<{
  get(name: string): { value: string } | undefined;
}>;
declare function loadOffers(city: string): Promise<string[]>;

// кешируется: у всех читателей одного города запись общая
async function Offers({ city }: { city: string }) {
  "use cache";
  cacheLife("hours");
  const offers = await loadOffers(city);
  return (
    <ul>
      {offers.map((offer) => (
        <li key={offer}>{offer}</li>
      ))}
    </ul>
  );
}

// не кешируется: читает запрос — поэтому живёт под Suspense
async function CityOffers() {
  const city = (await cookies()).get("city")?.value ?? "spb";
  return <Offers city={city} />;
}

function Page() {
  return (
    <main>
      <h1>Акции</h1>
      <React.Suspense fallback={<p>Подбираем город…</p>}>
        <CityOffers />
      </React.Suspense>
    </main>
  );
}

По частям здесь происходит вот что. Заголовок и запасная разметка Suspense уходят в предрендеренную оболочку — они не зависят ни от кого. Когда приходит запрос, читаются куки, и на место запасной разметки приезжает Offers — из кеша, если кто-то из этого города заходил недавно, иначе с расчётом. Для города, а не для человека: людей много, городов десяток.

Отдельная забота — значения, которые обязаны быть разными на каждом запросе: Math.random(), Date.now(), crypto.randomUUID(). Cache Components не дают им втихую застыть в кеше: перед такими вызовами объявляют, что это дело запроса, вызвав connection(), и, как всё запросное, заворачивают в Suspense.

Есть и вариант директивы для личного: "use cache: private" кеширует на одного читателя и умеет читать данные запроса. Он нужен редко — обычно хватает приёма выше, когда из запроса достают одно значение и делают его аргументом общей записи.

На практике выбор сводится к двум вопросам: одинаков ли ответ для всех читателей и как быстро он устаревает. Первый вопрос решает, будет ли директива вообще, второй — какой профиль.

Время — не единственный повод обновить запись. Статья меняется не по часам, а когда её отредактировали: такой функции ставят длинный профиль и вешают метку.

declare function cacheLife(profile: string): void;
declare function cacheTag(...tags: string[]): void;

type Post = { id: string; title: string };
declare function loadPost(id: string): Promise<Post>;

async function getPost(id: string): Promise<Post> {
  "use cache";
  // статья устаревает не по часам, а когда её отредактировали
  cacheLife("max");
  cacheTag("post:" + id);
  return loadPost(id);
}

Метка сама ничего не сбрасывает — она даёт имя, по которому запись можно объявить устаревшей после записи в базу. Кто и когда это делает, разбирает статья «Что происходит после мутации: revalidatePath и revalidateTag»: сброс по метке живёт рядом с серверным действием, а не рядом с кешем.

И последнее, что стоит держать в голове: по умолчанию записи лежат в памяти процесса. На своём сервере они переживают запросы, а в бессерверной среде каждый запрос может достаться новому экземпляру — тогда общего кеша между запросами почти нет, и польза остаётся в основном от предрендера. Для общего хранилища есть отдельный вариант директивы, "use cache: remote", но это уже разговор про площадку, а не про React.