Patrón Middleware

Construye pipelines de solicitudes a partir de funciones pequeñas y componibles, donde cada una maneja una preocupación antes de pasar el control al siguiente manejador.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

import express, { type Request, type Response, type NextFunction } from "express";
 
const app = express();
 
// El middleware se ejecuta en el orden de registro
app.use((req, _res, next) => {
  req.headers["x-request-start"] = String(Date.now());
  next();
});
 
app.get("/users", (req, res) => {
  res.json({ startedAt: req.headers["x-request-start"] });
});
 
// Middleware de error de cuatro argumentos (Express 5)
app.use((err: Error, _req: Request, res: Response, _next: NextFunction) => {
  res.status(500).json({ error: err.message });
});

Cuándo usarlo: Cualquier aplicación HTTP que necesite que las preocupaciones transversales (registro, autenticación, análisis, CORS) se apliquen de manera consistente en todas las rutas.

Ejemplo de trabajo

Un ejecutor de middleware mínimo sin Express, luego la misma cadena en Express 5.

import express from "express";
 
// --- Tipos de middleware de Node puro ---
type Req = { headers: Record<string, string | undefined>; body?: unknown };
type Res = { statusCode: number; body?: unknown; status(n: number): Res; json(d: unknown): void };
type Next = (err?: Error) => void;
type Middleware = (req: Req, res: Res, next: Next) => void;
 
function runMiddleware(
  middlewares: Middleware[],
  req: Req,
  res: Res,
  finalHandler: () => void
) {
  let index = 0;
  const next: Next = (err) => {
    if (err) throw err;
    const fn = middlewares[index++];
    if (fn) fn(req, res, next);
    else finalHandler();
  };
  next();
}
 
// --- Equivalente a Express 5 ---
const app = express();
app.use(express.json({ limit: "1mb" }));
 
function requestId(req: express.Request, _res: express.Response, next: express.NextFunction) {
  req.headers["x-request-id"] = crypto.randomUUID();
  next();
}
 
function requireAuth(req: express.Request, res: express.Response, next: express.NextFunction) {
  const token = req.headers.authorization;
  if (!token?.startsWith("Bearer ")) {
    res.status(401).json({ error: "Unauthorized" });
    return;
  }
  next();
}
 
app.use(requestId);
app.get("/public", (_req, res) => res.json({ ok: true }));
app.get("/private", requireAuth, (_req, res) => res.json({ secret: true }));

Lo que esto demuestra:

• El middleware es una función con la firma (req, res, next)
• Llama a next() para continuar; omítelo para finalizar la respuesta
• El orden importa: los analizadores antes de las rutas, los manejadores de errores al final
• El middleware a nivel de ruta (requireAuth) limita la autenticación a rutas específicas

En detalle

Cómo funciona

• Cada middleware puede mutar req/res, finalizar la respuesta o llamar a next()
• La cadena es una invocación enlazada: m1 -> m2 -> m3 -> manejador de ruta
• El middleware de error tiene 4 parámetros (err, req, res, next) y solo se ejecuta cuando se llama a next(err)
• Fastify usa hooks (onRequest, preHandler) en lugar de una sola cadena; NestJS usa guards, interceptors y pipes

Categorías de Middleware

Notas de TypeScript

// Extiende Express Request para un contexto de middleware tipado
declare global {
  namespace Express {
    interface Request {
      userId?: string;
    }
  }
}
 
function attachUser(req: express.Request, _res: express.Response, next: express.NextFunction) {
  req.userId = "user-42";
  next();
}

Errores comunes

• Llamar a next() después de res.send() - envía respuestas duplicadas y falla con ERR_HTTP_HEADERS_SENT. Solución: regresa inmediatamente después de finalizar la respuesta.
• next() olvidado - la solicitud se cuelga hasta que se agota el tiempo de espera. Solución: cada ruta de código debe llamar a next() o finalizar la respuesta.
• Middleware de error registrado antes de las rutas - nunca se ejecuta. Solución: registra los manejadores de 4 argumentos después de todas las rutas.
• Middleware asíncrono sin reenvío de errores - las promesas rechazadas se pierden en patrones más antiguos. Solución: Express 5 reenvía errores asíncronos; de lo contrario, usa try/catch y next(err).
• Autenticación global en archivos estáticos - bloquea favicon.ico y las comprobaciones de estado. Solución: monta la autenticación en enrutadores específicos, no app.use(auth) globalmente.
• Orden de los analizadores de cuerpo - express.json() después de las rutas significa que los cuerpos POST nunca se analizan. Solución: los analizadores primero. Consulta Orden de Middleware.

Alternativas

Preguntas frecuentes

Relacionado

• Orden de Middleware - secuencia de registro correcta
• Manejo de errores en Express - patrones de middleware de error
• Middleware de seguridad - helmet, cors, límites de velocidad
• Guards, Interceptors y Pipes - equivalente de NestJS
• Mejores prácticas de fundamentos HTTP - lista de verificación de la sección

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.