Validacion con Zod y contratos de API

Un contrato de API convierte entradas ambiguas en datos que el dominio puede procesar. La validación debe ejecutarse en el servidor y distinguir tipo, formato, límites y valores permitidos. Un error de validación no debe llegar como una excepción genérica.

Ejemplo resuelto

Para crear un curso, acepta title de 3 a 80 caracteres, level igual a basic o advanced y hours entero positivo. El body {title:"JS",level:"expert",hours:0} contiene tres problemas: título corto, nivel no permitido y duración inválida. La respuesta puede ser 400 con errores por campo, sin llamar al servicio.

Con Zod, expresa y usa el contrato, sin confiar en una conversión implícita:

import { z } from 'zod';
const CursoInput = z.object({
  title: z.string().trim().min(3).max(80),
  level: z.enum(['basic', 'advanced']),
  hours: z.number().int().positive(),
});
const resultado = CursoInput.safeParse({ title: 'JavaScript', level: 'basic', hours: 6 });
if (!resultado.success) {
  const errores = resultado.error.issues.map(i => ({ campo: i.path.join('.'), mensaje: i.message }));
  console.log(errores);
} else {
  console.log(resultado.data);
}

El número 6 es válido; la cadena "6" no lo es con este esquema. No reutilices coerción indiscriminada para parámetros, valores vacíos o campos opcionales.

Pruébalo

1. Define campos obligatorios y límites.

2. Valida body, params y query por separado.

3. Devuelve una forma estable para los errores.

4. Ejecuta la regla de negocio solo tras validar.

Error frecuente: confiar en la validación del frontend. Corrígelo tratando todo request como no confiable, incluso si proviene de tu propia interfaz.

Comprueba tu resultado

Prueba cuatro cuerpos: uno válido, uno sin title, uno con level:"expert" y uno con hours:-2. Solo el primero debe llegar al servicio; los otros tres deben producir 400 y señalar el campo responsable.