La lliçó anterior va deixar una promesa sense complir: vam dir que un servei en crida un altre, que cal propagar el JWT i l'identificador de rastre, que fa falta un tallacircuits i que la caiguda d'un servei no s'ha d'encadenar. Res d'això no ho hem escrit encara. I fa falta encara que CicloUrbana no es divideixi mai: tan bon punt l'aplicació crida la passarel·la de pagaments de Ribalta —un sistema extern, amb la seva latència, les seves caigudes i els seus errors 500— apareixen exactament els mateixos problemes.

Aquesta lliçó els resol amb codi. Primer el client: quines opcions ofereix Spring, com es configura RestClient per parlar amb la passarel·la, per què els temps d'espera són l'ajust més car d'oblidar, com es propaguen el rastre i el token, i com es tradueix un error remot a una excepció del domini. Després la resiliència: els cinc patrons de Resilience4j un a un, en quin ordre s'apliquen, i la decisió —de negoci, no tècnica— de què fa CicloUrbana quan la passarel·la no respon. I al final, com es prova tot això simulant un servei lent, caigut i trencat.

1. Els clients HTTP d'Spring
2. El client de la passarel·la de pagaments
3. Temps d'espera: l'ajust que no es pot oblidar
4. Interceptors: propagar el rastre i el token
5. Traduir els errors remots al domini
6. La interfície declarativa amb @HttpExchange
7. Resilience4j: instal·lació i configuració
8. Reintents
9. Tallacircuits
10. Limitador de taxa, mampara i temps límit
11. L'ordre dels decoradors
12. Degradació elegant
13. Observabilitat de la resiliència
14. Provar les fallades amb WireMock
15. Comunicació asíncrona: el mínim imprescindible
16. Errors Comuns i Consells
17. Exercicis

Dos aclariments útils. RestTemplate no està obsolet ni desapareixerà, però no rep funcionalitat nova; migrar a RestClient és gairebé mecànic perquè comparteix la infraestructura (ClientHttpRequestFactory, interceptors, convertidors). I fer servir WebClient en una aplicació servlet només per cridar un servei i fer .block() és un antipatró comú: arrossega tota la pila reactiva per obtenir el comportament de RestClient amb més complexitat. L'elecció per a CicloUrbana: RestClient com a base i @HttpExchange per exposar-lo com a interfície de domini.

Partim de la PassarelaProperties de 02-05, ampliada amb els temps d'espera:

Quatre decisions. És un bean, no un RestClient creat a cada crida: crear-lo per invocació descarta el pool de connexions i afegeix una negociació TLS completa a cada petició. La clau de l'API va com a capçalera per defecte, així que cap mètode no la pot oblidar —i mai a la URL, on acabaria als logs d'accés i als proxies intermedis—. L'User-Agent identifica CicloUrbana als logs de la passarel·la, cosa que estalvia discussions quan cal investigar un incident amb el proveïdor. I hi ha un client per destinació: si demà apareix un servei de mapes, tindrà el seu propi bean amb els seus propis temps i el seu propi tallacircuits.

No configurar els temps d'espera és l'error més car de tota la lliçó, i és fàcil de cometre perquè no produeix cap símptoma fins al dia que el sistema remot es degrada.

Sense ells, una petició a una passarel·la que accepta la connexió i no respon mai espera indefinidament, i el fil que atén el ciutadà queda bloquejat. Amb dos-cents ciutadans intentant pagar, els dos-cents fils de Tomcat queden retinguts, i a partir d'aquí CicloUrbana sencera deixa de respondre: ni consultar estacions, ni iniciar lloguers, ni tan sols /actuator/health si comparteix port. Un problema d'un tercer s'ha convertit en una caiguda total del servei municipal.

La regla per fixar-los: parteix del pressupost de latència del teu propi endpoint. Si POST /api/v1/lloguers/{id}/finalitzar ha de respondre en menys d'un segon, no es pot permetre una espera de lectura de trenta; és més útil fallar ràpid i degradar (apartat 12) que esperar una resposta que ja no serveix a ningú. I un advertiment sobre els reintents: l'espera efectiva es multiplica —amb una lectura de 5 s i tres intents, el pitjor cas són 15 s més les pauses—, que és per això que l'apartat 11 insisteix en l'ordre dels decoradors i en un límit global.

