Durant deu mòduls hem construït la xarxa de bicicletes elèctriques de Ribalta capa per capa. Primer un endpoint que retornava quatre estacions en memòria; després el contenidor de Spring i els seus beans; el contracte REST amb els seus DTOs i els seus errors; la persistència sobre PostgreSQL amb Flyway; la seguretat amb JWT i regles per dada; les proves; l'operabilitat; el desplegament; i per fi l'observabilitat, el criteri i la neteja. Cada lliçó va afegir una peça i va mirar gairebé sempre cap a la següent.

Mai no hem mirat CicloUrbana sencera. Aquesta lliçó ho fa: l'arquitectura completa en un diagrama, l'estructura real del repositori, el viatge d'una sola petició des del balancejador fins a la mètrica —citant a cada pas on es va estudiar—, el mapa de què va construir cada mòdul, les decisions de disseny amb les seves alternatives i les seves contrapartides, el pom.xml i la configuració finals, com posar el projecte en marxa des de zero i cap a on continuar portant-lo. Si has seguit el curs, aquí ho reconeixeràs tot; el que és nou és veure-ho junt.

1. L'arquitectura final
2. El repositori complet
3. El viatge d'una petició: POST /api/v1/lloguers
4. Mapa del curs: què va construir cada mòdul
5. Decisions de disseny i les seves alternatives
6. El pom.xml final
7. La configuració final
8. Posar en marxa el projecte des de zero
9. Recorregut d'extrem a extrem amb peticions .http
10. Llista de comprovació final de posada en producció
11. Cap a on continuar amb aquest projecte
12. Errors Comuns i Consells
13. Exercicis

Quatre observacions sobre el dibuix, perquè un diagrama sense lectura és decoració.

L'aplicació és un sol desplegable. Els cinc blocs de dins no són serveis: són capes i mòduls dins del mateix procés. És el monòlit modular de 07-05, i les fletxes entre ells són crides a mètodes, no crides de xarxa.

Les dependències apunten cap endins i cap avall. Filtres → controladors → serveis → repositoris → base de dades. Cap fletxa no puja. És la regla de dependència de 10-01, verificada automàticament amb les regles d'ArchUnit de 10-03.

L'observabilitat és un lateral, no una capa. No és al camí de la petició: l'aplicació publica mètriques, logs i traces, i uns altres els recullen. Si Prometheus cau, CicloUrbana continua funcionant.

L'única cosa que pot tombar el servei és PostgreSQL. La memòria cau de Redis degrada a Caffeine, la passarel·la té tallacircuits i respatller de cobrament diferit, i la resta és opcional. Aquesta asimetria és deliberada i és darrere del fet que la sonda readiness sí que consulti la base de dades i la de liveness no.

Dues coses mereixen atenció. src/test és un mirall exacte de src/main, cosa que permet accedir a membres amb visibilitat de paquet sense obrir la classe de producció i fa l'arbre navegable. I la separació *Test / *IT no és cosmètica: Surefire executa els primers a ./mvnw test en segons, i Failsafe els segons a ./mvnw verify amb PostgreSQL real.

La Marta obre l'aplicació a l'estació «Plaça Major», tria una bicicleta i prem «llogar». Això és el que passa.

El detall pas a pas, amb la seva lliçó:

El que es veu en ajuntar-ho. Els passos 9 i 10 els fa el mateix proxy, i per això el parany de l'autoinvocació s'endú per davant la transacció i la comprovació de permisos alhora. El pas 14 no és un detall d'estil: amb open-in-view: false és l'única manera que la resposta es construeixi sense LazyInitializationException. I els passos 16 a 18 són la raó que la Marta rebi el seu 201 en desenes de mil·lisegons mentre el cobrament triga gairebé dos segons en un altre fil.

Tota decisió d'arquitectura compra alguna cosa i en paga una altra. Aquestes són les sis principals de CicloUrbana, amb el que van costar.

