Capas y consistencia

Tres horas. Media hora para entender qué sabe cada capa y qué no debe saber ninguna, y dos horas y media separando tu proyecto hasta poder cambiarle el almacén sin tocar una sola ruta.

Se explica

25 minutos · conceptos y demostración

La sesión tiene una sola prueba, y hoy se pasa o no se pasa: cambiar el sitio donde viven los datos sin tocar nada por encima. Todo lo demás son las condiciones para que eso sea posible.

Las tres capas

1. Ruta · HTTP
2. Servicio · las reglas
3. Repositorio · el almacén

// repositorio/productos.js
export async function porId(id) {
  const productos = await leerProductos();
  return productos.find((p) => p.id === id) ?? null;
}

// servicio/productos.js
export async function borrar(id) {
  const producto = await repositorio.porId(id);
  if (!producto) return false;
  if (producto.stock > 0) throw new ErrorDeConflicto("No se puede borrar con stock");
  return repositorio.eliminar(id);
}

// rutas/productos.js
export async function borrarProducto(peticion, respuesta, next) {
  try {
    const borrado = await servicio.borrar(Number(peticion.params.id));
    if (!borrado) throw new ErrorNoEncontrado("Producto no encontrado");
    respuesta.status(204).end();
  } catch (error) {
    next(error);
  }
}

Con un solo recurso y un fichero, esta separación parece burocracia. Sus tres razones aparecen enseguida: se puede probar el servicio sin levantar un servidor; se puede cambiar el almacén sin tocar la API; y cuando el proyecto tiene ocho recursos, todos se organizan igual y cualquiera sabe dónde mirar. Es, además, la arquitectura que verás en el módulo de servidor con otros nombres: controlador, servicio y repositorio.

El repositorio como frontera

// La interfaz que el servicio conoce
export async function todos() {}
export async function porId(id) {}
export async function guardar(producto) {}
export async function eliminar(id) {}

Mientras el conjunto de funciones y lo que devuelven no cambie, el servicio no distingue si detrás hay un fichero, una base de datos o una API ajena.

function normalizar(crudo) {
  return {
    id: Number(crudo.id),
    nombre: String(crudo.nombre ?? "").trim(),
    precio: Number(crudo.precio ?? 0),
    stock: Number.isInteger(crudo.stock) ? crudo.stock : 0,
    categoria: crudo.categoria ?? "sin-categoria"
  };
}

Un proyecto que se prueba necesita además poder volver a un estado conocido, con un script que rellene el fichero con datos de ejemplo:

{ "scripts": { "sembrar": "node src/herramientas/sembrar.js" } }

Sin él, cada prueba deja los datos en un estado distinto y los fallos dejan de ser reproducibles.

La traducción de errores, en un solo sitio

const ESTADOS = {
  ErrorDeValidacion: 400,
  ErrorNoAutenticado: 401,
  ErrorSinPermiso: 403,
  ErrorNoEncontrado: 404,
  ErrorDeConflicto: 409
};

export function manejadorDeErrores(error, peticion, respuesta, next) {
  const estado = ESTADOS[error.name] ?? 500;

  if (estado >= 500) {
    console.error(`[${peticion.id}] ${peticion.method} ${peticion.originalUrl}`, error);
  }

  respuesta.status(estado).json({
    error: estado >= 500 ? "Error interno del servidor" : error.message,
    codigo: error.codigo ?? error.name ?? "ERROR",
    detalles: error.detalles ?? [],
    peticion: peticion.id
  });
}

Añadir un tipo de error nuevo se reduce a añadir una línea a la tabla, sin que ninguna ruta necesite conocer qué código corresponde a su fallo.

export function identificar(peticion, respuesta, next) {
  peticion.id = crypto.randomUUID();
  respuesta.setHeader("X-Request-Id", peticion.id);
  next();
}

Al otro lado se cobra el contrato de la sesión 1: una sola función en el cliente sirve para toda la API, hoy y cuando añadas rutas.

async function pedir(url, opciones) {
  const respuesta = await fetch(url, opciones);
  if (respuesta.ok) return respuesta.status === 204 ? null : respuesta.json();

  const cuerpo = await respuesta.json().catch(() => ({}));
  throw new ErrorDeApi(respuesta.status, cuerpo.error ?? "Error inesperado", cuerpo.detalles ?? []);
}

Si cada error tuviera una forma distinta, esta función no podría existir.

Se trabaja

150 minutos · separar, sustituir y diagnosticar

Los tres primeros pasos construyen la separación. Los dos últimos la ponen a prueba: uno cambia el almacén de verdad, el otro recorre los cinco errores desde el navegador hasta el registro.

Paso 1 · La separación · 40 min

1. Crea src/servicio/ y src/repositorio/ y reparte el código que hoy está mezclado.
2. Deja las rutas sin ninguna referencia a ficheros.
3. Deja el servicio sin ninguna referencia a peticiones ni respuestas.
4. Mueve al servicio las reglas de negocio que estaban en las rutas, como «no se puede borrar un producto con stock».
5. Busca las dos palabras de la prueba —respuesta en el servicio, peticion en el repositorio— y corrige lo que aparezca.
6. Escribe un programa que use el servicio directamente, sin HTTP, y cree y borre un producto.

Antes de continuar: ese programa del apartado 6 funciona sin que Express esté arrancado. Si necesita el servidor, el servicio todavía depende de la capa de arriba.

Paso 2 · Cambiar el almacén · 40 min

