Al llarg del mòdul han anat quedant caps solts, tots del mateix tipus. carregarEsdeveniment propaga ESDEVENIMENT_NO_TROBAT amb seguent(error). El domini llança AFORAMENT_INSUFICIENT quan la Sala Bóveda ja no té entrades. express.json() rebutja un cos malformat. El middleware validar de 06-06 crida seguent(new ErrorDeValidacio(...)), una classe que encara no existeix. I el middleware 404 de 06-03 propaga RUTA_NO_TROBADA. Ningú no recull res d'això. En aquesta lliçó construïm la destinació comuna: un gestor central que converteix qualsevol fallada en una resposta coherent, i una política clara sobre què es pot convertir en una resposta amable i què no. És l'última peça del mòdul, i la que dona sentit a la taula ESTAT_PER_CODI del mòdul 4.

1. El middleware d'error i la seva signatura de quatre arguments
2. El gestor per defecte d'Express
3. Errors síncrons, asíncrons i la gran millora d'Express 5
4. Una jerarquia d'errors pròpia
5. ESTAT_PER_CODI troba el seu lloc
6. Errors operatius enfront d'errors de programació
7. El gestor central complet
8. El middleware 404
9. Errors fora d'Express
10. Llista de comprovació del mòdul

Un middleware d'error és idèntic als altres tret d'una cosa: té quatre paràmetres.

Express distingeix els dos tipus inspeccionant fn.length, l'aritat de la funció: si val 4, és gestor d'errors; si no, és middleware normal. Els símptomes de la versió dolenta són desconcertants: els errors continuen mostrant-se amb el format per defecte d'Express, i a les peticions correctes apareix un 500 inexplicable, perquè la teva funció rep (req, res, next) i tracta req com si fos un error. Si no fas servir seguent, declara'l igualment: configura ESLint per permetre arguments no utilitzats al final, o anomena'l _seguent, però no el treguis.

Un gestor d'errors només captura el que s'ha propagat des de middleware i rutes registrats per damunt d'ell. Registrar-lo al mig significa que tot el declarat després escapa al seu control: si escrius aplicacio.use(gestorDErrors) i només després aplicacio.use('/api', crearRutesApi()), els errors de l'API no hi arriben. És el mateix principi de l'ordre de 06-04, aplicat al final de la cadena.

Un gestor d'errors pot cridar seguent(error) per passar-lo al següent, igual que a la cadena normal, cosa que serveix per separar responsabilitats: aplicacio.use(registrarError) registra i propaga, aplicacio.use(errorDeValidacio) tracta només un tipus o propaga, i aplicacio.use(gestorFinal) respon sempre. El que no ha de passar mai és que l'últim no respongui.

Si no en registres cap, Express té el seu, i fa tres coses assenyades: fa servir error.status o error.statusCode si existeixen (si no, respon 500); fixa les capçaleres que porti error.headers; i envia el cos de l'error, amb una diferència crítica segons l'entorn:

Aquest comportament és correcte i val la pena entendre per què. Una traça de pila revela rutes absolutes del servidor (/home/desplegament/escena-viva/src/...), noms de mòduls interns, versions de biblioteques i de vegades fragments de dades: un mapa de franc per a qui estigui buscant per on entrar. En desenvolupament la vols veure sencera; en producció no ha de sortir mai del servidor. El nostre gestor propi manté exactament aquesta política, però amb el nostre format JSON en comptes d'HTML. Un detall sovint ignorat: Express assumeix NODE_ENV=production per a això, i a Escena Viva fem servir produccio en català, així que cal ser explícits i no dependre de la comparació interna del framework —per això el nostre gestor consulta configuracio.esProduccio.

Els errors síncrons Express sempre els ha capturat: un throw dins d'un gestor síncron va al gestor d'errors, sense més.

A Express 4, el framework cridava el gestor, aquest retornava una promesa que ningú no observava, i el rebuig es convertia en un unhandledRejection sense resposta al client: ni error visible, ni 500, ni res, només el client esperant. Si et trobes asyncHandler, express-async-handler, catchAsync o wrapAsync en un projecte, ja saps què són: restes d'Express 4. A Express 5 sobren, i treure'ls elimina una capa de soroll de cada ruta.

Aquesta última fila és l'excepció que no desapareix. Express només pot observar la promesa que li retornes:

La regla: si un error pot passar dins d'una devolució de trucada, promisifica aquesta operació. És una raó més per preferir fs.promises i les utilitats dels mòduls 2 i 3.

Fins ara creaves errors amb Object.assign(new Error(...), { codi }). Funciona, però no permet distingir tipus amb instanceof, no obliga a res i s'escriu diferent a cada lloc. El formalitzarem.

Decisions que mereixen explicació:

• this.name = new.target.name: cada subclasse s'identifica amb el seu propi nom als registres, sense repetir-lo a mà; i { cause } preserva l'error original en envoltar-lo, amb la cadena completa per al registre i sense filtrar-la al client.
• this.estat opcional deixa que el domini llanci errors amb només un codi, sense saber res d'HTTP; Error.captureStackTrace elimina el constructor de la traça, que comença on de debò va passar la fallada; i esOperatiu = true és la marca central de l'apartat 6.

Ús al domini, que continua sense conèixer HTTP:

Al mòdul 4 vas escriure src/servidor/errors-http.js amb estatPerError, cosPerError i la taula ESTAT_PER_CODI, que vivia repartida pels gestors de respostes.js. Ara té un únic client: el gestor central.

La cascada de quatre passos fa que tot encaixi al mateix lloc: la nostra jerarquia, els codis que el domini llança sense saber d'HTTP i els errors de tercers. Per a aquests últims convé a més normalitzar el codi, perquè el client vegi sempre el vocabulari d'Escena Viva:

Aquesta distinció és la que decideix què s'explica al client i què no:

Com es distingeixen al codi:

Per què el bug retorna un 500 mut. Si un TypeError es filtra al client amb el seu missatge, publiques el nom de les teves variables internes, la línia del fitxer i, amb la traça, mig arbre de directoris. A més, aquest missatge no li serveix de res a qui crida l'API: no pot corregir la seva petició perquè el problema no hi és. Un 500 amb l'identificador de la petició és més útil per a tothom: el client sap que la fallada és teva i té una referència amb què reclamar, i tu tens la traça completa als teus registres.

Dues respostes reals, una d'operativa i una altra de bug:

La segona no diu absolutament res de la fallada, però als registres del servidor hi ha la traça completa associada a aquest mateix idPeticio que el client té al davant. Aquesta correlació —l'identificador de 06-04 apareixent a la resposta i al registre— és el que converteix un informe d'incidència inútil («em va donar error») en un d'accionable («em va donar error, referència 3b71e0a2»).

Per què va abans del gestor d'errors i després de les rutes: és un middleware normal, no d'error, i Express hi arriba quan cap ruta anterior no ha respost. Si el posessis abans de les rutes, respondria 404 a tot; si el posessis després del gestor d'errors, no s'executaria mai. I propaga en comptes de respondre perquè el 404 passi pel mateix punt que la resta d'errors i surti amb codi, estat, idPeticio i el mateix format: curl -s localhost:3000/api/no-existeix retorna {"error":{"codi":"RUTA_NO_TROBADA","missatge":"No s'ha trobat ruta GET /api/no-existeix",...}}. Un client que sap interpretar els teus errors no hauria de necessitar cap cas especial per al 404.

Express només veu el que passa dins d'una petició; hi ha dos successos del procés que se li escapen:

La temptació és evident: capturar l'error, registrar-lo i deixar el servidor dret per no perdre el servei. És un error greu, i aquestes són les raons:

1. L'estat del procés és desconegut. L'excepció s'ha propagat per una pila que no l'esperava: hi ha funcions a mitges, amb variables actualitzades parcialment. A Escena Viva, una excepció enmig de GestorDeVendes.registrar pot deixar les entrades descomptades de l'aforament però la comanda sense crear.
2. Es perden recursos. Cada excepció no capturada pot deixar sense tancar un descriptor de fitxer, un socket o un temporitzador: el procés «sobreviu» degradant-se fins a exhaurir la memòria.
3. Amaga el bug. Un servidor que continua funcionant malament no genera urgència, i la fallada s'acumula durant setmanes. A més, el comportament per defecte d'uncaughtException sense gestor és acabar, i així ha de ser.

La política correcta, i la que apliquem, és: registrar l'error sencer → deixar d'acceptar peticions noves → donar uns segons a les peticions en curs → acabar el procés → que el supervisor el reiniciï. Qui reinicia és assumpte de l'entorn, i al mòdul 11 ho veurem amb noms propis: PM2 en mode cluster, restart: always a Docker o el reinici automàtic d'un contenidor gestionat. L'aplicació no es reinicia a si mateixa: es mor amb dignitat i deixa que el supervisor faci la seva feina.