I dues decisions menors que il·lustren la mateixa manera de pensar. open-in-view: false compra que cap consulta no es dispari durant la serialització, i paga amb l'obligació de mapejar a DTO dins de la transacció —cosa que, de passada, reforça una pràctica que volíem igualment—. La denegació per defecte compra que un oblit produeixi un 403 visible en lloc d'un endpoint obert, i paga amb el fet que cada ruta nova exigeixi una regla explícita.

Cap d'aquestes sis no és universalment correcta. El que les fa defensables és que es van prendre amb la contrapartida a la vista i van quedar escrites.

Les dependències acumulades, agrupades pel mòdul que les va introduir. La columna de versió és la informació important: només porten versió pròpia les que el BOM de Spring Boot no gestiona, i són exactament les que cal revisar a mà a cada actualització.

I la part del pom.xml que de debò cal llegir amb atenció, perquè és la que trenca la construcció davant d'un problema concret:

Els sis plugins no són adorn: cadascun trenca la construcció davant d'un problema concret —un camp sense mapejar, una prova d'integració fallida, codi sense formatar, una vulnerabilitat alta—. És la idea de fons de 10-01: moure la comprovació del cap d'una persona a la construcció.

I les diferències per entorn, que és l'única cosa que canvia:

El pas 3 mereix un comentari: ./mvnw verify aixeca un PostgreSQL efímer amb Testcontainers i aplica les nou migracions a sobre abans d'executar les *IT. Si aquesta ordre passa a la teva màquina, el projecte està sa de dalt a baix.

I les tres comprovacions que tanquen el recorregut, que són les que demostren que l'observabilitat del mòdul 9 funciona de debò:

Si els tres retornen dades, les tres senyals estan connectades: la mètrica detecta, la traça localitza i el log explica.

El punt 13 no va aparèixer en cap lliçó i és dels que surten més cars: una còpia de seguretat que mai no s'ha restaurat no és una còpia de seguretat, és una esperança. I el 15 repeteix l'advertiment del mòdul 5: tot el que s'ha construït en aquest curs és un punt de partida didàctic i necessita revisió professional abans d'exposar-se a Internet.

CicloUrbana està acabada com a material de curs, no com a producte. Aquestes set extensions estan ordenades per dificultat i cadascuna combina lliçons que ja coneixes.

Sobre la número 7, que és la que més gent vol fer primer: és l'última de la llista per una raó. Repartir el sistema en dos processos converteix una transacció local en una saga amb compensacions, una traça de pila en una investigació entre dos desplegaments, i una crida a mètode en una crida de xarxa que pot fallar. Fes-la només quan tinguis traçabilitat distribuïda funcionant i una raó concreta —escalat o equip independent—, no com a exercici d'estil.

I una recomanació sobre el mètode: per a qualsevol de les set, comença per escriure la prova del comportament que vols, segueix per la migració si toca l'esquema, i deixa el controlador per al final. És l'ordre que menys codi llença a les escombraries.

Creure que el diagrama és l'arquitectura. El diagrama de l'apartat 1 és una vista; l'arquitectura real és el que fan les dependències del codi. Per això existeixen les regles d'ArchUnit: són l'únic diagrama que no pot mentir.

Copiar el pom.xml sencer a un projecte nou. Porta Redis, ShedLock, Resilience4j i Testcontainers a un projecte que potser no els necessita, i cada dependència és superfície de manteniment i de vulnerabilitats. Comença per web, data-jpa i test, i afegeix quan alguna cosa faci mal.

Aixecar l'observabilitat sencera en local sempre. Prometheus, Grafana, Loki, Tempo i el Collector consumeixen memòria i temps d'arrencada. En el dia a dia n'hi ha prou amb l'aplicació i PostgreSQL; la pila completa s'aixeca quan s'està treballant en observabilitat.

Oblidar que el .env no és al repositori. És el primer que trenca qui clona el projecte per primera vegada. Un .env.exemple versionat amb les claus i sense els valors estalvia aquesta mitja hora a cada persona nova.

Consell: recorre l'apartat 3 amb un depurador. Posar un punt d'interrupció a LloguerService.iniciar i pujar per la pila de crides fins al filtre és l'exercici que més consolida tot el curs: es veuen, en una sola pantalla, el proxy, la transacció, el SecurityContext i el MDC.

