¿Por qué los archivos del Data Access Layer deben comenzar con 'import server-only'?

El paquete 'server-only' desencadena un error de compilación inmediato si el archivo es importado en un componente de cliente ('use client'). Esto protege credenciales de bases de datos, consultas ORM privadas y secretos del negocio frente a fugas hacia los bundles públicos de JavaScript.

¿Cómo se prueba la invalidación de caché con revalidateTag() en Vitest?

Se mockea el módulo 'next/cache' con vi.mock('next/cache', () => ({ revalidateTag: vi.fn() })). Se invoca la función del servicio o Server Action que muta los datos y se verifica con expect(revalidateTag).toHaveBeenCalledWith('nombre-del-tag').

¿Cuál es la diferencia fundamental entre React.cache() y unstable_cache() en Next.js 15?

React.cache() es una utilidad nativa de React para memoizar funciones en el ciclo de vida de una única petición del servidor, reteniendo resultados en la memoria volátil de dicho render. unstable_cache() es una API de Next.js que persiste resultados serializados en una Data Cache compartida entre múltiples peticiones HTTP y usuarios, con soporte para TTL e invalidación por tags mediante revalidateTag.

¿Por qué pasar objetos como argumentos a funciones envueltas en React.cache() exige extrema precaución?

React.cache() emplea Object.is() para cotejar argumentos. Si se pasan objetos recién creados ({ id: '1' }), las referencias en memoria serán distintas en cada invocación, produciendo un fallo de caché total (Cache Miss). Los argumentos deben ser primitivos (strings, números, booleanos) o poseer estricta identidad referencial.

¿Cómo evitar la contaminación cruzada entre pruebas al interactuar con cachés globales?

Se limpian mocks y módulos en beforeEach mediante vi.clearAllMocks() y vi.resetModules(), se emplean identificadores dinámicos únicos en las fixtures y se envuelven las operaciones de base de datos en transacciones con Rollback para que cada prueba se ejecute en un estado limpio.

¿Cómo se prueba que una consulta es inmune al Cache Poisoning al usar unstable_cache()?

La prueba ejecuta dos llamadas sucesivas para dos organizaciones o usuarios diferentes (User A y User B) y comprueba que el array keyParts suministrado a unstable_cache contiene el identificador respectivo. Esto verifica que se generen claves distintas, impidiendo que un usuario reciba datos cacheados de otro.

¿Cómo probar la gestión de caídas y timeouts de conexión a la base de datos dentro del DAL?

Se configura el espía del ORM para rechazar la promesa con un error de conexión (ej. vi.mocked(db.select).mockRejectedValue(new Error('Connection timeout'))). La prueba verifica que el DAL registre el incidente, no almacene en caché datos nulos erróneos y lance una excepción de dominio fuertemente tipada.

Pruebas de Data Access Layer (DAL) y Caché — Pruebas y Automatización QA

Base Arquitectónica#

En la arquitectura de aplicaciones fullstack modernas en Next.js 15, prescindir de capas intermedias de API REST o GraphQL para permitir la comunicación directa de los React Server Components con la base de datos introdujo el riesgo de difuminar responsabilidades: las consultas SQL, las verificaciones de autorización y las políticas de caché pueden terminar dispersas caóticamente entre páginas y componentes.

La solución arquitectónica a este problema es el patrón Data Access Layer (DAL). El DAL consolida todas las interacciones con la base de datos (Prisma, Drizzle, Redis) y actúa como único punto de entrada para la obtención de datos.

Un elemento crítico del DAL en Next.js es su sistema de caché de dos niveles:

Per-Request Memoization (React.cache): Proporciona deduplicación de invocaciones a funciones dentro de un mismo ciclo de renderizado del servidor (una única solicitud HTTP entrante). Si la cabecera, la barra lateral y la vista principal solicitan el mismo registro de usuario mediante getUser(id), la consulta física a la base de datos se ejecuta exactamente una vez.
Caché entre solicitudes (unstable_cache): Persiste los resultados serializados de cómputo en la Next.js Data Cache entre peticiones de distintos usuarios, admitiendo invalidación bajo demanda mediante etiquetas (revalidateTag).

Las pruebas del DAL garantizan la integridad de los datos, previenen degradaciones de rendimiento causadas por consultas SQL redundantes y suprimen fugas de información confidencial entre inquilinos.

Modelo Mental#

En el modelo mental para probar el DAL y los mecanismos de caché, las consultas atraviesan un riguroso filtro de dos niveles antes de consultar la base de datos física:

text

Invocación entrante desde RSC
                                             │
                                             ▼
+-------------------------------------------------------------------------------+
| Nivel 1: React.cache() (Per-Request Memoization)                              |
| Ciclo de vida: 1 solicitud HTTP. Deduplicación por identidad referencial de args|
+-------------------------------------------------------------------------------+
     │ (Cache Miss)                                      │ (Cache Hit: misma petición)
     ▼                                                   ▼
