En la lección anterior dejamos un proyecto con carpetas vacías, dependencias instaladas y configuración validada, pero incapaz de responder a nada. Hoy eso cambia: al terminar tendrás un servidor Express escuchando en http://localhost:3000 que sirve GET /v1/cafes y GET /v1/cafes/caf_001 con el formato exacto que fijamos en el módulo 2, un endpoint de salud, y un 404 que ya habla el idioma del contrato. Por el camino entenderemos la única idea que hay que entender de verdad para trabajar con Express —el middleware—, veremos por qué separar app.js de servidor.js es una decisión de arquitectura y no un capricho, y montaremos el Router bajo /v1, que es donde el versionado en la ruta decidido en 02-07 deja de ser un diagrama y se convierte en código.

1. Qué es Express y qué no es
2. El concepto central: middleware
3. El ciclo de vida de una petición
4. src/app.js y src/servidor.js: por qué van separados
5. Primer arranque y endpoint de salud
6. Middleware integrado: express.json y express.urlencoded
7. El Router de Express y el montaje de /v1
8. Datos en memoria: src/repositorios/cafes-memoria.js
9. Las primeras rutas de cafés
10. Rutas con parámetros y req.params
11. Enviar respuestas: res.status, res.json, res.set, res.sendStatus
12. El 404 genérico con el formato de error del contrato
13. Probarlo todo con curl
14. Registro de peticiones: morgan y hasta dónde llegamos hoy

Node incluye un módulo http con el que ya se puede montar un servidor:

Funciona, y enseña algo importante: Express no hace nada que no pudieras hacer tú. Pero ese if/else crece hasta lo inmanejable en cuanto hay veinte rutas, parámetros de ruta, cuerpos JSON que parsear y comportamientos comunes a todas las peticiones.

Express es una capa fina sobre node:http que aporta exactamente cuatro cosas:

Y es igual de importante saber qué no es: Express no es un framework "con baterías incluidas". No trae ORM, ni validación, ni autenticación, ni estructura de carpetas obligatoria. Todo eso lo pones tú —y por eso el módulo tiene ocho lecciones—. A cambio, no hay magia: cada cosa que ocurre en una petición está escrita en algún fichero tuyo. Para aprender cómo funciona de verdad una API es la mejor elección posible. En 05-03 compararemos Express con Fastify, NestJS y otros.

Un middleware es una función que recibe la petición, puede hacer algo con ella y decide si la pasa a la siguiente función de la cadena. Toda su definición cabe en una firma:

Y tres reglas que explican el 90 % de los problemas de un principiante con Express:

1. Los middleware se ejecutan en el orden en que se registran. No hay prioridades ni magia: es una lista, de arriba abajo.
2. Si un middleware no llama a next() ni responde, la petición se queda colgada hasta que el cliente se cansa. Es el error más frecuente.
3. Si un middleware responde (res.json(...)), la cadena termina ahí. Llamar a next() después provoca el famoso ERR_HTTP_HEADERS_SENT.

Un ejemplo con tres middleware encadenados para ver el orden en vivo:

Un manejador de ruta (app.get, app.post) es también un middleware; simplemente está condicionado a un método y una ruta. Esa uniformidad es la clave del diseño de Express: todo es la misma cosa. La validación de 03-04, la autenticación de 03-06 y el manejo de errores de 03-07 serán middleware con esta misma firma.

Este es el recorrido completo que tendrá una petición en Tienda Aroma al final del módulo. Hoy montamos las cajas grises; las demás llegan en las lecciones indicadas.

Lo que hay que retener: una petición atraviesa la cadena de arriba abajo y sale por uno de dos sitios, una respuesta normal o el middleware de errores. Nada más.

Casi todos los tutoriales de Express meten en un único fichero la creación de la app y la llamada a listen(). Nosotros no, y el motivo es concreto:

La ventaja aparece en 03-08. Supertest, la herramienta con la que probaremos la API, acepta el objeto app de Express y le lanza peticiones sin abrir ningún puerto TCP. Si app.js llamara a listen(), cada fichero de pruebas ocuparía el puerto 3000 y dos suites en paralelo chocarían con EADDRINUSE. Separando, la app es un objeto reutilizable y el puerto es un detalle de despliegue.

Empezamos por src/app.js:

Y src/servidor.js:

Sobre el cierre ordenado: sin él, Ctrl+C corta de golpe y una petición a medio responder muere sin respuesta. Con servidor.close(), el socket deja de aceptar clientes nuevos pero las peticiones vivas terminan. En 03-05 añadiremos aquí el cierre de la base de datos y en 03-07 la captura de errores no controlados del proceso.

