Express.js
Explica cómo organizar rutas con express.Router, factories, middleware por módulo, nested routers y una estructura por feature fácil de probar y mantener.
Un Router organiza un subconjunto del pipeline HTTP. Modularizar por feature mantiene juntos contratos, validación y handlers relacionados sin convertir la estructura en carpetas globales desconectadas.
express.Router() crea un handler modular con su propio stack de middleware y rutas:
import { Router } from 'express';
export const ordersRouter = Router();
ordersRouter.get('/', listOrdersHandler);
ordersRouter.post('/', validateCreateOrder, createOrderHandler);Después se monta con un prefijo:
app.use('/api/orders', ordersRouter);El router no necesita conocer el prefijo global. Esto permite reutilizarlo, versionarlo o probarlo de forma aislada.
Una aplicación pequeña puede registrar todas las rutas en app.ts. Al crecer aparecen:
El router crea una frontera HTTP. No es por sí mismo una frontera de dominio: todavía debes decidir qué dependencias y reglas pertenecen al módulo.
app
├─ middleware global
├─ /orders → ordersRouter
│ ├─ middleware del módulo
│ ├─ GET /
│ ├─ POST /
│ └─ GET /:id
└─ /customers → customersRouterCada router recibe la URL restante después del prefijo y comparte los mismos objetos request/response.
src/
modules/
orders/
orders.router.ts
create-order.handler.ts
create-order.schema.ts
create-order.use-case.ts
order.repository.tsEsta organización mantiene cerca piezas que cambian juntas. Una estructura global:
controllers/
services/
repositories/
validators/puede obligar a navegar varias carpetas para entender una sola operación.
Evita imports globales de dependencias:
type OrdersRouterDependencies = {
createOrder: CreateOrder;
listOrders: ListOrders;
};
export function createOrdersRouter(
dependencies: OrdersRouterDependencies,
): Router {
const router = Router();
router.post(
'/',
validate(createOrderSchema),
makeCreateOrderHandler(dependencies.createOrder),
);
router.get('/', makeListOrdersHandler(dependencies.listOrders));
return router;
}La factory hace visibles dependencias y facilita tests.
router.use(requireAuthentication);Esto protege todas las rutas registradas después. No lo uses cuando algunas rutas son públicas, o separa subrouters:
router.get('/public-catalog', listPublicCatalog);
router.use(requireAuthentication);
router.get('/private-orders', listPrivateOrders);const branchOrdersRouter = Router({ mergeParams: true });
app.use(
'/businesses/:businessId/branches/:branchId/orders',
branchOrdersRouter,
);mergeParams: true permite acceder a params del padre. Esa dependencia debe probarse; de lo contrario, branchId puede ser undefined.
Un módulo debería exportar pocas entradas:
export { createOrdersRouter } from './orders.router.js';Evita que otros módulos importen archivos internos arbitrariamente. Si necesitan una capacidad, crea un contrato explícito.
router
→ matching, orden y middleware
handler/controller
→ traducción HTTP
use case
→ operación del negocioUn router gigante que consulta base de datos directamente mezcla las tres responsabilidades.
Puedes montar distintas versiones:
app.use('/api/v1/orders', createOrdersV1Router(deps));
app.use('/api/v2/orders', createOrdersV2Router(deps));No dupliques todo el negocio. Las versiones pueden compartir casos de uso y variar mappers, schemas o contrato HTTP.
export function createOrdersRouter(deps: Dependencies): Router {
const router = Router();
router.use(deps.authenticate);
router.get(
'/',
validateQuery(listOrdersSchema),
makeListOrdersHandler(deps.listOrders),
);
router.post(
'/',
deps.authorize('orders:create'),
validateBody(createOrderSchema),
makeCreateOrderHandler(deps.createOrder),
);
router.get(
'/:orderId',
validateParams(orderIdSchema),
makeGetOrderHandler(deps.getOrder),
);
return router;
}El módulo expresa auth común y precondiciones específicas. Los handlers reciben casos de uso, no acceden a singletons ocultos.
Puede ser deliberado, pero links absolutos y auth pueden asumir un prefijo. Usa baseUrl y configuración explícita.
Solo afecta rutas posteriores.
Indican boundaries débiles. Extrae un contrato compartido o coordina desde una capa superior.
Crear un router para una sola ruta puede ser correcto si representa un módulo real, pero no es obligatorio.
Si mezcla catálogo, pagos, usuarios y reportes, probablemente la frontera sea demasiado amplia.
mergeParams sin verificar relaciones padre-hijo.Prueba el router montado en una app mínima:
Más módulos reducen archivos grandes, pero aumentan navegación y composición. La unidad adecuada es una responsabilidad que cambia junta y tiene un vocabulario propio, no una cifra fija de rutas.
mergeParams crea una dependencia explícita del padre.mergeParams?Controllers y handlers HTTP explica cómo traducir entre el contrato de transporte y la aplicación.