+---------------------------------------------------+  Retorno desde memoria
| Nivel 2: unstable_cache() (Next.js Data Cache)    |  sin consultar el nivel 2
| Ciclo de vida: Entre solicitudes, tags, TTL       |
+---------------------------------------------------+
     │ (Data Cache Miss)                                 │ (Cache Hit: por tags/claves)
     ▼                                                   ▼
+---------------------------------------------------+  Retorno desde caché
| Data Access Layer Físico                          |  sin ejecutar SQL
| - Ejecución SQL / Drizzle / Prisma                |
| - Verificación de permisos de sesión actual       |
+---------------------------------------------------+
     │
     ▼
[Base de Datos Real: PostgreSQL / MySQL]

Al escribir pruebas del DAL, se debe verificar:

Que React.cache() evite llamadas físicas reiteradas al suministrar idénticos argumentos;
Que unstable_cache() genere una clave de caché (keyParts) única que incorpore identificadores de inquilino o usuario para prevenir intoxicación de caché entre usuarios (Cache Poisoning);
Que la función revalidateTag() purgue la caché de las entidades correspondientes.

Aplicación en Producción#

Pruebas de deduplicación de consultas SQL en árboles complejos de RSC: Comprobación de que el renderizado paralelo de layouts y páginas no duplique peticiones del perfil de la organización o ajustes globales.
Validación de unicidad en claves compuestas de caché: Prevención de vulnerabilidades graves donde los datos del usuario A son devueltos al usuario B por omitir userId en keyParts.
Verificación de invalidación en cascada por tags: Confirmación de que las mutaciones de entidades invoquen confiablemente revalidateTag() con los identificadores de tag esperados.
Aislamiento de contexto en suites de testing: Garantía de que el estado de caché de una prueba unitaria no contamine las pruebas subsecuentes dentro del mismo worker de Vitest.

Cómo Funciona#

1. Arquitectura de un Módulo DAL Seguro#

Implementamos un servicio para obtener datos de organizaciones empleando React.cache() para deduplicación por solicitud y unstable_cache() para almacenamiento compartido entre peticiones.

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;
}

// Extractor de bajo nivel contra la base de datos
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;
}

// Caché entre solicitudes con tags de invalidación
export const getCachedOrganization = (orgId: string) =>
  unstable_cache(
    async () => fetchOrganizationFromDb(orgId),
    ['organization-cache-key', orgId],
    {
      revalidate: 3600, // 1 hora
      tags: [`org:${orgId}`, 'organizations'],
    }
  )();

// Método consolidado del DAL con deduplicación por petición
export const getOrganization = cache(async (orgId: string): Promise<OrganizationDTO | null> => {
  if (!orgId || typeof orgId !== 'string') {
    throw new Error('Identificador de organización inválido');
  }

  return getCachedOrganization(orgId);
});

2. Pruebas de Deduplicación por Petición con React.cache()#