Fíjate en la dirección de los import: servidor.js importa app.js, nunca al revés.

En otra terminal:

Merece la pena detenerse en tres detalles de esa respuesta:

• Content-Type: application/json; charset=utf-8 lo ha puesto res.json() automáticamente. Es lo que declaramos en el contrato.
• ETag también viene de serie. Es la base del caché condicional, que trataremos en 04-06.
• No hay X-Powered-By, gracias a app.disable.

¿Por qué /salud está fuera de /v1? Porque no es parte de la API pública: no lo consumen la SPA ni Aroma Móvil, sino el balanceador de carga y la monitorización. No forma parte del contrato versionado, así que no debe versionarse. Es la excepción que confirma la regla de 02-07.

Cuando llega un POST con cuerpo JSON, el cuerpo viaja como un flujo de bytes. Sin ayuda, req.body es undefined. express.json() es un middleware que lee ese flujo, lo parsea y deja el objeto en req.body.

Añádelo a src/app.js, antes de las rutas:

Dos consecuencias que hay que conocer desde ya. La primera: si el cliente envía JSON mal formado, express.json() lanza un SyntaxError que hoy produce una página HTML de error fea; en 03-07 lo convertiremos en un 400 datos_invalidos del contrato. La segunda: si el cliente no envía Content-Type: application/json, el middleware no parsea nada y req.body queda como {}; es la causa número uno del "mi POST llega vacío".

Poner todas las rutas en app.js funciona con dos y es insostenible con veinticuatro. Un Router es una mini-aplicación de Express: tiene sus propias rutas y sus propios middleware, y se monta bajo un prefijo.

Vamos a crear dos ficheros. Primero, el router de cafés (src/rutas/cafes.js), que de momento solo declara sus rutas relativas:

Y ahora el agregador (src/rutas/index.js), que reúne todos los routers de la versión 1:

Y se monta en src/app.js:

El resultado es una composición de prefijos en tres niveles:

Y aquí está la ganancia real de 02-07 hecha código: el día que exista una v2, se crea src/rutas/v2/ y se añade app.use('/v2', rutasV2). Las dos versiones conviven en el mismo proceso, compartiendo servicios donde el comportamiento no cambie y divergiendo donde sí. Sin este montaje, "convivencia de versiones" sería una frase bonita imposible de implementar.

Todavía no tenemos base de datos —eso es 03-05—, así que los cafés vivirán en un array. Pero lo colocamos ya en la carpeta de repositorios y detrás de una interfaz, porque el objetivo declarado es sustituirlo por SQLite sin que el resto del código se entere.

Dos decisiones que parecen menores y no lo son:

• Los nombres de los métodos (buscarTodos, buscarPorId) son la interfaz del repositorio. En 03-05 escribiremos cafes-sqlite.js con exactamente los mismos nombres, y cambiar de uno a otro será cambiar un import.
• Se devuelven copias ({ ...cafe }), no las referencias del array. Si devolviéramos la referencia, cualquier capa superior podría modificar el "almacén" por accidente. Con una base de datos real esto es imposible por construcción; en memoria hay que imponerlo a mano.

Ahora conectamos el repositorio con el router. Sustituye el contenido de src/rutas/cafes.js:

Detalles importantes de este fichero:

• El envoltorio solo está en la colección. GET /v1/cafes devuelve {datos, total}; GET /v1/cafes/:id devuelve el objeto desnudo. Es exactamente lo que decidimos en 02-05.
• return res.status(404)...: el return no devuelve nada útil a Express, pero corta la ejecución de la función. Sin él, seguiría hasta el res.status(200) y provocaría ERR_HTTP_HEADERS_SENT.
• total es hoy la longitud del array. Cuando en 03-03 haya filtros y paginación, total será el número de elementos que cumplen el filtro, no los devueltos en la página. Esa distinción se cobra bugs.
• ?? null (fusión de nulos) devuelve el valor de la izquierda salvo que sea null o undefined. No confundir con ||, que también sustituiría el 0 o la cadena vacía.

'/:id' declara un segmento variable. Express captura lo que haya en esa posición y lo deja en req.params.id, siempre como cadena de texto.

Que nuestros identificadores sean cadenas con prefijo (caf_001) juega a favor: no hay que convertir nada ni preocuparse de un parseInt que devuelva NaN. Fue una decisión de 02-02 y aquí se cobra el primer dividendo.

Un aviso sobre el orden, que es la trampa clásica:

Express recorre las rutas en orden de declaración y se queda con la primera que coincide. Lo concreto va antes que lo variable.

