Зачем в файлах Data Access Layer первой строкой пишется import 'server-only'?

Пакет 'server-only' гарантирует, что данный модуль никогда не попадет в клиентский бандл. Если разработчик по ошибке импортирует функцию из этого файла в клиентский компонент ('use client'), сборщик Webpack/Turbopack немедленно выбросит ошибку на этапе компиляции, предотвращая утечку серверных секретов и кода базы данных.

Каким образом в Vitest протестировать инвалидацию кэша через revalidateTag()?

Модуль 'next/cache' мокируется через vi.mock('next/cache', () => ({ revalidateTag: vi.fn() })). В тесте вызывается метод сервиса или экшен мутации, после чего проверяется: expect(revalidateTag).toHaveBeenCalledWith('my-tag-name').

Чем принципиально различаются механизмы React.cache(), unstable_cache() и 'use cache' в Next.js 16?

React.cache() — это встроенная функция React для дедупликации в рамках жизненного цикла одного серверного запроса (хранится в оперативной памяти конкретного потока рендера). Директива 'use cache' в Next.js 16 — это современный декларативный стандарт Cache Components, управляющий долгосрочным Data Cache через cacheLife() и cacheTag(). Функция unstable_cache() — это легаси-API (Next.js 14-15), сохранявший результаты в Data Cache через явную императивную обертку.

Почему передача непримитивных типов (объектов) в аргументы функции, обернутой в React.cache(), требует осторожности?

React.cache() использует алгоритм сравнения Object.is() для сопоставления аргументов. Если передавать объекты по значению (например, { id: '1' }), ссылки на объекты при каждом вызове будут разными, что приведет к полному промаху кэша (Cache Miss). Аргументы функций React.cache() должны быть примитивами (строки, числа, булевы) либо иметь строгую ссылочную идентичность.

Как избежать взаимного влияния тестов при использовании глобального кэша в интеграционных сьютах?

Каждый интеграционный тест должен выполняться с изолированным контекстом: использовать vi.clearAllMocks() и vi.resetModules() в хуке beforeEach, применять уникальные динамические идентификаторы сущностей в фикстурах и изолировать окружение базы данных через транзакционный откат (Rollback).

Как протестировать, что запрос не подвержен уязвимости Cache Poisoning при использовании unstable_cache()?

В тесте симулируются два последовательных вызова функции получения данных для двух разных пользователей (User A и User B). Тест проверяет, что массив keyParts, переданный в unstable_cache, различается для этих вызовов (содержит идентификатор пользователя), исключая возврат закэшированного ответа первого пользователя второму.

Как протестировать обработку таймаутов и падений соединений с базой данных внутри DAL?

Шпион метода ORM настраивается на выброс ошибки соединения (например, vi.mocked(db.select).mockRejectedValue(new Error('Connection timeout'))). Тест проверяет, что DAL корректно логирует сбой, не отдает некорректно кэшированный результат и выбрасывает контролируемое типизированное доменное исключение.

Тестирование Data Access Layer (DAL) и кэширования — Тестирование & QA Automation

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

В архитектуре полнофункциональных приложений Next.js 15 отказ от промежуточного слоя REST/GraphQL API в пользу прямого взаимодействия React Server Components с базой данных создал риск размытия ответственности: SQL-запросы, проверки прав доступа и логика кэширования могут хаотично распределяться по страницам и компонентам.

Решением этой проблемы является паттерн Data Access Layer (DAL). DAL консолидирует все обратные вызовы к базе данных (Prisma, Drizzle, Redis) и служит единственной точкой входа для выборки данных.

Критически важной частью DAL в Next.js является двухуровневая система кэширования:

Per-Request Memoization (React.cache): Обеспечивает дедупликацию вызовов функций внутри одного цикла серверного рендеринга (один входящий HTTP-запрос). Если заголовок, боковое меню и основной контент запрашивают одного и того же пользователя getUser(id), физический запрос к базе выполняется ровно один раз.
Кросс-запросный кэш (unstable_cache): Сохраняет сериализованные результаты вычислений в постоянном кэше (Next.js Data Cache) между запросами разных пользователей, поддерживая инвалидацию по строковым тегам (revalidateTag).

Тестирование DAL позволяет гарантировать целостность данных, предотвратить деградацию производительности из-за избыточных SQL-запросов и исключить утечки конфиденциальной информации между тенантами.

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