Un interceptor s'executa abans de cada petició sortint i és el lloc natural per a les capçaleres transversals:

Amb aquesta capçalera, l'identificador de rastre del FiltreRastreig de 03-06 viatja al sistema remot i apareix als seus logs: quan el proveïdor de la passarel·la pregunti per una transacció concreta, la referència és la mateixa a banda i banda. A 09-06, Micrometer Tracing farà això de manera estàndard amb les capçaleres traceparent del W3C. Per propagar el JWT cap a un altre servei de CicloUrbana —el token relay de 07-05— l'interceptor llegeix el context de seguretat:

Mai cap a un tercer: aquest interceptor només s'ha de registrar en clients que apunten a serveis propis; enviar el token d'un ciutadà de Ribalta a la passarel·la de pagaments externa seria una filtració de credencials, i per això la passarel·la fa servir la seva pròpia apiKey. I el SecurityContextHolder és un ThreadLocal: si la crida surt d'un fil asíncron (07-03), aquí no hi haurà res tret que l'executor estigui embolcallat en DelegatingSecurityContextAsyncTaskExecutor.

Sense tractament, un 402 Payment Required de la passarel·la es converteix en una HttpClientErrorException que puja fins al GestorGlobalExcepcions de 03-06, que la desconeix i retorna un 500 genèric. Al ciutadà li arriba «error intern» quan el que passa és que la seva targeta no té saldo.

I al gestor global, tres regles noves coherents amb el ProblemDetail de 03-06:

Dos principis darrere d'aquesta taula. L'excepció de transport no ha d'escapar: que el client faci servir RestClient, Feign o un sòcol pelat és un detall d'implementació, i HttpClientErrorException a la signatura d'un servei de domini acobla l'aplicació a la biblioteca. I el codi d'estat cap al ciutadà no és el del remot: que la passarel·la retorni 400 perquè vam enviar un camp malament no significa que la petició del ciutadà fos incorrecta.

Compte, a més, amb allò que es registra: el cos de la resposta d'una passarel·la de pagaments pot contenir dades de targeta, així que mai no s'ha d'abocar sencer al log ni, molt menys, al missatge de l'excepció que arriba al client.

Amb més de dues o tres operacions, el RestClient nu dispersa URI i tipus pel codi. La interfície declarativa els reuneix en un contracte llegible:

Spring genera la implementació, que fa servir per sota el RestClient de l'apartat 2 amb els seus temps d'espera, els seus interceptors i el seu traductor d'errors. Els avantatges davant del client nu: la interfície és el contracte i es llegeix d'un cop d'ull, el servei de domini depèn d'una abstracció pròpia i no d'una biblioteca HTTP, i a les proves se substitueix per un mock de Mockito (06-03) sense aixecar res.

@HttpExchange és l'equivalent estàndard d'OpenFeign sense dependre d'Spring Cloud, amb una correspondència gairebé un a un (@FeignClient → @HttpExchange, @GetMapping → @GetExchange).

spring-boot-starter-aop no és opcional: les anotacions de Resilience4j funcionen amb proxies, amb els mateixos paranys d'autoinvocació de @Transactional (04-07) i @Async (07-03) —un mètode anotat que es crida amb this. no està protegit per res—. Tota la configuració és YAML, amb configs.default heretable més ajustos per instància:

ignoreExceptions amb PagamentRebutjatException és la línia més important de tot el bloc. Una targeta sense saldo és una resposta correcta de la passarel·la: no s'ha de reintentar ni comptar com a fallada per obrir el tallacircuits. Si es comptés, mil ciutadans amb la targeta caducada bastarien per deixar sense cobraments tota la xarxa de Ribalta.

Un reintent resol fallades transitòries: una pèrdua de paquets, un 503 durant un desplegament del proveïdor, un pic momentani.

Dos conceptes que cal entendre.

Retrocés exponencial amb jitter. Reintentar cada 500 ms de manera fixa té un efecte pervers: si mil peticions fallen alhora perquè la passarel·la s'ha reiniciat, les mil reintenten alhora i la tomben de nou —la tempesta de reintents—. El retrocés exponencial separa els intents (500 ms, 1 s, 2 s) i el jitter (enableRandomizedWait) hi afegeix variació aleatòria: amb randomizedWaitFactor: 0.5, la segona espera cau entre 250 i 750 ms.