Un router hermano muy útil es router.param(), que ejecuta código cada vez que aparece un parámetro concreto —por ejemplo, cargar el café y dejarlo en req.cafe—. Lo mencionamos para que lo conozcas; en este curso preferimos hacerlo explícito en el servicio.

Tres avisos prácticos:

En este módulo usaremos casi siempre el mismo patrón: res.set(...) para las cabeceras del contrato y res.status(...).json(...) para el cuerpo.

Si pides GET /v1/inexistente, ninguna ruta coincide y Express responde con su 404 por defecto: una página HTML con el texto Cannot GET /v1/inexistente. Para un consumidor que espera JSON, eso rompe el contrato en tres frentes: Content-Type equivocado, forma del cuerpo desconocida y filtración del framework.

Añadimos un middleware final en src/app.js, después de todas las rutas:

Dos precisiones sobre el catálogo. El código ruta_no_encontrada no estaba en el catálogo de 02-04, que solo tenía los 404 específicos (cafe_no_encontrado, pedido_no_encontrado…). Lo añadimos ahora para el caso genérico —una URI que no existe en absoluto—, y eso es perfectamente legítimo: la regla que fijamos es que el catálogo solo crece; añadir un código es un cambio aditivo, retirarlo sería rompedor. Y hay que documentarlo en openapi.yaml, porque un código de error sin documentar no forma parte del contrato.

La diferencia entre los dos 404 conviene tenerla clara:

El orden es crítico. Este middleware debe registrarse el último de los normales; si estuviera antes de app.use('/v1', rutasV1), respondería 404 a absolutamente todo. En 03-07 añadiremos por detrás de él el middleware de errores, que es el único que va después.

El src/app.js completo queda así:

Esos cinco bloques numerados son el orden definitivo de la aplicación. Durante el resto del módulo solo insertaremos piezas entre ellos, nunca cambiaremos la secuencia.

Con npm run dev en marcha, en otra terminal:

Si tienes jq instalado, la lectura mejora mucho:

Atención a 14.5. El contrato de 02-05 dice "euros con dos decimales", pero JSON no distingue 14.50 de 14.5: son el mismo número y así lo serializa JSON.stringify. Los dos decimales son una cuestión de formato de presentación, responsabilidad del cliente, no del transporte. Lo importante —y lo que sí controlamos— es que el valor sea exacto, y lo es porque por dentro son 1450 céntimos enteros. Si un consumidor necesitara literalmente la cadena "14.50", habría que serializar el precio como texto, y esa es una decisión de contrato que ya descartamos en 02-05.

Cinco comprobaciones, cinco respuestas conformes al contrato. En 03-08 convertiremos exactamente estas llamadas en pruebas automáticas con Supertest, para que nadie tenga que ejecutarlas a mano nunca más.

Ahora mismo la terminal no dice nada cuando llega una petición, y eso hace incómodo depurar. La solución mínima es un middleware de cinco líneas, que además sirve de ejemplo perfecto de la firma que hemos aprendido:

La alternativa habitual es morgan (npm install morgan), un middleware de registro con formatos predefinidos:

Cualquiera de los dos vale para desarrollar. Pero que quede claro que esto no es observabilidad: no hay niveles de log, ni formato estructurado en JSON, ni identificador de correlación, ni métricas, ni trazas. console.log en producción es un log que nadie puede consultar ni agregar. La observabilidad seria —logs estructurados con pino, métricas, trazas distribuidas y el trazaId que emitiremos en los 500— es la lección 04-07. En 03-07 daremos el primer paso generando ese trazaId para correlacionar un error con su log.

1. La petición se queda colgada para siempre. Un middleware ni llamó a next() ni respondió. Recorre la cadena de arriba abajo buscando el que no cierra ningún camino.

2. Error: Can't set headers after they are sent. Se respondió dos veces: un res.json() sin return seguido de otro, o un next() después de responder. Usa siempre return res.json(...) cuando la función pueda continuar.

3. Las rutas devuelven 404 aunque el fichero exista. Casi siempre es el montaje: recuerda que las rutas del router son relativas. Si escribes rutasCafes.get('/cafes', ...) y lo montas en /v1/cafes, la URL real es /v1/cafes/cafes.

4. req.body es undefined. Falta express.json() o está registrado después de las rutas. El orden manda.

5. req.body llega vacío aunque express.json() está puesto. El cliente no envió Content-Type: application/json. En curl, la opción es -H "Content-Type: application/json".

6. /:id declarada antes que una ruta fija. /destacados deja de existir. Lo específico, primero.

7. EADDRINUSE: address already in use :::3000. Hay otro proceso en el puerto, normalmente un npm run dev anterior que no murió. lsof -i :3000 lo identifica; kill <pid> lo cierra.