В ментальной модели тестирования DAL и кэширования запросы проходят через строгий двухуровневый фильтр до момента обращения к реальной базе данных:

text

Входящий вызов из RSC
                                        │
                                        ▼
+-------------------------------------------------------------------------------+
| Уровень 1: React.cache() (Per-Request Memoization)                           |
| Жизненный цикл: 1 HTTP-запрос. Дедупликация по ссылочной идентичности аргументов|
+-------------------------------------------------------------------------------+
    │ (Cache Miss)                                      │ (Cache Hit: тот же реквест)
    ▼                                                   ▼
+---------------------------------------------------+  Возврат из памяти
| Уровень 2: unstable_cache() (Next.js Data Cache)  |  без обращения к слою 2
| Жизненный цикл: Кросс-запросный, теги, TTL        |
+---------------------------------------------------+
    │ (Data Cache Miss)                                 │ (Cache Hit: по тегам/ключам)
    ▼                                                   ▼
+---------------------------------------------------+  Возврат из кэша
| Физический Data Access Layer                      |  без выполнения SQL
| - Выполнение SQL / Drizzle / Prisma               |
| - Проверка прав текущей сессии                    |
+---------------------------------------------------+
    │
    ▼
[Реальная СУБД: PostgreSQL / MySQL]

При тестировании необходимо проверять:

Что React.cache() не выполняет повторный вызов при повторной передаче тех же аргументов;
Что unstable_cache() формирует корректный ключ кэша (keyParts) с учетом идентификатора тенанта/пользователя во избежание межпользовательской утечки (Cache Poisoning);
Что функция revalidateTag() сбрасывает кэш соответствующих сущностей.

Алгоритм верификации Data Access Layer и кэширования

Проверка server-only изоляцииSecurity

Убедиться, что модуль содержит декларацию 'server-only' и не экспортирует приватные структуры базы.

Тестирование React.cache()Deduplication

Вызвать функцию 3-5 раз с одинаковыми аргументами и зафиксировать строго 1 обращение к базе данных.

Инспекция ключей unstable_cacheKey Isolation

Проверить, что keyParts включает все динамические идентификаторы аргументов (userId, tenantId).

Валидация тегов кэшаTags Assert

Удостовериться, что массив tags содержит гранулярные идентификаторы сущностей (например, 'entity:id').

Проверка сброса revalidateTagInvalidation

Вызвать соответствующий метод мутации и подтвердить вызов revalidateTag с точным именем тега.

Очистка состояния между тестамиCleanup

Сбросить вызовы шпионов и внутреннее состояние кэш-хранилища в блоке beforeEach.

ЧЕКПОИНТ #1

Двухуровневая модель кэширования DAL: React.cache против unstable_cache

+15 XP

В чем заключается принципиальная разница в жизненном цикле и области видимости между React.cache() и unstable_cache() при тестировании DAL?

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

Тестирование дедупликации тяжелых SQL-запросов в дереве RSC: Проверка того, что параллельный рендеринг лейаута и страницы не дублирует запросы профиля компании или настроек сайта.
Валидация уникальности составных ключей кэша: Предотвращение критических уязвимостей, когда данные пользователя A отдаются пользователю B из-за отсутствия userId в ключе keyParts кэша.
Верификация каскадной инвалидации по тегам: Подтверждение того, что мутация сущности приводит к вызову revalidateTag() с ожидаемым именем тега.
Тестирование изоляции контекстов в тестах: Гарантия того, что состояние кэша одного модульного теста не загрязняет последующие тесты в рамках одного воркера Vitest.

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

1. Архитектура безопасного модуля DAL#

Реализуем функцию получения данных организации с использованием React.cache() для дедупликации внутри реквеста и unstable_cache() для разделяемого кэширования.

typescriptsrc/dal/organization.ts

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

export interface OrganizationDTO {
  id: string;
  name: string;
  plan: 'free' | 'pro' | 'enterprise';
  createdAt: Date;
}

// Низкоуровневая выборка из базы данных
async function fetchOrganizationFromDb(orgId: string): Promise<OrganizationDTO | null> {
  const [record] = await db
    .select({
      id: organizations.id,
      name: organizations.name,
      plan: organizations.plan,
      createdAt: organizations.createdAt,
    })
    .from(organizations)
    .where(eq(organizations.id, orgId))
    .limit(1);

  return record ?? null;
}