Idempotència: què és segur reintentar. Aquesta és la regla que decideix si el reintent ajuda o duplica cobraments, i enllaça amb la semàntica dels mètodes HTTP de 03-03:

El cas perillós és un temps d'espera exhaurit: no se sap si l'operació es va executar o no —la resposta es va perdre, però el cobrament es va poder aplicar—. La solució és la clau d'idempotència: CicloUrbana envia a cada cobrament una clau derivada del lloguer (cobrament-lloguer-42) i la passarel·la, si ja l'ha vista, retorna el resultat original sense tornar a cobrar. Sense aquest mecanisme del costat servidor, reintentar un POST de cobrament és inacceptable.

El reintent serveix per a fallades passatgeres. Quan la fallada és sostinguda, reintentar empitjora les coses: consumeix fils, allarga les respostes i masega un sistema que ja és caigut. El tallacircuits talla aquesta realimentació.

L'estat OBERT és el que aporta el valor: es llança CallNotPermittedException immediatament, de manera que es deixa d'esperar cinc segons per cada petició i es falla en microsegons, sense tocar el sistema caigut.

Quatre regles sobre el fallbackMethod, totes font d'errors freqüents:

1. Mateixa signatura més un últim paràmetre Throwable. Si no coincideix, Resilience4j no el troba i l'excepció original s'escapa, en silenci, en temps d'execució.
2. Ha de ser a la mateixa classe i pot ser private.
3. Poden ser-ne diversos, especialitzats per tipus d'excepció; guanya el més específic.
4. No ha de fallar ni ser lent. Una reserva que crida un altre servei remot reintrodueix el problema que venia a resoldre.

Els dos llindars. failureRateThreshold: 50 obre el circuit amb la meitat de fallades, però slowCallRateThreshold: 80 amb slowCallDurationThreshold: 3s és igual d'important —un servei lent fa més mal que un de caigut, perquè reté fils sense retornar res—, i minimumNumberOfCalls: 10 evita que dues fallades en un moment de baix trànsit obrin el circuit.

@RateLimiter protegeix de superar una quota: la passarel·la de Ribalta admet 50 peticions per segon i sobrepassar-les produeix 429 i, en alguns contractes, un recàrrec. Amb timeoutDuration: 200ms, una crida que no obté permís en aquest termini llança RequestNotPermitted. És diferent del Bucket4j de 05-05: aquell limitava allò que entra a CicloUrbana; aquest limita allò que surt cap al tercer.

@Bulkhead —mampara, pels compartiments estancs d'un vaixell— limita les crides concurrents a un recurs: amb @Bulkhead(name = "passarelaPagaments", type = Bulkhead.Type.SEMAPHORE) i maxConcurrentCalls: 10, com a molt deu fils esperen la passarel·la alhora; la resta falla ràpid en lloc d'acumular-se. És el que impedeix que un tercer lent exhaureixi el pool de Tomcat: sense mampara, dues-centes peticions concurrents a un servei de cinc segons retenen els dos-cents fils i tomben CicloUrbana sencera. És el mateix principi que vam aplicar a 07-03 en donar un executor propi al correu.

@TimeLimiter imposa un topall global, i només funciona sobre mètodes que retornen CompletableFuture, perquè necessita poder cancel·lar:

En una aplicació bloquejant com CicloUrbana els temps d'espera del RestClient (apartat 3) cobreixen el cas habitual; @TimeLimiter aporta el topall de l'operació completa, inclosos els reintents i les seves pauses, que és justament el que les esperes individuals no acoten.

Quan diverses anotacions s'apliquen al mateix mètode, l'ordre importa molt. El que aplica Resilience4j per defecte, de fora cap a dins:

Es llegeix així: primer es demana lloc a la mampara; a dins, el temps límit acota tota l'operació; després el limitador concedeix permís; llavors el tallacircuits decideix si s'intenta tan sols; i el reintent queda a l'interior, embolcallant únicament la crida real. Que Retry sigui dins de CircuitBreaker és la decisió clau:

L'ordre per defecte és el correcte en gairebé tots els casos, i es pot canviar amb les propietats ...retryAspectOrder i ...circuitBreakerAspectOrder si calgués.

Arriba la pregunta central de la lliçó: què fa CicloUrbana quan la passarel·la de pagaments no respon?

La decisió de CicloUrbana és la segona: finalitzar el lloguer i diferir el cobrament, que és el que fa el cobramentDiferit de l'apartat 9. El raonament és de negoci, no tècnic: el ciutadà ja va tornar la bicicleta —això és un fet físic que va passar— i bloquejar l'operació no ho desfà, només deixa un ancoratge inutilitzat i un ciutadà atrapat. L'import és petit, la identitat del ciutadà és coneguda i el cobrament es pot reintentar més tard amb una tasca programada (07-03) sobre els CobramentPendent encuats.

I aquesta decisió no la pren el desenvolupador: canviaria del tot si l'import fos de mil euros, si el ciutadà fos anònim o si la normativa exigís cobrament previ. La regla general és que la reserva és una decisió de producte i el codi només la implementa, i les preguntes que cal portar a aquesta conversa són sempre les mateixes: podem servir dades una mica antigues?, acceptar l'operació i completar-la després?, oferir una funcionalitat reduïda?, o aquesta operació és realment indispensable?

Un catàleg de degradacions típiques: servir l'última resposta a la memòria cau (09-02) quan la dada tolera antiguitat; retornar un valor per defecte segur; encuar i confirmar, com aquí; o deshabilitar la funcionalitat mantenint la resta.

Un tallacircuits que s'obre sense que ningú se n'assabenti és tan dolent com no tenir-lo: el sistema degrada en silenci. Amb registerHealthIndicator: true, cada circuit apareix com a component de salut a /actuator/health (07-01), i Resilience4j afegeix els seus propis endpoints:

Compte amb l'indicador de salut. Si el circuit de la passarel·la entra al grup readiness, obrir-se trauria la instància del balancejador —justament l'escenari que vam advertir a 07-01—. Un tallacircuits obert significa «el tercer és caigut i estic degradant correctament», no «estic malalt»: s'ha de veure a /actuator/health i disparar una alerta, però no ser a readiness.

Les mètriques que Resilience4j publica a Micrometer —resilience4j_circuitbreaker_state, ..._calls, resilience4j_retry_calls— s'exploten a 09-03 i es representen a Grafana a 09-04, amb dues alertes mínimes: circuit obert més d'un minut i taxa de reintents per damunt del normal, que és l'avís primerenc d'una degradació abans que el circuit arribi a obrir-se.

Tot l'anterior només serveix si està provat, i no es pot provar demanant al proveïdor que caigui. WireMock aixeca un servidor HTTP que fingeix ser la passarel·la i es comporta com se li indiqui (dependència org.wiremock:wiremock-standalone, àmbit test).

Els asserts que donen valor a aquestes proves són els que no miren el resultat feliç: verify(0, ...) amb el circuit obert demostra que no va sortir ni una petició, que és l'essència del patró, i la comprovació de temps demostra que un tercer que triga trenta segons no arrossega CicloUrbana. Per al reintent, WireMock ofereix escenaris amb estat (inScenario(...).whenScenarioStateIs(STARTED)...willSetStateTo(...)), que permeten simular «falla una vegada i després funciona» i comprovar-ho amb verify(2, ...); l'exercici 2 ho desenvolupa.

Dos detalls imprescindibles: reiniciar el tallacircuits entre proves, perquè el seu estat és global al context i una prova deixaria el circuit obert per a la següent; i abaixar els llindars a application-test.yml (minimumNumberOfCalls: 5, waitDurationInOpenState: 1s) perquè la suite duri segons i no minuts. L'alternativa a WireMock és MockServer sobre Testcontainers, reprenent 06-05, útil quan es vol el mateix enfocament de contenidors de la resta de la suite.

Quan la resposta no fa falta per continuar (07-05), la missatgeria converteix una caiguda en un retard. Amb spring-kafka —o spring-boot-starter-amqp per a RabbitMQ—, publicar i consumir són unes poques línies:

