A la lliçó anterior vam deixar un projecte amb carpetes buides, dependències instal·lades i configuració validada, però incapaç de respondre res. Avui això canvia: en acabar tindràs un servidor Express escoltant a http://localhost:3000 que serveix GET /v1/cafes i GET /v1/cafes/caf_001 amb el format exacte que vam fixar al mòdul 2, un endpoint de salut, i un 404 que ja parla l'idioma del contracte. Pel camí entendrem l'única idea que cal entendre de debò per treballar amb Express —el middleware—, veurem per què separar app.js de servidor.js és una decisió d'arquitectura i no un caprici, i muntarem el Router sota /v1, que és on el versionat a la ruta decidit a 02-07 deixa de ser un diagrama i es converteix en codi.

1. Què és Express i què no és
2. El concepte central: middleware
3. El cicle de vida d'una petició
4. src/app.js i src/servidor.js: per què van separats
5. Primera arrencada i endpoint de salut
6. Middleware integrat: express.json i express.urlencoded
7. El Router d'Express i el muntatge de /v1
8. Dades en memòria: src/repositoris/cafes-memoria.js
9. Les primeres rutes de cafès
10. Rutes amb paràmetres i req.params
11. Enviar respostes: res.status, res.json, res.set, res.sendStatus
12. El 404 genèric amb el format d'error del contracte
13. Provar-ho tot amb curl
14. Registre de peticions: morgan i fins on arribem avui

Node inclou un mòdul http amb el qual ja es pot muntar un servidor:

Funciona, i ensenya una cosa important: Express no fa res que tu no poguessis fer. Però aquell if/else creix fins a l'inmanejable tan bon punt hi ha vint rutes, paràmetres de ruta, cossos JSON per analitzar i comportaments comuns a totes les peticions.

Express és una capa fina sobre node:http que aporta exactament quatre coses:

I és igual d'important saber què no és: Express no és un framework "amb bateries incloses". No porta ORM, ni validació, ni autenticació, ni estructura de carpetes obligatòria. Tot això ho poses tu —i per això el mòdul té vuit lliçons—. A canvi, no hi ha màgia: cada cosa que passa en una petició està escrita en algun fitxer teu. Per aprendre com funciona de debò una API és la millor elecció possible. A 05-03 compararem Express amb Fastify, NestJS i altres.

Un middleware és una funció que rep la petició, hi pot fer alguna cosa i decideix si la passa a la funció següent de la cadena. Tota la seva definició cap en una signatura:

I tres regles que expliquen el 90 % dels problemes d'un principiant amb Express:

1. Els middleware s'executen en l'ordre en què es registren. No hi ha prioritats ni màgia: és una llista, de dalt a baix.
2. Si un middleware no crida next() ni respon, la petició es queda penjada fins que el client se'n cansa. És l'error més freqüent.
3. Si un middleware respon (res.json(...)), la cadena acaba aquí. Cridar next() després provoca el famós ERR_HTTP_HEADERS_SENT.

Un exemple amb tres middleware encadenats per veure l'ordre en directe:

Un gestor de ruta (app.get, app.post) també és un middleware; simplement està condicionat a un mètode i una ruta. Aquesta uniformitat és la clau del disseny d'Express: tot és la mateixa cosa. La validació de 03-04, l'autenticació de 03-06 i la gestió d'errors de 03-07 seran middleware amb aquesta mateixa signatura.

Aquest és el recorregut complet que tindrà una petició a la Botiga Aroma al final del mòdul. Avui muntem les caixes grises; les altres arriben a les lliçons indicades.

El que cal retenir: una petició travessa la cadena de dalt a baix i surt per un de dos llocs, una resposta normal o el middleware d'errors. Res més.

Gairebé tots els tutorials d'Express fiquen en un únic fitxer la creació de l'app i la crida a listen(). Nosaltres no, i el motiu és concret:

L'avantatge apareix a 03-08. Supertest, l'eina amb què provarem l'API, accepta l'objecte app d'Express i li llança peticions sense obrir cap port TCP. Si app.js cridés listen(), cada fitxer de proves ocuparia el port 3000 i dues suites en paral·lel xocarien amb EADDRINUSE. Separant-ho, l'app és un objecte reutilitzable i el port és un detall de desplegament.

Comencem per src/app.js:

I src/servidor.js:

Sobre el tancament ordenat: sense ell, Ctrl+C talla de cop i una petició a mig respondre mor sense resposta. Amb servidor.close(), el sòcol deixa d'acceptar clients nous però les peticions vives acaben. A 03-05 hi afegirem el tancament de la base de dades i a 03-07 la captura d'errors no controlats del procés.