1. Escribe en un comentario la lista exacta de funciones que el servicio espera del repositorio, con lo que recibe y lo que devuelve cada una.
2. Normaliza los datos al leerlos del fichero, con una función normalizar.
3. Escribe un segundo repositorio que guarde en memoria, con esa misma lista de funciones.
4. Elige entre uno y otro con una variable de entorno, en un solo punto del programa.
5. Escribe el script de siembra y añádelo a los scripts de package.json.
6. Prueba tu fichero .http completo contra los dos repositorios.

Paso 3 · Errores de punta a punta · 40 min

1. Define los cinco tipos de error de tu aplicación, cada uno con su nombre y su código.
2. Escribe la tabla de traducción y el manejador central.
3. Añade el identificador de petición y sácalo en el registro y en la respuesta.
4. Elimina todos los códigos de estado repartidos por las rutas. Al terminar, status( no debería aparecer en ninguna ruta salvo para las respuestas correctas.
5. Escribe la función pedir en el cliente y úsala en toda la interfaz, sustituyendo cada fetch suelto.
6. Muestra en el formulario los detalles de validación campo por campo, aprovechando el array detalles.

Paso 4 · La prueba del cambio de almacén · 15 min

Hasta aquí has escrito la separación. Ahora se comprueba si es real.

1. Anota el estado de tu repositorio con git status antes de empezar.
2. Cambia al repositorio en memoria y ejecuta el fichero .http completo.
3. Rellena la tabla con lo que ha hecho falta tocar.

4. Cualquier fila fuera del repositorio y del punto único de configuración señala una fuga: algo de arriba sabe cómo se guardan los datos. Localízala y escribe en una línea qué la causaba.
5. Si las dos ejecuciones no dan el mismo resultado, anota en qué petición difieren. Hay una diferencia legítima entre un almacén que persiste y otro que no, y conviene saber nombrarla.

Paso 5 · Los cinco errores, desde el navegador · 15 min

Provoca cada error desde la interfaz, no desde el fichero .http, y recorre el camino entero.

Las dos últimas son las que importan: comprueba que la persona ve un mensaje genérico con su identificador, que la traza completa queda solo en el registro, y que el identificador de la pantalla coincide con el del registro.

Escribe al terminar, en una línea, qué habrías tenido que hacer para diagnosticar el quinto caso sin ese identificador.

Ampliación si has completado el trabajo

Primero termina y comprueba los cinco pasos. El primer reto lleva la frontera del repositorio hasta donde se rompe; el segundo convierte tus registros en una herramienta de diagnóstico.

Reto 1 · El tercer almacén

Dos repositorios que leen de un array y de un fichero se parecen demasiado para probar nada. Escribe un tercero contra algo que se comporte de otra manera: una API pública de solo lectura, o una base de datos ligera como SQLite.

1. Impleméntalo con la misma lista de funciones, sin cambiar su forma.
2. Anota cada punto en el que la interfaz se queda corta. Aparecerán varios: un almacén remoto puede tardar, puede paginar, puede fallar por red, y puede no permitir borrar.
3. Decide qué hacer con lo que el almacén nuevo no sabe hacer. Fallar de forma explícita es una respuesta válida; fingir que ha funcionado, no.
4. Traduce los fallos propios de ese almacén a los tipos de error de tu aplicación. El servicio no debería recibir nunca un error de red en crudo.
5. Rediseña la interfaz si hace falta, y vuelve a probar los tres repositorios con ella. Cambiar la interfaz por culpa del tercero indica que estaba escrita a la medida del fichero.
6. Explica en tres líneas qué has aprendido sobre tu primera interfaz. Una abstracción solo se valida con la segunda implementación, y se confirma con la tercera.

Reto 2 · Seguir el rastro de un fallo

Tus registros hoy sirven para mirarlos por encima. Conviértelos en algo sobre lo que se pueda buscar.

1. Pasa el registro a formato estructurado: una línea por petición, en JSON, con identificador, método, ruta, código de estado y duración en milisegundos.
2. Haz que el identificador llegue hasta el repositorio, de modo que una operación de escritura pueda registrarse asociada a la petición que la causó. Piensa cómo pasarlo sin que el servicio hable de HTTP.
3. Escribe el registro en un fichero además de en la consola, y decide qué ocurre cuando ese fichero crece.
4. Provoca veinte peticiones, tres de ellas con error, y escribe el comando que extrae de tu fichero de registro solo las que fallaron.
5. Ahora el ejercicio de verdad: pide a un compañero que introduzca un fallo en tu código sin decirte cuál. Reprodúcelo desde la interfaz, apunta el identificador y diagnostica la causa mirando solo el registro, sin leer el código.
6. Escribe qué dato te faltó en el registro para llegar antes. Añádelo, y repite el apartado 5 con un fallo distinto.
7. Decide qué no debe aparecer nunca en un registro. Hay al menos tres categorías de dato que no pueden acabar ahí; nómbralas y comprueba que las tuyas están limpias.

Cierre

5 minutos · comprobación y recuerdo

Ver respuestas

1 · El 404 a la ruta, la regla del stock al servicio, la lectura del fichero al repositorio.

2 · Buscando respuesta en el servicio y peticion en el repositorio, y comprobando que cambiar el almacén no obliga a tocar nada más.

3 · Porque el fichero también es entrada externa y puede llegar incompleto o con otra forma.

4 · Que los dos ofrezcan la misma lista de funciones con el mismo comportamiento.

5 · Porque revela detalles internos del servidor sin aportar nada a quien la lee.

6 · Para relacionar lo que ve la persona con la traza completa del registro.

---