La publicació és simètrica —kafka.send("ciclourbana.lloguers", String.valueOf(esdeveniment.lloguerId()), esdeveniment)— amb el lloguerId com a clau de partició perquè els esdeveniments d'un mateix lloguer conservin l'ordre.

La cua de missatges fallits mereix un paràgraf. Sense ella, un missatge que sempre falla —un esdeveniment amb un camp corrupte— es reintenta indefinidament i bloqueja tota la partició: cap missatge posterior no es processa. Amb ella, el missatge problemàtic s'aparta a un tema .DLT per a revisió manual i el flux continua. I aquest tema cal vigilar-lo: una cua de fallits que ningú no mira és una carpeta de correu que ningú no obre.

No configurar els temps d'espera. L'error més car: un tercer lent exhaureix els fils i tomba CicloUrbana sencera.

Crear un client HTTP a cada crida. Es perd el pool de connexions i cada petició paga una negociació TLS completa.

Reintentar un POST no idempotent. Un temps d'espera exhaurit no significa que l'operació no s'executés: es cobra dues vegades.

Comptar els errors de negoci com a fallades del circuit. Mil targetes sense saldo obririen el tallacircuits i deixarien sense cobraments tota la xarxa. ignoreExceptions.

Signatura del fallbackMethod incorrecta. Resilience4j no el troba i l'excepció original s'escapa, sense cap error en compilació.

Una reserva que crida un altre servei remot. Reintrodueix exactament el problema que venia a resoldre.

Deixar escapar l'excepció del transport. HttpClientErrorException en un servei de domini acobla l'aplicació a la biblioteca HTTP.

Propagar el JWT del ciutadà a un tercer. És una filtració de credencials: cap enfora va la clau del sistema, no la de l'usuari.

Posar el tallacircuits al grup readiness. Obrir-se significa que el tercer és caigut, no que la instància estigui malalta.

Consell: un client, un tallacircuits i una mampara per destinació, perquè compartir-los fa que un tercer lent afecti crides que no hi tenen res a veure; i fixa els temps des del pressupost de latència del teu endpoint, no des del que sol trigar el remot.

Consell: prova les fallades, no només el camí feliç. Un tallacircuits que no s'ha vist obrir mai en una prova és una hipòtesi, no una protecció.

servei-lloguers necessita consultar a servei-estacions si la bicicleta RB-0142 està disponible abans d'iniciar un lloguer. Dissenya el client complet: interfície @HttpExchange, RestClient amb temps d'espera i propagació del JWT, configuració de Resilience4j i reserva. La consulta és de només lectura i l'endpoint de lloguer ha de respondre en menys d'un segon. Justifica cada valor i decideix què ha de passar si estacions no respon.

Escriu les proves amb WireMock que demostrin, per al client de l'exercici anterior: que un 503 puntual es reintenta i acaba funcionant; que després de fallades sostingudes el circuit obre i deixa de sortir trànsit; que una resposta que triga 20 segons no bloqueja el ciutadà; i que un 404 (bicicleta inexistent) no compta com a fallada del circuit. Indica la configuració d'application-test.yml necessària.

Troba tots els problemes d'aquest codi i reescriu-lo.

Solució 1

Justificació de cada valor. El pressupost és d'un segon per a tot l'endpoint, i aquesta consulta només n'és una part: d'aquí 300 ms de connexió i 600 de lectura, amb dos intents com a màxim i 100 ms de pausa, cosa que acota el pitjor cas en uns 1,6 s abans que actuï la reserva —ja fora de pressupost, i per això el circuit és agressiu—. slowCallDurationThreshold: 500ms és baix a propòsit: al camí crític, lent equival a trencat. waitDurationInOpenState: 15s és curt perquè és un servei propi que es recupera de pressa després d'un desplegament. ignoreExceptions amb la bicicleta inexistent evita que un 404 legítim compti com a fallada. I la mampara de 30 crides concurrents protegeix el pool de Tomcat.

Què passa si estacions no respon, i per què. Aquí la decisió és la contrària a la dels pagaments: es denega el lloguer amb un 503. La diferència és que el cobrament diferit tenia compensació possible —es cobra més tard— mentre que iniciar un lloguer sense saber si la bicicleta està disponible no en té: dos ciutadans es podrien endur la mateixa bicicleta, o algú llogar-ne una que és al taller. Quan la informació que falta és la que fa correcta l'operació, la degradació correcta és rebutjar. És la mateixa pregunta de l'apartat 12 amb resposta diferent, i per això es decideix cas a cas.