Abans de donar Escena Viva per acabada, repassa punt per punt:

• [ ] crearAplicacio() a src/app.js no crida listen i retorna l'aplicació; src/servidor.js crea el servidor http, arrenca i registra l'aturada ordenada.
• [ ] src/config/index.js és l'únic lloc que llegeix process.env, i valida en arrencar; x-powered-by desactivat i trust proxy d'acord amb el desplegament real.
• [ ] Routers a src/rutes/ i controladors a src/controladors/, tots dos sense lògica de negoci; rutes ordenades d'específica a genèrica, amb el comodí l'últim.
• [ ] Tots els camins de cada middleware responen o criden seguent, i l'ordre és el canònic de 06-05: id, seguretat, CORS, registre, compressió, límits, cos, estàtics, rutes, 404, errors.
• [ ] express.json() amb limit; express.static amb dotfiles: 'ignore'; helmet actiu amb la CSP ajustada al front-end en comptes de desactivada.
• [ ] CORS amb llista blanca des de configuració, mai '*' amb credentials; límit de peticions a POST /api/comandes.
• [ ] Tota entrada validada amb esquema a la vora (i a req.dadesValidades, no reassignant req.query); el domini conserva els seus invariants.
• [ ] Jerarquia d'errors a src/errors.js i gestor central l'últim; traça a la resposta només fora de producció, i idPeticio a les respostes d'error i als registres.
• [ ] unhandledRejection i uncaughtException registren i acaben ordenadament; npm audit net i dependències revisades amb el criteri del mòdul 5.

• Oblidar el quart paràmetre. Sense seguent, Express tracta el teu gestor com a middleware normal: no rep mai errors i trenca les peticions sanes.
• Registrar-lo abans que les rutes. Només captura el declarat per damunt.
• Filtrar la traça en producció o tractar els bugs com a errors operatius. Publiques rutes del sistema i versions, i un TypeError detallat no ajuda el client però a tu et delata; comprova-ho amb NODE_ENV=produccio abans de desplegar. I no continuïs després d'un uncaughtException: el procés queda en estat desconegut, així que registra i acaba.
• Respondre quan res.headersSent ja és true. Provoca Cannot set headers after they are sent; comprova l'indicador i delega en Express.
• Perdre la causa en envoltar errors. Fes servir new Error(missatge, { cause: original }); sense això la traça comença on vas envoltar, no on va fallar. I mantén trivial el gestor mateix: si fa JSON.stringify d'alguna cosa amb referències circulars, fallarà al pitjor lloc possible.
• Consell: prova els teus errors. Al mòdul 9, amb supertest, verifica que un aforament insuficient retorna 409 amb AFORAMENT_INSUFICIENT, que un :id invàlid retorna 400 i que un bug forçat retorna un 500 sense traça en producció.

Implementa src/errors.js complet i fes que el domini el faci servir. Comprova amb curl quatre casos, tots amb idPeticio: GET /api/esdeveniments/evt-999 → 404 ESDEVENIMENT_NO_TROBAT; POST /api/comandes amb quantitat: 99 → 400 DADES_INVALIDES amb detalls; POST /api/comandes demanant més entrades de les lliures → 409 AFORAMENT_INSUFICIENT; i GET /api/no-existeix → 404 RUTA_NO_TROBADA.