Fixa't en la direcció dels import: servidor.js importa app.js, mai a l'inrevés.

En un altre terminal:

Val la pena aturar-se en tres detalls d'aquesta resposta:

• Content-Type: application/json; charset=utf-8 l'ha posat res.json() automàticament. És el que vam declarar al contracte.
• ETag també ve de sèrie. És la base de la memòria cau condicional, que tractarem a 04-06.
• No hi ha X-Powered-By, gràcies a app.disable.

Per què /salut és fora de /v1? Perquè no és part de l'API pública: no la consumeixen la SPA ni l'Aroma Mòbil, sinó el balancejador de càrrega i la monitoratge. No forma part del contracte versionat, així que no s'ha de versionar. És l'excepció que confirma la regla de 02-07.

Quan arriba un POST amb cos JSON, el cos viatja com un flux de bytes. Sense ajuda, req.body és undefined. express.json() és un middleware que llegeix aquell flux, l'analitza i deixa l'objecte a req.body.

Afegeix-lo a src/app.js, abans de les rutes:

Dues conseqüències que cal conèixer des d'ara. La primera: si el client envia JSON mal format, express.json() llança un SyntaxError que avui produeix una pàgina HTML d'error lletja; a 03-07 el convertirem en un 400 dades_invalides del contracte. La segona: si el client no envia Content-Type: application/json, el middleware no analitza res i req.body queda com {}; és la causa número u del "el meu POST arriba buit".

Posar totes les rutes a app.js funciona amb dues i és insostenible amb vint-i-quatre. Un Router és una miniaplicació d'Express: té les seves pròpies rutes i els seus propis middleware, i es munta sota un prefix.

Crearem dos fitxers. Primer, el router de cafès (src/rutes/cafes.js), que de moment només declara les seves rutes relatives:

I ara l'agregador (src/rutes/index.js), que aplega tots els routers de la versió 1:

I es munta a src/app.js:

El resultat és una composició de prefixos en tres nivells:

I aquí hi ha el guany real de 02-07 fet codi: el dia que existeixi una v2, es crea src/rutes/v2/ i s'afegeix app.use('/v2', rutesV2). Les dues versions conviuen al mateix procés, compartint serveis on el comportament no canviï i divergint on sí. Sense aquest muntatge, "convivència de versions" seria una frase bonica impossible d'implementar.

Encara no tenim base de dades —això és 03-05—, així que els cafès viuran en un array. Però el col·loquem ja a la carpeta de repositoris i darrere d'una interfície, perquè l'objectiu declarat és substituir-lo per SQLite sense que la resta del codi se n'assabenti.

Dues decisions que semblen menors i no ho són:

• Els noms dels mètodes (buscarTots, buscarPerId) són la interfície del repositori. A 03-05 escriurem cafes-sqlite.js amb exactament els mateixos noms, i canviar d'un a l'altre serà canviar un import.
• Es retornen còpies ({ ...cafe }), no les referències de l'array. Si retornéssim la referència, qualsevol capa superior podria modificar el "magatzem" per accident. Amb una base de dades real això és impossible per construcció; en memòria cal imposar-ho a mà.

Ara connectem el repositori amb el router. Substitueix el contingut de src/rutes/cafes.js:

Detalls importants d'aquest fitxer:

• L'embolcall només és a la col·lecció. GET /v1/cafes retorna {dades, total}; GET /v1/cafes/:id retorna l'objecte nu. És exactament el que vam decidir a 02-05.
• return res.status(404)...: el return no retorna res d'útil a Express, però talla l'execució de la funció. Sense ell, continuaria fins al res.status(200) i provocaria ERR_HTTP_HEADERS_SENT.
• total és avui la longitud de l'array. Quan a 03-03 hi hagi filtres i paginació, total serà el nombre d'elements que compleixen el filtre, no els retornats a la pàgina. Aquesta distinció es cobra bugs.
• ?? null (fusió de nuls) retorna el valor de l'esquerra llevat que sigui null o undefined. No s'ha de confondre amb ||, que també substituiria el 0 o la cadena buida.

'/:id' declara un segment variable. Express captura el que hi hagi en aquella posició i ho deixa a req.params.id, sempre com a cadena de text.

Que els nostres identificadors siguin cadenes amb prefix (caf_001) juga a favor: no cal convertir res ni preocupar-se d'un parseInt que retorni NaN. Va ser una decisió de 02-02 i aquí es cobra el primer dividend.

Un avís sobre l'ordre, que és el parany clàssic:

Express recorre les rutes en ordre de declaració i es queda amb la primera que coincideix. El que és concret va abans que el que és variable.