Solució 2

Comentaris. La primera fa servir escenaris amb estat de WireMock, l'única manera de simular «falla una vegada i després funciona», i el verify(2, ...) és el que prova el reintent; sense ell, la prova passaria igual sense cap reintent configurat. La segona conté l'assert més valuós de l'exercici: verify(0, ...) després de resetRequests() demostra que amb el circuit obert no surt ni una petició, que és precisament l'objectiu del patró. La tercera comprova que 20 segons de retard es tallen en menys de 3, cosa que prova que l'espera de lectura està configurada. I la quarta és la més subtil: verifica que un error de negoci no degrada el sistema; sense ignoreExceptions, sis consultes a una matrícula inexistent deixarien sense servei tota la xarxa de Ribalta.

Cada prova parteix d'estacions.resetAll() i registre.circuitBreaker("estacions").reset() en un @BeforeEach; sense això, l'ordre d'execució determinaria el resultat i la suite seria intermitent.

Solució 3

Nou problemes:

La versió corregida és la del cos de la lliçó: RestClient com a bean amb els temps de PassarelaProperties, la clau en una capçalera per defecte, la interfície @HttpExchange, el defaultStatusHandler que tradueix a PagamentRebutjatException / PassarelaNoDisponibleException, @CircuitBreaker + @Retry + @Bulkhead amb ignoreExceptions sobre els errors de negoci, la clau d'idempotència cobrament-lloguer-{id} a cada sol·licitud, i un cobramentDiferit(Long, BigDecimal, Throwable) que encua el cobrament i retorna ResultatCobrament.diferit() —mai null—.

El mòdul 7 acaba i CicloUrbana ha canviat de naturalesa. Va començar sent una aplicació correcta: ben construïda, ben provada i completament incapaç de viure fora del portàtil d'un desenvolupador. Acaba sent una aplicació operable. Actuator respon si és sana, quina versió s'executa i què està fallant, amb sondes de disponibilitat que un orquestrador entén. Els perfils fan que el mateix artefacte —el que va aprovar ./mvnw verify— serveixi per al portàtil i per al servidor de l'ajuntament sense recompilar-se, amb els secrets fora del repositori. Les tasques programades caduquen els lloguers oblidats de Ribalta i recalculen l'ocupació, coordinades entre instàncies; l'execució asíncrona envia el correu de confirmació sense fer esperar el ciutadà, amb el rastre i la identitat viatjant a l'altre fil. La imatge de contenidor empaqueta l'aplicació, el seu JRE i la seva zona horària en un artefacte reproduïble, amb capes que fan que reconstruir costi segons, un usuari sense privilegis i un docker-compose.yml on PostgreSQL i l'aplicació s'esperen per les seves comprovacions de salut. I aquesta última lliçó hi ha afegit la peça que faltava: CicloUrbana ja sap parlar amb el món exterior sense morir en l'intent —temps d'espera que acoten l'espera, reintents amb retrocés i jitter només allà on és segur reintentar, un tallacircuits que deixa d'insistir sobre allò que és caigut, mampares que impedeixen que un tercer lent exhaureixi els fils, i una degradació elegant que és una decisió de negoci, escrita en codi i demostrada amb proves que fingeixen la caiguda—. Sap a més quan té sentit dividir-se en microserveis i, encara més valuós, quan no. El que queda ja no és construir, sinó lliurar: la xarxa de Ribalta funciona, és observable, resisteix i està empaquetada, però continua vivint en màquines de desenvolupament. El mòdul 8, Desplegament d'Aplicacions Spring Boot, la posa per fi en mans dels ciutadans: què significa desplegar i què cal decidir abans de fer-ho, una primera plataforma senzilla amb Heroku, la infraestructura real a AWS, l'orquestració amb Kubernetes —on les sondes de 07-01 i la imatge de 07-04 encaixen per fi al seu lloc— i una canalització d'integració i lliurament continu que porti cada commit des del repositori fins a la ciutat sense que ningú toqui un servidor a mà.