// Кросс-запросный кэш с тегами инвалидации
export const getCachedOrganization = (orgId: string) =>
  unstable_cache(
    async () => fetchOrganizationFromDb(orgId),
    ['organization-cache-key', orgId],
    {
      revalidate: 3600, // 1 час
      tags: [`org:${orgId}`, 'organizations'],
    }
  )();

// Итоговый метод DAL с дедупликацией внутри одного запроса
export const getOrganization = cache(async (orgId: string): Promise<OrganizationDTO | null> => {
  if (!orgId || typeof orgId !== 'string') {
    throw new Error('Некорректный идентификатор организации');
  }

  return getCachedOrganization(orgId);
});

2. Тестирование дедупликации вызовов через React.cache()#

Для проверки React.cache() в Vitest вызываем мемоизированную функцию несколько раз подряд и проверяем счетчик вызовов шпиона базового метода.

typescriptsrc/dal/organization.memo.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { cache } from 'react';

describe('React.cache (Per-Request Deduplication)', () => {
  it('дедуплицирует параллельные вызовы с идентичными аргументами', async () => {
    const rawFetcherMock = vi.fn().mockImplementation(async (id: string) => {
      return { id, name: `Организация ${id}`, plan: 'enterprise' as const };
    });

    // Оборачиваем мок в нативный React.cache
    const memoizedFetcher = cache(rawFetcherMock);

    // Симулируем параллельные запросы из разных серверных компонентов в рамках одного рендера
    const [result1, result2, result3] = await Promise.all([
      memoizedFetcher('org-123'),
      memoizedFetcher('org-123'),
      memoizedFetcher('org-123'),
    ]);

    // Проверяем эквивалентность результатов
    expect(result1).toEqual(result2);
    expect(result2).toEqual(result3);
    expect(result1.name).toBe('Организация org-123');

    // КЛЮЧЕВОЙ АССЕРТ: физический вызов fetcher произошел ровно 1 раз
    expect(rawFetcherMock).toHaveBeenCalledTimes(1);
    expect(rawFetcherMock).toHaveBeenCalledWith('org-123');
  });

  it('выполняет отдельные вызовы для различных аргументов', async () => {
    const rawFetcherMock = vi.fn().mockImplementation(async (id: string) => ({ id }));
    const memoizedFetcher = cache(rawFetcherMock);

    await Promise.all([
      memoizedFetcher('org-A'),
      memoizedFetcher('org-B'),
    ]);

    expect(rawFetcherMock).toHaveBeenCalledTimes(2);
    expect(rawFetcherMock).toHaveBeenNthCalledWith(1, 'org-A');
    expect(rawFetcherMock).toHaveBeenNthCalledWith(2, 'org-B');
  });
});

3. Тестирование конфигурации unstable_cache: ключи, TTL и теги#

Поскольку unstable_cache управляется внутренним рантаймом Next.js, в интеграционном тесте DAL мы верифицируем параметры, с которыми регистрируется кэш-делегат, гарантируя предотвращение коллизий ключей.

typescriptsrc/dal/organization.cache.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { unstable_cache } from 'next/cache';
import * as dbModule from '@/lib/db';

// Мокируем unstable_cache для перехвата метаданных конфигурации
vi.mock('next/cache', () => ({
  unstable_cache: vi.fn((fn: () => Promise<unknown>, keyParts?: string[], options?: { revalidate?: number; tags?: string[] }) => {
    // Возвращаем функцию-обертку, которая может вызывать оригинальный коллбэк
    return Object.assign(fn, {
      __keyParts: keyParts,
      __options: options,
    });
  }),
  revalidateTag: vi.fn(),
}));

vi.mock('@/lib/db', () => ({
  db: {
    select: vi.fn(),
  },
}));

describe('DAL: unstable_cache Configuration & Security', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('регистрирует кэш с уникальным составным ключом и корректными тегами', async () => {
    const { getCachedOrganization } = await import('./organization');

    const cachedFn = getCachedOrganization('org-prod-42');

    // Проверяем, что unstable_cache был вызван с ожидаемыми параметрами
    expect(unstable_cache).toHaveBeenCalledWith(
      expect.any(Function),
      ['organization-cache-key', 'org-prod-42'],
      {
        revalidate: 3600,
        tags: ['org:org-prod-42', 'organizations'],
      }
    );
  });

  it('гарантирует, что ключ кэша предотвращает смешение данных разных организаций', async () => {
    const { getCachedOrganization } = await import('./organization');

    getCachedOrganization('tenant-alpha');
    getCachedOrganization('tenant-beta');

    const calls = vi.mocked(unstable_cache).mock.calls;

    const keyAlpha = calls[0][1];
    const keyBeta = calls[1][1];

    expect(keyAlpha).toEqual(['organization-cache-key', 'tenant-alpha']);
    expect(keyBeta).toEqual(['organization-cache-key', 'tenant-beta']);
    expect(keyAlpha).not.toEqual(keyBeta);
  });
});