Afegeix una ruta /api/depuracio/fallada que provoqui un TypeError real (llegir una propietat d'undefined). Comprova que amb NODE_ENV=desenvolupament la resposta inclou traca, que amb NODE_ENV=produccio retorna el 500 mut, i que en tots dos casos stderr mostra la traça completa amb el prefix [BUG] i l'idPeticio.

Crea dues rutes async que rebutgin, una envoltada en asyncHandler i l'altra sense envoltar, i comprova a Express 5 que es comporten igual. Després escriu un gestor que llanci dins d'un setTimeout i explica per què aquest sí que tomba el procés, i com ho arreglaries.

Solució 1

Fixa't en la diferència entre els dos últims: quantitat: 99 és un problema de forma (400, el detecta l'esquema sense mirar l'estat del sistema); demanar 6 entrades quan en queden 3 és un problema d'estat (409, només el pot detectar el domini en aquell instant). Són els dos nivells de 06-06 funcionant.

Solució 2

En tots dos casos, stderr mostra la mateixa traça completa precedida de [BUG] 3b71e0a2-... GET /api/depuracio/fallada 500 TypeError.

Solució 3

Amb curl, /a, /b i /d retornen un 500 amb el seu missatge —les dues primeres, idèntiques—, mentre que /c mata el procés amb un uncaughtException, perquè el seu throw passa en un tic posterior del bucle d'esdeveniments (mòdul 2), en una pila on ja no hi ha res d'Express, i la promesa que el gestor va retornar —cap, en aquest cas— no pot observar aquesta fallada. L'arranjament és /d: promisificar l'espera perquè el throw passi dins de la cadena async que Express sí que observa. Conclusió pràctica: asyncHandler és innecessari a Express 5, però promisificar continua sent obligatori.

Amb aquesta lliçó es tanca el mòdul 6, i Escena Viva ja és una API Express completa. Els errors tenen per fi una destinació única. Saps que el gestor d'error s'identifica pels seus quatre paràmetres i que oblidar l'últim el converteix en un middleware normal amb símptomes desconcertants; que va registrat l'últim perquè només veu el declarat per damunt; i que el gestor per defecte d'Express filtra la traça en producció i la mostra en desenvolupament, política que el teu gestor propi reprodueix amb el teu format JSON. Has vist la gran millora d'Express 5 —un gestor async que rebutja arriba sol al gestor d'errors, i asyncHandler passa a ser una relíquia d'Express 4— amb la seva única excepció viva: el que passa dins d'una devolució de trucada continua sent cosa teva, i per això es promisifica.

Has construït una jerarquia pròpia a src/errors.js amb ErrorDAplicacio i les seves subclasses ErrorDeValidacio, RecursNoTrobat i ConflicteDEstat, i la taula ESTAT_PER_CODI que vas escriure al mòdul 4 ha trobat per fi el seu lloc definitiu: un únic punt on els codis del domini, els de la teva jerarquia i els dels paquets de tercers es tradueixen a estats HTTP. Distingeixes els errors operatius —esperables, explicats al client amb detall— dels errors de programació —registrats sencers, retornats com un 500 mut amb només l'identificador de petició com a referència—. I fora d'Express, unhandledRejection i uncaughtException registren i acaben el procés ordenadament, sense fingir que no ha passat res, deixant el reinici a un supervisor que arribarà al mòdul 11.

Mira ara el projecte sencer. crearAplicacio() es prova sense arrencar res. La configuració es llegeix i es valida en un sol lloc. Els routers de /api/esdeveniments, /api/sessions i /api/comandes viuen en fitxers de trenta línies amb els seus controladors al costat. Els teus middleware propis mesuren, identifiquen i controlen la memòria cau; els de tercers afegeixen capçaleres de seguretat, CORS, registre, compressió i límits d'ús. Els esquemes de zod descriuen exactament què accepta cada endpoint. I qualsevol fallada, vingui d'on vingui, surt amb la mateixa forma i amb un identificador que l'enllaça amb els registres del servidor. Això és una API de producció. Però hi ha una cosa que no ha canviat des del mòdul 3, i ja comença a incomodar: les dades continuen vivint a dades/esdeveniments.json. Cada venda reescriu un fitxer sencer. Dos compradors que premen «comprar» alhora per a les últimes entrades de la Sala Bóveda llegeixen tots dos el mateix aforament, tots dos veuen que hi ha lloc i tots dos escriuen. El fitxer acaba amb les vendes del segon i les del primer desapareixen, o pitjor: es venen més entrades de les que caben a la sala. Cap validació d'esquema no evita això, cap middleware no ho detecta i cap gestor d'errors no ho pot arreglar, perquè no és un error: és una cursa entre dues escriptures.

Al mòdul 7 les dades deixen de viure en un JSON. Començarem per entendre què és una base de dades i què aporta enfront d'un fitxer, modelarem Escena Viva amb MongoDB i Mongoose, escriurem el CRUD complet, explorarem relacions i consultes avançades, veurem el món SQL amb Sequelize i acabarem amb migracions, llavors i —el que estaves esperant— transaccions, que són exactament la resposta al problema de l'aforament i la sobrevenda que acabem de descriure. El JSON ens ha servit durant set mòduls; ha arribat el moment de jubilar-lo.