8. Meter la lógica de negocio dentro de la ruta. Hoy hemos consultado el repositorio directamente desde el router porque no hay nada más. Es el último día: en 03-03 se separa en controlador y servicio, y no volverá a ocurrir.

Consejo: define el orden de los middleware una vez, coméntalo con números como hemos hecho en app.js y respétalo. Los fallos más difíciles de diagnosticar en Express son siempre de orden.

Añade al router de cafés la ruta GET /v1/cafes/:id/resenas, que forma parte del mapa de URIs de 02-02. De momento no hay reseñas, así que debe devolver una colección vacía con el envoltorio del contrato, pero solo si el café existe; si no existe, debe devolver 404 cafe_no_encontrado. Explica por qué una colección vacía es 200 y no 404.

Escribe un middleware llamado cabeceraServidor que añada a todas las respuestas la cabecera Aroma-Version: 1.0.0. Regístralo en src/app.js en la posición correcta y justifícala. Comprueba el resultado con curl -i. ¿Por qué Aroma- y no X-Aroma-?

Este código tiene tres errores. Encuéntralos, explica qué le pasa a la petición con cada uno y escribe la versión corregida.

Solución 1

Por qué 200 y no 404: el recurso solicitado es la colección de reseñas del café caf_001, y esa colección existe; lo que ocurre es que está vacía. Un 404 significaría "esta URI no identifica ningún recurso", y obligaría al cliente a tratar el caso normal "aún no hay reseñas" como un error. La regla, que ya vimos en 02-04: colección vacía es 200 con {"datos": [], "total": 0}; recurso inexistente es 404. Coherente con la decisión de 02-05 de que los arrays vacíos se representan como [] y nunca como null ni ausentes.

Solución 2

Por qué esa posición: debe ir antes de cualquier cosa que pueda responder —rutas, 404, errores—, porque las cabeceras solo pueden fijarse mientras la respuesta no se haya enviado. Colocado el primero, la cabecera acompaña a todas las respuestas, incluidos los 404 y los 500.

Por qué Aroma- y no X-Aroma-: el prefijo X- para cabeceras no estándar quedó desaconsejado por el RFC 6648 en 2012. El problema histórico es que muchas cabeceras X- acababan estandarizándose y entonces convivían dos nombres para lo mismo (X-Forwarded-For es el ejemplo canónico). La recomendación actual es usar un prefijo propio del proveedor sin X-, y por eso el contrato de 02-05 fijó Aroma-.

Solución 3

Versión corregida:

Nota sobre next: se ha eliminado del todo de la firma. Un manejador final de ruta no necesita next porque siempre responde; declararlo invita a llamarlo por error. En este módulo solo lo usaremos en los middleware intermedios y, a partir de 03-07, para propagar errores con next(error).

Ya hay un servidor. Y más allá de que responda, lo importante es lo que has entendido de él: que Express es una cadena ordenada de middleware con la firma (req, res, next), que cada pieza decide si cede el turno o responde, y que el orden de registro es el orden de ejecución, sin excepciones. Esa idea es el 90 % de Express, y con ella encajarán sin sorpresas la validación de 03-04, la autenticación de 03-06 y el manejo de errores de 03-07.

Has tomado además tres decisiones estructurales que sostienen el resto del módulo. app.js separado de servidor.js, para que la aplicación sea un objeto que las pruebas de 03-08 puedan usar sin abrir un puerto. El Router montado en /v1, que convierte el versionado en la ruta de 02-07 en un prefijo compuesto en tres niveles y hace que una futura v2 sea una línea de código, no una migración. Y el almacén tras una interfaz de repositorio con buscarTodos y buscarPorId, cuyos nombres reaparecerán idénticos en 03-05 cuando detrás haya SQLite. Además, las respuestas ya cumplen el contrato: envoltorio {datos, total} en la colección, objeto desnudo en el elemento, céntimos por dentro y euros por fuera, y un 404 con codigo, mensaje y detalles.

Lo que hoy chirría es que toda la lógica vive dentro del router, que la conversión a la representación pública es una función suelta con un comentario de "provisional", y que solo sabemos leer. En 03-03, Manejo de peticiones y respuestas, lo arreglamos: exprimiremos los objetos req y res, partiremos el código en rutas → controladores → servicios, escribiremos el mapeador de representación en su sitio, e implementaremos el contrato completo de escritura —POST con 201 y Location, PUT, PATCH con merge-patch+json y su 415, DELETE lógico— junto con los filtros, la ordenación, la paginación y la cabecera Link que diseñamos en 02-06.