4. Тестирование сброса кэша через revalidateTag()#

Проверяем сервис мутации, который обновляет данные в БД и сбрасывает кэш для конкретной организации.

typescriptsrc/dal/update-organization.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { updateOrganizationPlan } from './organization-mutations';
import { db } from '@/lib/db';
import { revalidateTag } from 'next/cache';

vi.mock('next/cache', () => ({
  revalidateTag: vi.fn(),
  revalidatePath: vi.fn(),
}));

vi.mock('@/lib/db', () => ({
  db: {
    update: vi.fn().mockReturnThis(),
    set: vi.fn().mockReturnThis(),
    where: vi.fn().mockResolvedValue([{ id: 'org-99' }]),
  },
}));

describe('updateOrganizationPlan Mutation', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('инвалидирует тег конкретной организации после успешного обновления', async () => {
    await updateOrganizationPlan('org-99', 'enterprise');

    // Проверяем вызов обновления в БД
    expect(db.update).toHaveBeenCalled();

    // Проверяем точечный сброс тега в Data Cache
    expect(revalidateTag).toHaveBeenCalledWith('org:org-99');
    // Не должен сбрасывать весь список, если обновляется только единичный план
    expect(revalidateTag).not.toHaveBeenCalledWith('all-data');
  });
});

ЧЕКПОИНТ #2

Предотвращение Cache Poisoning и изоляция тестов DAL

+15 XP

Почему при кэшировании приватных пользовательских данных через unstable_cache() критически важно включать userId в массив keyParts?

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

Ошибка: Межпользовательская утечка данных (Cache Poisoning) в unstable_cache

Если функция внутри unstable_cache возвращает приватные данные пользователя, но в массив keyParts не включен userId, данные первого запросившего пользователя закэшируются глобально и будут отдаваться всем последующим пользователям.

typescript

// ❌ КРИТИЧЕСКАЯ УЯЗВИМОСТЬ: Ключ общий, данные приватные
export const getMyPrivateData = (userId: string) =>
  unstable_cache(
    async () => fetchPrivateProfile(userId),
    ['private-user-data'] // Нет userId в ключе!
  )();

// ✅ БЕЗОПАСНО: Ключ уникален для каждого пользователя
export const getMyPrivateData = (userId: string) =>
  unstable_cache(
    async () => fetchPrivateProfile(userId),
    ['private-user-data', userId]
  )();

Ошибка: Путаница между React.cache() и unstable_cache()

React.cache() предназначен исключительно для дедупликации вызовов в рамках одного входящего HTTP-запроса (хранится в оперативной памяти конкретного рендера и уничтожается после его завершения). unstable_cache() сохраняет данные на диск или во внешний Data Cache между разными запросами и пользователями. Их объединение дает максимальный эффект, но заменять один другим нельзя.

Ошибка: Отсутствие директивы 'server-only' в модулях DAL

Если файл DAL случайно импортируется в клиентский компонент ('use client'), секретные переменные окружения, пароли БД или ORM попадут в публичный JavaScript-бандл. Директива import 'server-only'; в первой строке файла приводит к ошибке сборки, если файл попадет на клиент. В тестах важно проверять наличие этой директивы.

Ошибка: Загрязнение кэша между тестами в Vitest

Поскольку React.cache() привязан к глобальному контексту сборщика в тестах, повторный вызов функции в соседнем it() блоке без сброса моков может вернуть значение из предыдущего теста. Используйте beforeEach(() => { vi.clearAllMocks(); }) и изолируйте инстансы функций.

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

На собеседовании спросят7 вопросов

Связанные темы#

Связанные темы

Тестирование React Server Components (RSC)— Интеграция компонентов с серверным Data Access Layer.Интеграционное тестирование Server Actions— Мутации данных и сброс кэша по тегам.Интеграционное тестирование Route Handlers (API)— Использование DAL внутри API эндпоинтов.