Un router germà molt útil és router.param(), que executa codi cada vegada que apareix un paràmetre concret —per exemple, carregar el cafè i deixar-lo a req.cafe—. L'esmentem perquè el coneguis; en aquest curs preferim fer-ho explícit al servei.

Tres avisos pràctics:

En aquest mòdul farem servir gairebé sempre el mateix patró: res.set(...) per a les capçaleres del contracte i res.status(...).json(...) per al cos.

Si demanes GET /v1/inexistent, cap ruta no coincideix i Express respon amb el seu 404 per defecte: una pàgina HTML amb el text Cannot GET /v1/inexistent. Per a un consumidor que espera JSON, això trenca el contracte en tres fronts: Content-Type equivocat, forma del cos desconeguda i filtració del framework.

Afegim un middleware final a src/app.js, després de totes les rutes:

Dues precisions sobre el catàleg. El codi ruta_no_trobada no era al catàleg de 02-04, que només tenia els 404 específics (cafe_no_trobat, comanda_no_trobada…). L'afegim ara per al cas genèric —una URI que no existeix en absolut—, i això és perfectament legítim: la regla que vam fixar és que el catàleg només creix; afegir un codi és un canvi additiu, retirar-lo seria trencador. I cal documentar-ho a openapi.yaml, perquè un codi d'error sense documentar no forma part del contracte.

La diferència entre els dos 404 convé tenir-la clara:

L'ordre és crític. Aquest middleware s'ha de registrar l'últim dels normals; si estigués abans d'app.use('/v1', rutesV1), respondria 404 a absolutament tot. A 03-07 hi afegirem al darrere el middleware d'errors, que és l'únic que va després.

L'src/app.js complet queda així:

Aquests cinc blocs numerats són l'ordre definitiu de l'aplicació. Durant la resta del mòdul només hi inserirem peces entremig, mai canviarem la seqüència.

Amb npm run dev en marxa, en un altre terminal:

Si tens jq instal·lat, la lectura millora molt:

Atenció al 14.5. El contracte de 02-05 diu "euros amb dos decimals", però JSON no distingeix 14.50 de 14.5: són el mateix número i així ho serialitza JSON.stringify. Els dos decimals són una qüestió de format de presentació, responsabilitat del client, no del transport. L'important —i el que sí que controlem— és que el valor sigui exacte, i ho és perquè per dins són 1450 cèntims enters. Si un consumidor necessités literalment la cadena "14.50", caldria serialitzar el preu com a text, i aquesta és una decisió de contracte que ja vam descartar a 02-05.

Cinc comprovacions, cinc respostes conformes al contracte. A 03-08 convertirem exactament aquestes crides en proves automàtiques amb Supertest, perquè ningú no les hagi d'executar a mà mai més.

Ara mateix el terminal no diu res quan arriba una petició, i això fa incòmode depurar. La solució mínima és un middleware de cinc línies, que a més serveix d'exemple perfecte de la signatura que hem après:

L'alternativa habitual és morgan (npm install morgan), un middleware de registre amb formats predefinits:

Qualsevol dels dos serveix per desenvolupar. Però que quedi clar que això no és observabilitat: no hi ha nivells de log, ni format estructurat en JSON, ni identificador de correlació, ni mètriques, ni traces. console.log en producció és un log que ningú no pot consultar ni agregar. L'observabilitat seriosa —logs estructurats amb pino, mètriques, traces distribuïdes i el tracaId que emetrem als 500— és la lliçó 04-07. A 03-07 farem el primer pas generant aquest tracaId per correlacionar un error amb el seu log.

1. La petició es queda penjada per sempre. Un middleware ni ha cridat next() ni ha respost. Recorre la cadena de dalt a baix buscant el que no tanca cap camí.

2. Error: Can't set headers after they are sent. S'ha respost dues vegades: un res.json() sense return seguit d'un altre, o un next() després de respondre. Fes servir sempre return res.json(...) quan la funció pugui continuar.

3. Les rutes retornen 404 encara que el fitxer existeixi. Gairebé sempre és el muntatge: recorda que les rutes del router són relatives. Si escrius rutesCafes.get('/cafes', ...) i el muntes a /v1/cafes, la URL real és /v1/cafes/cafes.

4. req.body és undefined. Falta express.json() o està registrat després de les rutes. L'ordre mana.

5. req.body arriba buit encara que express.json() hi sigui. El client no ha enviat Content-Type: application/json. A curl, l'opció és -H "Content-Type: application/json".

6. /:id declarada abans que una ruta fixa. /destacats deixa d'existir. L'específic, primer.

7. EADDRINUSE: address already in use :::3000. Hi ha un altre procés al port, normalment un npm run dev anterior que no ha mort. lsof -i :3000 l'identifica; kill <pid> el tanca.

