Tema 3 · Router & Versionado

3. Enrutamiento Avanzado: Sub-routers Modulares, Versionado de APIs y Manejo Global de Errores

Organiza rutas REST jerárquicas con express.Router(), versiona endpoints (/api/v1) y centraliza excepciones asíncronas con clases de error personalizadas y el middleware de error de 4 parámetros.

Estructura de Rutas y Versionado en APIs REST

A medida que evolucionan las aplicaciones móviles o clientes web, romper contratos de API existentes es inaceptable. El versionado mediante prefijos de URL (/api/v1, /api/v2) y la delegación con express.Router() permite mantener versiones en paralelo de forma limpia.

1. Jerarquía de Sub-routers con express.Router()

En lugar de registrar todas las rutas en app, creamos un árbol modular de routers:

  • app.use('/api/v1', v1Router)
  • v1Router.use('/auth', authRouter)
  • v1Router.use('/productos', productosRouter)
  • v1Router.use('/pedidos', pedidosRouter)

2. El Middleware Global de Errores de 4 Parámetros

En Express, un middleware sólo se reconoce como manejador de errores si declara exactamente 4 parámetros en su firma:

app.use((err, req, res, next) => { /* ... */ });

Si omites el parámetro next, Express interpretará la función como un middleware ordinario de 3 parámetros y no capturará las excepciones lanzadas con next(err).

Seguridad: Ocultar Stack Traces en Producción

Nunca expongas err.stack ni detalles internos de la base de datos en respuestas de producción (process.env.NODE_ENV === 'production'). Estos datos proporcionan información valiosa a posibles atacantes sobre la estructura interna de tus tablas y librerías.

⚡ Router Versionado con Clase AppError y Middleware Global

Patrón completo de gestión de excepciones HTTP en Express.

routesAndErrors.js
Solo lectura
import express from 'express';

// 1. Clase de Error Personalizada para la API
export class AppError extends Error {
  constructor(message, statusCode = 500) {
    super(message);
    this.statusCode = statusCode;
    this.status = `${statusCode}`.startsWith('4') ? 'fail' : 'error';
    this.isOperational = true; // Error controlado de negocio vs bug inesperado
    Error.captureStackTrace(this, this.constructor);
  }
}

// 2. Sub-router de Usuarios (/api/v1/usuarios)
const userRouter = express.Router();

userRouter.get('/:id', async (req, res, next) => {
  try {
    const { id } = req.params;
    if (isNaN(Number(id))) {
      throw new AppError('El ID proporcionado no es un número válido.', 400);
    }

    // Simular búsqueda en BD
    const user = id === '1' ? { id: 1, nombre: 'Ana' } : null;
    if (!user) {
      throw new AppError('Usuario no encontrado en el sistema.', 404);
    }

    res.status(200).json({ success: true, data: user });
  } catch (error) {
    next(error); // Delega al middleware de 4 parámetros
  }
});

// 3. Router Principal de Versión v1
export const v1Router = express.Router();
v1Router.use('/usuarios', userRouter);

// 4. Middleware de Ruta No Encontrada (404)
export const notFoundHandler = (req, res, next) => {
  next(new AppError(`No se encontró la ruta ${req.originalUrl} en este servidor.`, 404));
};

// 5. Middleware Global Centralizado de Errores (4 parámetros)
export const globalErrorHandler = (err, req, res, next) => {
  const statusCode = err.statusCode || 500;
  const status = err.status || 'error';

  // Registrar error con fines de observabilidad
  if (statusCode >= 500) {
    console.error('[CRITICAL ERROR]', err);
  }

  res.status(statusCode).json({
    status,
    message: err.message || 'Error interno del servidor.',
    ...(process.env.NODE_ENV !== 'production' && { stack: err.stack }),
  });
};
🧠
Mini-Quiz de Retención
Comprueba tu comprensión antes de pasar a la siguiente lección
1 Pregunta
Pregunta 1
¿Por qué es obligatorio que el middleware de manejo global de errores en Express declare exactamente cuatro argumentos (err, req, res, next)?
🦉
¿Tienes dudas con este tema?
Sócrates AI puede darte analogías y explicarte este código paso a paso.

🚀 ¿Quieres dominar Express.js: Framework Backend & APIs Empresariales y crear proyectos reales?

Aprende arquitectura limpia, desarrollo web moderno, buenas prácticas y despliegue en producción con nuestro Bootcamp Fullstack Developer con mentorías en vivo.

🏛️ Autoría y Propiedad Intelectual: Obra educativa original de Juan Sebastián Amador para Kilopolis Academia, estructurada sobre las especificaciones y estándares abiertos del W3C, el estándar vivo de WHATWG y la documentación oficial de código abierto. © Todos los derechos reservados.