Para verificar React.cache() en Vitest, invocamos la función memoizada múltiples veces concurrentemente y comprobamos el contador de llamadas del espía subyacente.

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('deduplica invocaciones concurrentes con argumentos idénticos', async () => {
    const rawFetcherMock = vi.fn().mockImplementation(async (id: string) => {
      return { id, name: `Organización ${id}`, plan: 'enterprise' as const };
    });

    // Envolvemos el mock en React.cache nativo
    const memoizedFetcher = cache(rawFetcherMock);

    // Simulamos llamadas concurrentes desde distintos componentes de servidor en un único ciclo de render
    const [result1, result2, result3] = await Promise.all([
      memoizedFetcher('org-123'),
      memoizedFetcher('org-123'),
      memoizedFetcher('org-123'),
    ]);

    // Comprobamos la igualdad de los resultados
    expect(result1).toEqual(result2);
    expect(result2).toEqual(result3);
    expect(result1.name).toBe('Organización org-123');

    // ASERCIÓN CLAVE: la consulta física se ejecutó exactamente una vez
    expect(rawFetcherMock).toHaveBeenCalledTimes(1);
    expect(rawFetcherMock).toHaveBeenCalledWith('org-123');
  });

  it('ejecuta consultas separadas ante argumentos distintos', 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. Pruebas de Configuración de unstable_cache: Claves, TTL y Tags#

Dado que unstable_cache es coordinado por el runtime interno de Next.js, en la prueba de integración del DAL interceptamos y verificamos los parámetros de registro, garantizando el aislamiento de claves y la ausencia de colisiones.

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';

// Mockeamos unstable_cache para interceptar metadatos de configuración
vi.mock('next/cache', () => ({
  unstable_cache: vi.fn((fn: () => Promise<unknown>, keyParts?: string[], options?: { revalidate?: number; tags?: string[] }) => {
    // Retornamos una función envoltorio que expone los metadatos para inspección
    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('registra la caché con clave compuesta única y tags correctos', async () => {
    const { getCachedOrganization } = await import('./organization');

    getCachedOrganization('org-prod-42');

    // Verificamos que unstable_cache fue invocado con los parámetros previstos
    expect(unstable_cache).toHaveBeenCalledWith(
      expect.any(Function),
      ['organization-cache-key', 'org-prod-42'],
      {
        revalidate: 3600,
        tags: ['org:org-prod-42', 'organizations'],
      }
    );
  });

  it('garantiza que la clave previene la mezcla de datos entre organizaciones', 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. Pruebas de Purga de Caché con revalidateTag()#

Probamos el servicio de mutación que actualiza los registros en base de datos e invalida selectivamente la caché de una organización concreta.

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('invalida el tag de la organización específica tras actualizarla con éxito', async () => {
    await updateOrganizationPlan('org-99', 'enterprise');

    // Verificamos la ejecución del update en base de datos
    expect(db.update).toHaveBeenCalled();

    // Verificamos la invalidación puntual del tag en Data Cache
    expect(revalidateTag).toHaveBeenCalledWith('org:org-99');
    // Aseguramos que no se purgue toda la colección ante una modificación individual
    expect(revalidateTag).not.toHaveBeenCalledWith('all-data');
  });
});

Errores Comunes#

Ошибка: Fuga de datos entre inquilinos (Cache Poisoning) en unstable_cache

Si una función envuelta en unstable_cache retorna datos privados de un usuario pero omite userId dentro del array keyParts, la respuesta del primer usuario quedará guardada de forma global y será entregada a los usuarios posteriores.

typescript

// ❌ VULNERABILIDAD CRÍTICA: Clave compartida para datos privados
export const getMyPrivateData = (userId: string) =>
  unstable_cache(
    async () => fetchPrivateProfile(userId),
    ['private-user-data'] // ¡Falta userId en la clave!
  )();

// ✅ SEGURO: Clave compuesta única por usuario/inquilino
export const getMyPrivateData = (userId: string) =>
  unstable_cache(
    async () => fetchPrivateProfile(userId),
    ['private-user-data', userId]
  )();

Ошибка: Confusión entre React.cache() y unstable_cache()

React.cache() está confinado exclusivamente a la deduplicación dentro del ciclo de vida de una única petición HTTP entrante (almacenado en la memoria efímera de ese render y destruido al concluir). unstable_cache() almacena cargas serializadas en disco o almacenes externos entre múltiples peticiones y usuarios. Ambos se complementan, pero no son intercambiables.

Ошибка: Omitir la directiva 'server-only' en módulos del DAL

Si un módulo DAL se importa accidentalmente dentro de un componente de cliente ('use client'), las credenciales de base de datos, variables privadas y consultas ORM se filtrarán en el bundle JavaScript público. Colocar import 'server-only'; en la primera línea genera un error inmediato de compilación si el archivo es importado en el cliente.

Ошибка: Contaminación de estado entre pruebas en Vitest

Puesto que React.cache() se vincula al contexto global del empaquetador en pruebas, invocar una función memoizada en diferentes bloques it() sin reiniciar mocks puede devolver datos de la prueba anterior. Use siempre beforeEach(() => { vi.clearAllMocks(); }) y cree instancias aisladas de las funciones.

Proceso Paso a Paso para Probar el DAL#

Fases de verificación de Data Access Layer y almacenamiento en caché

Verificación de aislamiento server-onlySecurity

Confirmar que el módulo incluye 'import server-only' y no expone detalles internos de la base de datos.

Pruebas de deduplicación con React.cache()Deduplication

Invocar la función de 3 a 5 veces con parámetros idénticos y verificar exactamente 1 consulta a la base de datos.

Inspección de claves en unstable_cacheKey Isolation

Comprobar que keyParts contenga todos los identificadores dinámicos requeridos (userId, tenantId).

Validación de tags de cachéTags Assert

Asegurar que el array tags incluya identificadores granulares de entidad (ej. 'org:id').

Verificación de purga con revalidateTagInvalidation

Ejecutar la mutación y validar la llamada a revalidateTag con el nombre de tag exacto.

Limpieza de estado entre pruebasCleanup

Reiniciar espías y cachés en beforeEach para evitar contaminación entre pruebas en los workers.

Preguntas de Entrevista#

Preguntas de entrevista7 preguntas

Temas Relacionados#

Temas relacionados

Pruebas de React Server Components (RSC)— Integración de componentes con el Data Access Layer de servidor.Pruebas de Integración de Server Actions— Mutaciones de datos y purga de caché por tags.Pruebas de Integración de Route Handlers (API)— Uso de servicios DAL dentro de endpoints de API.