8. Ficar la lògica de negoci dins de la ruta. Avui hem consultat el repositori directament des del router perquè no hi ha res més. És l'últim dia: a 03-03 se separa en controlador i servei, i no tornarà a passar.

Consell: defineix l'ordre dels middleware una vegada, comenta'l amb números com hem fet a app.js i respecta'l. Les fallades més difícils de diagnosticar a Express són sempre d'ordre.

Afegeix al router de cafès la ruta GET /v1/cafes/:id/ressenyes, que forma part del mapa d'URIs de 02-02. De moment no hi ha ressenyes, així que ha de retornar una col·lecció buida amb l'embolcall del contracte, però només si el cafè existeix; si no existeix, ha de retornar 404 cafe_no_trobat. Explica per què una col·lecció buida és 200 i no 404.

Escriu un middleware anomenat capcaleraServidor que afegeixi a totes les respostes la capçalera Aroma-Versio: 1.0.0. Registra'l a src/app.js a la posició correcta i justifica-la. Comprova el resultat amb curl -i. Per què Aroma- i no X-Aroma-?

Aquest codi té tres errors. Troba'ls, explica què li passa a la petició amb cadascun i escriu la versió corregida.

Solució 1

Per què 200 i no 404: el recurs sol·licitat és la col·lecció de ressenyes del cafè caf_001, i aquella col·lecció existeix; el que passa és que és buida. Un 404 significaria "aquesta URI no identifica cap recurs", i obligaria el client a tractar el cas normal "encara no hi ha ressenyes" com un error. La regla, que ja vam veure a 02-04: col·lecció buida és 200 amb {"dades": [], "total": 0}; recurs inexistent és 404. Coherent amb la decisió de 02-05 que els arrays buits es representen com [] i mai com null ni absents.

Solució 2

Per què aquella posició: ha d'anar abans de qualsevol cosa que pugui respondre —rutes, 404, errors—, perquè les capçaleres només es poden fixar mentre la resposta no s'hagi enviat. Col·locada la primera, la capçalera acompanya totes les respostes, inclosos els 404 i els 500.

Per què Aroma- i no X-Aroma-: el prefix X- per a capçaleres no estàndard va quedar desaconsellat pel RFC 6648 el 2012. El problema històric és que moltes capçaleres X- acabaven estandarditzant-se i llavors convivien dos noms per a la mateixa cosa (X-Forwarded-For n'és l'exemple canònic). La recomanació actual és fer servir un prefix propi del proveïdor sense X-, i per això el contracte de 02-05 va fixar Aroma-.

Solució 3

Versió corregida:

Nota sobre next: s'ha eliminat del tot de la signatura. Un gestor final de ruta no necessita next perquè sempre respon; declarar-lo convida a cridar-lo per error. En aquest mòdul només el farem servir als middleware intermedis i, a partir de 03-07, per propagar errors amb next(error).

Ja hi ha un servidor. I més enllà que respongui, l'important és el que n'has entès: que Express és una cadena ordenada de middleware amb la signatura (req, res, next), que cada peça decideix si cedeix el torn o respon, i que l'ordre de registre és l'ordre d'execució, sense excepcions. Aquesta idea és el 90 % d'Express, i amb ella hi encaixaran sense sorpreses la validació de 03-04, l'autenticació de 03-06 i la gestió d'errors de 03-07.

A més, has pres tres decisions estructurals que sostenen la resta del mòdul. app.js separat de servidor.js, perquè l'aplicació sigui un objecte que les proves de 03-08 puguin fer servir sense obrir un port. El Router muntat a /v1, que converteix el versionat a la ruta de 02-07 en un prefix compost en tres nivells i fa que una futura v2 sigui una línia de codi, no una migració. I el magatzem darrere d'una interfície de repositori amb buscarTots i buscarPerId, els noms dels quals reapareixeran idèntics a 03-05 quan al darrere hi hagi SQLite. A més, les respostes ja compleixen el contracte: embolcall {dades, total} a la col·lecció, objecte nu a l'element, cèntims per dins i euros per fora, i un 404 amb codi, missatge i detalls.

El que avui grinyola és que tota la lògica viu dins del router, que la conversió a la representació pública és una funció solta amb un comentari de "provisional", i que només sabem llegir. A 03-03, Gestió de peticions i respostes, ho arreglem: exprimirem els objectes req i res, partirem el codi en rutes → controladors → serveis, escriurem el mapejador de representació al seu lloc, i implementarem el contracte complet d'escriptura —POST amb 201 i Location, PUT, PATCH amb merge-patch+json i el seu 415, DELETE lògic— juntament amb els filtres, l'ordenació, la paginació i la capçalera Link que vam dissenyar a 02-06.