Consell: guarda el registre de decisions. La taula de l'apartat 5 —decisió, alternativa, motiu, contrapartida— és el document que més s'agraeix d'aquí a un any, i l'únic que respon a «per què està fet així?».

Consell: mesura abans d'estendre. Qualsevol de les set extensions de l'apartat 11 canvia el perfil de càrrega. Guarda la línia base de k6 d'avui: serà la referència per saber si l'extensió ha costat alguna cosa.

En producció, a les 09:12, l'app mòbil comença a rebre 500 a POST /api/v1/lloguers. El cos de l'error és un ProblemDetail amb "codi": "ERROR_INTERN" i un rastreId. Descriu, pas a pas i amb les eines concretes del projecte, com investigaries l'incident des d'aquest rastreId fins a la causa arrel, indicant quina peça de quin mòdul faries servir a cada pas i què descartaries amb cadascuna.

Dissenya l'extensió número 4 de l'apartat 11: un ciutadà pot reservar una bicicleta concreta durant 10 minuts abans de recollir-la; passat aquest temps, la reserva caduca i la bicicleta torna a estar disponible. Especifica el canvi al model, la migració, el contracte de l'API, el control de concurrència, la tasca de caducitat, les regles de seguretat, les mètriques i les proves que escriuries.

L'ajuntament d'una ciutat veïna vol reutilitzar CicloUrbana. Els seus números: 40 estacions (davant de 4), 300.000 lloguers al mes, dos equips de desenvolupament i un requisit nou —integració en temps real amb el sistema de transport públic—. Analitza quines decisions de l'apartat 5 continuarien sent correctes, quines caldria revisar i en quin ordre abordaries l'adaptació.

Solució 1

Pas 1 — de l'alerta al quadre de comandament (09-04). Abans de tocar el rastreId, mirar la fila RED del tauler: és un pic d'errors o un degoteig? va començar amb el desplegament de les 09:05? Amb això es distingeix una fallada sistemàtica d'una de puntual, i es decideix si cal revertir ja.

Pas 2 — el log d'aquella petició exacta (09-05). A Loki: {app="ciclourbana", entorn="prod"} | json | rastreId = "...". Retorna la història completa de la petició, inclosa la traça de pila que no se li va enviar al client. La majoria dels incidents es tanquen aquí, amb el nom de l'excepció i la línia.

Pas 3 — la cascada de spans (09-06). A Tempo, la mateixa traça. Aquí es respon una cosa que el log no diu: on se'n va anar el temps i què va fallar. Una barra vermella al span de la passarel·la descarta que el problema sigui nostre; vint spans select idèntics delaten un N+1 nou; un forat de 900 ms sense instrumentar apunta a espera de connexió o a una pausa de GC.

Pas 4 — descartar recursos (09-03). hikaricp.connections.pending, jvm.gc.pause i resilience4j.circuitbreaker.state a l'instant de la fallada. Si pending és a 60, el problema no és la lògica: alguna cosa reté connexions —una crida HTTP dins d'una transacció és el sospitós número u—.

Pas 5 — reproduir (06-05). Amb la causa identificada, escriure la prova que la reprodueix abans d'arreglar res. Si la fallada depèn de dades reals, una *IT amb Testcontainers i l'estat exacte que la provoca.

Pas 6 — decidir (08-05). Si la fallada va arribar amb el desplegament de les 09:05, revertir primer i diagnosticar després: el temps de restauració és una mètrica DORA i la reversió és una ordre. Si és un problema extern, la decisió és de negoci —degradar, obrir el tallacircuits, esperar—, com en el cas pràctic de 09-06.

El que l'exercici ensenya: el recorregut va del general al particular i del barat al car. La mètrica costa una llambregada, la traça un clic, el log una consulta, i el depurador mig matí. Començar pel depurador és l'error més comú.

Solució 2

Model. EstatBicicleta guanya el valor RESERVADA. Apareix l'entitat Reserva(id, usuari, bicicleta, estacio, creada, expira, estat) amb EstatReserva { ACTIVA, CONSUMIDA, CADUCADA, CANCELLADA }. La reserva és un agregat propi i no un camp de Bicicleta, perquè té cicle de vida, històric i regles pròpies.

