Express.js
Integra HTTP, middleware, routing, validación, autenticación, casos de uso, datos, errores, observabilidad y deployment en un modelo mental completo.
Express se entiende mejor como un boundary HTTP: recibe una solicitud no confiable, la conduce por un pipeline explícito y traduce una operación de la aplicación en una respuesta observable. Todo lo demás —reglas, datos, seguridad y operación— debe conectarse con ese boundary sin quedar oculto dentro de él.
Esta página no introduce una API nueva. Reúne el modelo mental completo del notebook para que puedas:
El objetivo final no es memorizar helpers de Express. Es comprender el sistema que se construye alrededor de ellos.
cliente
↓ request HTTP
reverse proxy / load balancer
↓ conexión y headers confiables según topología
servidor Node.js
↓ IncomingMessage + ServerResponse
aplicación Express
↓ stack ordenado
request context → parsing → authentication → authorization → validation
↓
route handler
↓ traducción HTTP → input de aplicación
caso de uso
↓
reglas + transaction boundary + repositories + gateways
↓
PostgreSQL / cache / servicio externo / queue / object storage
↓
resultado o error de aplicación
↓ traducción a status + headers + body
response HTTP
↓
logs + métricas + trazas + cleanupCada flecha representa una frontera de responsabilidad. Los problemas aparecen cuando una capa asume trabajo que pertenece a otra o cuando el flujo deja de ser visible.
Node.js y la infraestructura administran conexiones, sockets, timeouts, TLS y proxies. Express recibe objetos HTTP ya creados.
Preguntas importantes:
X-Forwarded-For?Configurar trust proxy sin conocer la topología puede convertir headers falsificables en IP, protocolo o host supuestamente confiables.
Express organiza método, path, headers, params, query, body, cookies, middleware y errores.
Aquí deben vivir decisiones de transporte:
No deben vivir aquí reglas como “una orden confirmada no puede editarse” o “el stock no puede quedar negativo”.
El caso de uso representa una intención completa:
CreateOrder
CancelOrder
ConfirmPayment
AssignDeliveryRecibe datos ya interpretados y una identidad interna; coordina reglas, autorización dependiente del recurso, persistencia y eventos. Debe poder ejecutarse desde HTTP, un job o una prueba sin simular Express.
Repositories y gateways traducen operaciones de aplicación a PostgreSQL, Redis, correo, pagos o colas.
Aquí aparecen:
La infraestructura implementa contratos; no debería decidir la semántica HTTP final.
Una API no termina cuando responde correctamente en local. Producción exige health checks, shutdown, logs, métricas, trazas, alertas, despliegues reproducibles y rollback.
Una ruta técnicamente correcta puede ser operacionalmente peligrosa si no tiene límites, timeout, observabilidad o estrategia de recuperación.
Considera:
POST /api/v1/orders
Authorization: Bearer token
Idempotency-Key: order-abc-123
Content-Type: application/jsonEl proxy aplica TLS, límites y routing. Añade metadata confiable únicamente si Express está configurado para esa topología.
Un middleware crea requestId, registra inicio y prepara contexto. Ese identificador acompañará logs y errores.
express.json convierte bytes en un valor JavaScript dentro de un límite. Todavía no sabe si el contenido cumple el contrato.
El middleware verifica sesión, token o API key y produce un actor interno. No toma userId del body como identidad.
Se resuelve el tenant desde una fuente autenticada y se comprueba permiso general para crear órdenes.
Params, query y body se convierten a una estructura conocida. Se rechazan formatos inválidos y campos no permitidos.
El handler reúne actor, tenant e input y llama al caso de uso. No contiene SQL ni reglas extensas.
El caso de uso verifica reglas dependientes del estado actual, abre la transacción adecuada y coordina repositories.
PostgreSQL aplica constraints y concurrencia. Un unique constraint protege la idempotency key; la transacción asegura atomicidad.
Un outbox guarda el evento dentro de la misma transacción. Un worker enviará email o webhook después del commit.
El resultado se convierte en 201 Created, Location y una representación pública. Un conflicto de stock puede convertirse en 409.
La response finaliza; se registra status, duración y request ID. Se liberan recursos aunque haya error o desconexión.
request
↓
requestId
↓
logging inicial
↓
parser con límites
↓
authentication
↓
tenant resolution
↓
router
↓
route-specific authorization
↓
validation
↓
handler
↓
404 terminal
cualquier error
↓
error middlewareEl orden es comportamiento. Si auth necesita cookies, el parser correspondiente debe existir antes. Si el error handler se registra antes de rutas, no verá errores posteriores.
Cada middleware o handler debe elegir con claridad:
next().next(error) o una Promise rechazada retornada.No responder ni delegar cuelga la request. Responder y después delegar puede producir una segunda response.
Todo lo que entra desde red es no confiable:
TypeScript no valida runtime. El camino correcto es:
unknown
↓ parser
valor JavaScript
↓ schema de runtime
input estructural válido
↓ reglas de aplicación
operación permitidaValidación estructural, reglas del negocio y autorización son controles diferentes. Un UUID válido puede identificar un recurso inexistente o de otro tenant.
authentication
→ quién actúa
authorization
→ qué puede hacer sobre qué recurso y en qué contextoLa autorización completa suele necesitar:
actor + action + resource + tenant + estado actualUn rol manager puede tener permiso general, pero la orden aún debe pertenecer a su branch. Ocultar botones en frontend no protege el backend.
No todo error representa un 500.
input inválido → 400 o 422 según contrato
sin credenciales → 401
sin permiso → 403 o 404 por política
recurso inexistente → 404
conflicto de estado → 409
media type inválido → 415
dependencia temporal → 502/503/504 según contexto
fallo inesperado → 500El error público necesita códigos estables; el log interno necesita contexto técnico. No expongas stack, SQL, secretos ni metadata sensible.
En Express 5, una Promise retornada que se rechaza entra al error pipeline. Trabajo desprendido, callbacks y timers siguen requiriendo manejo explícito.
La transaction boundary debe corresponder a una unidad de consistencia, no a toda request por defecto.
Ejemplo correcto:
crear order
+ crear items
+ reservar stock
+ registrar outbox
= una transacciónEjemplo peligroso:
abrir transacción
→ llamar API de pagos durante 20 segundos
→ enviar email
→ commitMantiene locks y conexión mientras depende de la red. Conviene usar estados intermedios, outbox, jobs y operaciones idempotentes.
Una request puede llegar dos veces por retry del cliente, proxy o proveedor.
Para operaciones sensibles:
idempotency key
+ actor/tenant
+ endpoint
+ fingerprint del input
+ unique constraint
+ respuesta almacenadaRepetir la misma intención devuelve el resultado previo; reutilizar la key con contenido distinto produce conflicto.
Un retry sin idempotencia puede duplicar pagos, órdenes o notificaciones.
Toda dependencia remota necesita un límite. La jerarquía debe permitir traducir el fallo antes de que el proxy corte la conexión:
timeout de PostgreSQL / API externa
< timeout de caso de uso
< timeout HTTP de aplicación
< timeout del proxyUn timeout deja de esperar, pero no siempre cancela el trabajo. Propaga AbortSignal cuando la dependencia lo soporte.
También limita:
Para escalar varias instancias, evita depender de memoria local para estado compartido:
Escalar procesos no arregla queries lentas, event-loop blocking ni un pool total excesivo.
Request y response conservan capacidades de stream de Node.js. Para datos grandes:
source readable
↓ pipeline
transform opcional
↓ backpressure
response writableNo cargues un archivo completo en memoria cuando puede fluir por chunks. Después de enviar headers, un error de stream no puede transformarse en un JSON nuevo.
No existe un middleware mágico. Una postura real combina:
Cada control reduce un vector concreto y tiene límites.
Sigue una request mediante requestId o trace ID:
entrada
→ middleware ejecutado
→ ruta matched
→ validation/auth
→ caso de uso
→ query o servicio externo
→ error mapping
→ responseTres señales se complementan:
Explican eventos concretos con contexto. Deben ser estructurados y redactar secretos.
Permiten observar tasas, latencias, errores, saturación y tendencias.
Muestran el recorrido distribuido y dónde se consume tiempo.
No registres únicamente “error”. Incluye operación, duración, dependencia, categoría y correlación sin exponer datos sensibles.
Revisa:
next().Busca:
return.Sigue:
Mide por etapa:
Audita:
Busca:
Antes de implementar una operación, responde:
Una estructura útil refleja features y boundaries reales:
src/
app.ts
server.ts
config.ts
modules/
orders/
orders.router.ts
create-order.handler.ts
create-order.schema.ts
create-order.use-case.ts
order.repository.ts
postgres-order.repository.tsNo todos los módulos necesitan todas las capas. Un health check simple no necesita repository. Una operación crítica sí puede necesitar interfaces, transacción, outbox y policy.
La arquitectura debe reducir acoplamiento y riesgo, no aumentar archivos para parecer avanzada.
Prueba reglas y casos de uso con dependencias controladas. Debe ser rápido y preciso.
Prueba app, routing, middleware, validation, auth, error contract y PostgreSQL real de prueba.
Prueba flujos críticos desde la perspectiva del consumidor con infraestructura representativa.
No todo debe probarse en E2E. Utiliza la capa más baja que demuestre el comportamiento sin esconder integración importante.
Una API lista para producción necesita:
“Funciona en local” solo demuestra el camino feliz en una instancia.
A julio de 2026, Express 5 es la referencia moderna y requiere Node.js 18 o superior. Mantener una aplicación implica revisar:
No mezcles ejemplos de Express 4 y 5 sin etiquetarlos.
Estudia notas 1–12: relación con Node, aplicación, request/response, lifecycle, middleware, routing y semántica HTTP.
Continúa con notas 13–30: modularización, casos de uso, validation, errores, async, identidad y seguridad de sesión.
Revisa notas 31–40: XSS, headers, límites, archivos, streams, webhooks e idempotencia.
Estudia notas 41–50: paginación, diseño de APIs, OpenAPI, PostgreSQL, transacciones, servicios, jobs y tiempo real.
Utiliza notas 51–60: health, shutdown, observabilidad, performance, caching, proxies y testing.
Cierra con notas 61–71: estructura, DI, configuración, startup, TypeScript, supply chain, deployment, escalado, migración y antipatrones.
Después de completar la ruta deberías poder:
success:false no representa correctamente un error HTTP.request.body no reemplaza una constraint en PostgreSQL.Express es pequeño, pero las aplicaciones que lo usan no lo son necesariamente. Dominarlo significa comprender el recorrido completo de una solicitud y mantener cada responsabilidad en el lugar correcto.
Cuando puedas seguir una request desde el proxy hasta la transacción, explicar cada decisión y diagnosticar sus fallos, ya no estarás utilizando Express como una colección de métodos: estarás diseñando un backend consciente.