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:
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.
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¿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.