Migració V10__reserves.sql. Taula amb seqüència (allocationSize = 50, mai IDENTITY, pels lots de 09-01), claus foranes a usuaris, bicicletes i estacions, columnes d'auditoria, CHECK sobre l'estat, índex (expira) WHERE estat = 'ACTIVA' —parcial, unes desenes de files davant de milions— i un índex únic parcial que impedeix dues reserves actives del mateix usuari, la mateixa tècnica de l'uk_lloguers_usuari_en_curs. L'enum de la columna estat de bicicletes amplia el seu CHECK: canvi compatible cap enrere.

Contracte. POST /api/v1/reserves amb { "bicicletaId": 12 } retorna 201 amb Location i ReservaResponse(id, matricula, estacio, expira, segonsRestants). DELETE /api/v1/reserves/{id} cancel·la (204). I POST /api/v1/lloguers accepta opcionalment reservaId: si ve, consumeix la reserva en lloc de cercar bicicleta.

Concurrència. És el punt delicat. SELECT … FOR UPDATE sobre la bicicleta amb timeout de 3 s, comprovació que continua DISPONIBLE, i canvi a RESERVADA a la mateixa transacció. Sense bloqueig, dos ciutadans reserven la mateixa bicicleta i un s'emporta un 409 innecessari quan el sistema li podria haver ofert una altra.

Caducitat. CaducadorReserves, germà de CaducadorLloguers: @Scheduled(fixedDelayString = "${ciclourbana.reserves.caducador.interval:PT30S}") amb @SchedulerLock —tres rèpliques, una execució—, lògica en un mètode públic invocable per poder provar-la, Clock injectat i idempotència: marcar com a caducada una reserva ja caducada no canvia res.

Seguretat. @PreAuthorize("isAuthenticated()") per crear; @PreAuthorize("hasAnyRole('OPERARI','ADMIN') or @seguretatReserves.esPropietari(#idReserva, principal)") per cancel·lar i consultar, amb un bean nou idèntic en forma a SeguretatLloguers. El llistat filtra a la consulta, mai amb @PostFilter.

Mètriques. Un Counter ciclourbana.reserves.creades{estacio} i un altre ciclourbana.reserves.caducades, amb l'etiqueta d'estació —quatre valors— i mai l'identificador d'usuari. La taxa de caducitat és l'indicador de negoci interessant: si és alta, la finestra de 10 minuts és massa curta o massa llarga.

Proves. Unitària de Reserva.caducar() amb Clock.fixed i del cas límit dels 10 minuts exactes; @DataJpaTest de l'índex únic parcial —dues reserves actives del mateix usuari han de violar la restricció—; llesca de seguretat amb dos ciutadans creuant identificadors; i una *IT del flux complet reservar → llogar → finalitzar, més una altra de reservar → esperar → comprovar que ha caducat, amb el rellotge controlat.

La decisió de disseny que cal saber defensar: la reserva és un agregat propi. Modelar-la com dos camps a Bicicleta sembla més barat i fa impossible l'històric, complica la caducitat i fica estat transitori en una entitat que hauria de ser estable.

Solució 3

El que continua sent correcte sense discussió. Flyway, DTOs, denegació per defecte, @Transactional al servei, Testcontainers, logs estructurats i observabilitat: són decisions el benefici de les quals creix amb la mida, no decreix. MapStruct passa d'opcional a clarament rendible, perquè el nombre de DTOs es multiplica.

El que cal revisar, amb el seu motiu.

L'ordre de l'adaptació, que és el que l'exercici pregunta de debò:

1. Mesurar amb les dades noves abans de tocar res. Carregar 40 estacions i 300.000 lloguers a pre i executar l'escenari de k6. Gairebé totes les decisions anteriors es resolen amb dades, no amb opinions.
2. Índexs i consultes. El que es degrada amb el volum es degrada primer, i és el més barat d'arreglar.
3. Fronteres de mòdul abans que equips. Amb dos equips, el conflicte no és tècnic sinó de propietat del codi: regles d'ArchUnit per mòdul i fronteres explícites abans de repartir la feina.
4. Memòria cau distribuïda i pool redimensionat, amb la prova de càrrega com a jutge.
5. La integració de transport públic, l'última, perquè introdueix una tecnologia nova —missatgeria— i convé fer-ho sobre una base ja estable i mesurada.

El que no faria: dividir en microserveis des del principi «perquè ara és més gran». Quaranta estacions i set lloguers per minut no són un problema d'escala: són un problema d'organització, i aquest es resol amb fronteres internes abans que amb processos separats.

CicloUrbana està completa i, per primera vegada, l'has vista sencera. Tens l'arquitectura final en un diagrama que es llegeix: un sol desplegable amb mòduls interns, dependències que apunten sempre cap endins, l'observabilitat com a lateral i no com a capa, i una única dependència capaç de tombar el servei —PostgreSQL—, cosa que explica per què la sonda readiness la consulta i la de liveness no. Tens l'estructura real del repositori, amb els paquets per funcionalitat, l'arbre de proves com a mirall del de producció, la separació *Test/*IT i tot el que envolta el codi: Dockerfile, docker-compose, helm/, .github/workflows, observabilitat/ i carrega/.

I tens el viatge d'una petició explicat en vint-i-un passos, del balancejador a la mètrica, amb la lliçó de cadascun. Aquest recorregut és el millor resum del curs perquè hi apareix tot: el filtre que obre el span, el JWT que es valida, el binding i la validació del DTO, el proxy que avalua el permís i obre la transacció al mateix punt —d'aquí que l'autoinvocació se'ls endugui tots dos per davant—, el bloqueig pessimista sobre l'última bicicleta de «Plaça Major», el mapatge dins de la transacció que fa possible open-in-view: false, l'AFTER_COMMIT que treu el cobrament del fil HTTP i la mètrica de negoci que tanca el cicle.

Tens també el mapa de què va construir cada mòdul, el pom.xml final on es veu quines versions gestiona el BOM i quines cal revisar a mà, la configuració consolidada amb la taula de l'única cosa que canvia entre entorns, les ordres per posar el projecte en marxa des de zero i la col·lecció .http que recorre registre, login, consulta, lloguer, factura i la comprovació que un ciutadà no pot llegir el lloguer d'un altre —seguida de les tres consultes que demostren que la mètrica, el log i la traça estan units pel mateix rastreId—.

I tens les dues peces que separen un projecte de curs d'un producte: la taula de decisions amb les seves contrapartides, que és el document que respon d'aquí a un any a «per què està fet així?», i la llista de comprovació final amb els seus quinze punts, inclòs el que cap lliçó no havia esmentat —una còpia de seguretat que mai no s'ha restaurat no és una còpia de seguretat— i el que es repeteix des del mòdul 5: això és un punt de partida didàctic i necessita revisió professional abans d'exposar-se a Internet.

El projecte no s'acaba aquí, i aquesta és la idea. Les set extensions de l'apartat 11 estan ordenades per dificultat i cadascuna et diu quines lliçons combinar, des de l'informe amb exportació fins a extreure la facturació a un servei propi —l'última de la llista, i amb motiu—. Construir qualsevol d'elles sobre aquesta base és la millor manera de convertir el que has après en alguna cosa teva.

Queda una última lliçó, i és l'única del curs que no parla de CicloUrbana. Perquè saber Spring Boot no és haver acabat un curs: és haver començat a poder llegir la documentació amb criteri, distingir un recurs actualitzat d'un que confon, planificar una actualització de versió major sense por i triar què aprendre després entre vint camins possibles. Recursos per a Aprenentatge Addicional s'ocupa d'això: la documentació oficial i com llegir-la, el codi font com la millor font, com mantenir-se al dia amb el cicle de publicació de Spring, l'ecosistema Java, els llibres que de debò valen la pena, les certificacions amb una valoració honesta, la comunitat, la pràctica deliberada, els temes naturals per al pas següent i un full de ruta raonat per als propers sis mesos.