Fa tres lliçons que assenyalem el mateix deute. A 03-02, un exercici va demostrar que exposar el record Estacio directament obliga a contaminar-lo amb anotacions de Jackson i a mantenir una fràgil llista d'exclusions. A 03-03 vam haver d'inventar NovaEstacio perquè el client no pot enviar l'id. A 03-04 la vam reanomenar a CrearEstacioRequest i li vam penjar les restriccions de validació. El projecte ja té dues representacions d'una estació convivint sense que ningú no hagi ordenat aquesta convivència. Aquesta lliçó l'ordena: separa el domini —el que CicloUrbana sap sobre la xarxa de Ribalta— del contracte —el que l'API promet als seus clients—, dissenya la jerarquia completa de DTO del projecte i compara les estratègies per traslladar dades d'una capa a una altra sense escriure codi repetitiu ni introduir errors silenciosos.

1. Per què no s'exposen les entitats del domini
2. Quatre fallades concretes, amb exemple
3. Tipus de DTO: petició i resposta
4. Per què record immutables
5. La jerarquia de DTO de CicloUrbana
6. Mapatge manual
7. MapStruct
8. ModelMapper i per què el curs el descarta
9. On viu el mapatge
10. Projeccions i respostes parcials
11. DTO imbricats i agregats
12. Evolucionar el contracte sense trencar clients
13. Errors Comuns i Consells
14. Exercicis

Un DTO (Data Transfer Object) és un objecte l'únic propòsit del qual és transportar dades a través d'una frontera. No té comportament, no té regles i no viu al domini: pertany al contracte.

La temptació de saltar-se'ls és forta. Retornar Estacio directament estalvia una classe, un mapatge i una línia al controlador. Multiplicat per vint endpoints, sembla molt estalvi. El que s'estalvia el primer mes es paga amb interessos a partir del tercer, per quatre motius:

L'argument de fons és de disseny: el model de domini i el contracte públic canvien per raons diferents i a ritmes diferents. El domini canvia quan canvia el negoci de Ribalta; el contracte canvia quan el negocies amb els equips client. Lligar-los fa que cada canvi d'un arrossegui l'altre.

Fallada 1: la fuita de dades. És la més greu i la més silenciosa. Suposa que al mòdul 5 hi afegim autenticació i el record Usuari(Long id, String nom, String correu, String hashContrasenya, String dni, LocalDate dataAlta) creix amb aquests dos últims camps sensibles. Si UsuariController retorna Usuari, la resposta de GET /api/v1/usuaris/1 inclou el hash de la contrasenya i el DNI d'un ciutadà de Ribalta. Ningú no ho ha decidit: ha passat perquè el mecanisme per defecte és publicar. Es pot tapar amb @JsonIgnore, però això és una llista d'exclusions, i les llistes d'exclusions fallen per omissió: el dia que s'afegeixi un camp i ningú no recordi anotar-lo, es publica. Un DTO és una llista d'inclusions: només surt el que enumeres, i oblidar-se'n produeix com a molt un camp que falta, detectable a l'instant.

Fallada 2: l'acoblament invisible. L'equip decideix que capacitat es digui placesTotals perquè és més clar al domini. És un refactor de dos segons a l'IDE. I trenca l'app mòbil de tots els ciutadans de Ribalta que ja la tenen instal·lada, perquè el JSON passa de "capacitat" a "placesTotals" sense que ningú no ho adverteixi.

Fallada 3: les referències circulars. Al mòdul 4, Estacio tindrà una llista de Bicicleta i cada Bicicleta una referència a la seva Estacio. En serialitzar, el recorregut Estacio 1 → bicicletes → Bicicleta 42 → estacio → Estacio 1 → ... produeix un StackOverflowError o una resposta de diversos megabytes. Es pot pedaçar amb @JsonManagedReference i @JsonBackReference, però això és ficar decisions de serialització dins del model de dades. Amb DTO el problema no existeix: EstacioDetallResponse conté BicicletaResum, i BicicletaResum no conté l'estació.

Fallada 4: l'evolució bloquejada. L'ajuntament demana que l'API exposi bicicletesDisponibles, una dada que no és a l'entitat perquè es calcula comptant bicicletes. Sense DTO hi ha dues males sortides: afegir un camp calculat a l'entitat de domini —contaminant-la amb necessitats de presentació— o retornar un Map sense tipus. Amb DTO és trivial: EstacioResponse té aquest camp i el mapejador l'omple.

Els DTO es divideixen en dues famílies amb regles diferents.

DTO de petició (request): el que el client envia. No duen identificadors generats pel servidor —l'id va a la ruta, no al cos—, no duen camps derivats —l'import d'un lloguer el calcula el servidor—, duen les restriccions de validació de 03-04 i són mínims: com menys camps accepti l'API, menys superfície d'atac.

DTO de resposta (response): el que el servidor retorna. No duen validació —ningú no valida el que un mateix genera—, sí que duen camps calculats (bicicletesDisponibles, esPlena), poden agregar dades de diverses fonts i solen existir en dues mides: resum per als llistats i detall per a la consulta individual.

Un error comú és fer servir el mateix DTO per a entrada i sortida. Sembla que estalvia codi i produeix dos problemes: la classe acaba amb camps que només tenen sentit en una direcció (un id que és nul en crear i obligatori en llegir), i les restriccions de validació s'apliquen a objectes que no les necessiten. Val la pena la classe extra.

Tots els DTO de CicloUrbana són record. Les raons, comparades amb l'alternativa clàssica d'una classe amb getters i setters:

La immutabilitat és el que més aporta. Un DTO mutable es pot modificar entre el moment en què es valida i el moment en què es fa servir, i això ha causat vulnerabilitats reals. Amb un record, el que s'ha validat és exactament el que arriba al servei.

El constructor compacte és a més el lloc natural per normalitzar, i s'executa sempre, vingui l'objecte d'on vingui:

Aquest trim evita que el nom "Plaça Major " es consideri diferent de "Plaça Major" a la comprovació de duplicats. És una neteja que en una classe amb setters s'hauria de repetir a cadascun.

Els DTO viuen al costat del seu agregat, en un subpaquet dto: com.ciclourbana.estacions conté Estacio, EstacioService, EstacioController i EstacioMapper, i com.ciclourbana.estacions.dto conté CrearEstacioRequest, ActualitzarEstacioRequest, EstacioResponse i EstacioDetallResponse.

Dues observacions sobre el disseny. ActualitzarEstacioRequest no inclou coordenades, i és deliberat: una estació física no es mou de lloc, i corregir-ne la georeferenciació seria una operació administrativa diferent. Els DTO de petició són la manera més neta d'expressar què es pot modificar i què no: el que no és al DTO, no es pot tocar. I LloguerResponse no inclou bicicletaId sinó matricula, perquè l'identificador intern no serveix a l'app mòbil, que vol mostrar "RB-0142" a l'usuari; un DTO pot substituir identificadors per dades llegibles i reduir així el nombre de crides del client.

Els DTO de resposta:

BicicletaResum no té referència a l'estació, i aquí rau la clau de per què els DTO eliminen d'arrel el problema de les referències circulars: la jerarquia de DTO és un arbre per construcció.

La manera més simple de mapejar és escriure el codi. Amb record, cap en un mètode:

L'inconvenient seriós és el segon: si EstacioResponse guanya un camp zona, el compilador sí que avisa perquè el constructor del record canvia d'aritat, però si el camp nou és del mateix tipus que un altre, un error d'ordre passa desapercebut. És exactament el que MapStruct elimina.

Una alternativa sense bean són els mètodes de fàbrica estàtics al DTO mateix: EstacioResponse.de(estacio, disponibles). És més compacte, però acobla el DTO al domini i impedeix injectar dependències al mapatge. CicloUrbana fa servir el mapejador com a @Component.

MapStruct és un processador d'anotacions que genera el codi de mapatge en temps de compilació. No fa servir reflexió, així que és tan ràpid com el codi manual, i com que el resultat és Java compilat, qualsevol incoherència és un error de compilació.

La configuració al pom.xml va al maven-compiler-plugin, al costat de Lombok si el fessis servir:

unmappedTargetPolicy=ERROR és l'opció que fa MapStruct valuós: si afegeixes un camp al DTO de resposta i no li dius d'on surt, el projecte no compila. És l'oblit silenciós del mapatge manual convertit en error de compilació.

El mapejador és una interfície:

En compilar amb ./mvnw compile, MapStruct escriu a target/generated-sources/annotations una classe EstacioMapperImpl:

Llegir el codi generat és el millor hàbit que pots adquirir amb MapStruct. Deixa de ser màgia: és exactament el codi que hauries escrit a mà, incloses les comprovacions de nul. I quan alguna cosa no mapeja com esperaves, la resposta és allà, en un fitxer Java llegible.

Per a les actualitzacions parcials, MapStruct ofereix @MappingTarget, que modifica un objecte existent en lloc de crear-ne un de nou. Amb record immutables no s'hi aplica directament, així que a CicloUrbana el PATCH continua amb el mètode default que ja hem escrit. Amb classes mutables seria:

NullValuePropertyMappingStrategy.IGNORE significa "si l'origen és nul, no toquis el destí": exactament la semàntica de PATCH que tanta feina ens va donar a 03-03.

ModelMapper fa el mapatge en temps d'execució mitjançant reflexió, deduint les correspondències pel nom. El seu atractiu és que no requereix escriure res:

Els riscos, que són la raó de descartar-lo:

El segon risc és el pitjor: amb el mode de coincidència laxa, ModelMapper pot aparellar estacio.nom amb resposta.nomOperari perquè comparteixen un prefix, i publicar una dada al camp equivocat sense cap avís.

La recomanació del curs: mapatge manual quan hi ha pocs DTO o la lògica de conversió és substancial —és el cas de CicloUrbana en aquest mòdul, i és el codi que apareix a les lliçons—; MapStruct tan bon punt el projecte creix, per la garantia en temps de compilació; i ModelMapper, mai en producció.

Tres posicions defensables:

La política de CicloUrbana: mapejador dedicat, invocat des del controlador. El servei parla el llenguatge del domini —EstacioService.crear(...) rep i retorna Estacio, no DTO—, de manera que quan al mòdul 7 arribi un consumidor de missatges podrà cridar-lo sense construir objectes de l'API. El controlador tradueix, que és el seu paper des de 03-02. I el mapejador concentra la conversió, es prova amb proves unitàries ràpides (mòdul 6) i no obliga a aixecar el context de Spring. El controlador queda així:

Observa un detall important: EstacioService.crear ara rep una Estacio, no un DTO. La signatura del servei ha deixat d'esmentar el contracte de l'API, que és justament l'objectiu.

I la resposta que veu el client:

Compara-la amb la de 03-02, que era l'abocament literal del record Estacio. Aquesta és una decisió de disseny: agrupa les coordenades, exposa una dada calculada i no revela ni un camp que no vulguem publicar.

De vegades el client només vol uns pocs camps. Un mapa de Ribalta amb 4 estacions no necessita les adreces ni la capacitat: en té prou amb el nom i les coordenades. Descarregar l'objecte complet és trànsit malgastat, i en un llistat de centenars d'elements importa.

Les tres estratègies:

CicloUrbana tria DTO específics per la seva claredat:

L'endpoint GET /api/v1/estacions/mapa retorna List<EstacioMapaResponse> i no arrossega ni adreces ni capacitats. La regla per no acabar amb quinze DTO per recurs: crea una vista nova només quan un client real la demana i la diferència de mida és significativa. Dues o tres vistes per recurs —resum, detall i potser una d'especialitzada— cobreixen gairebé tots els casos.

La selecció dinàmica de camps (?camps=id,nom) és temptadora i gairebé sempre un error en una API REST: trenca el tipatge, impossibilita documentar la resposta a OpenAPI, complica la memòria cau —cada combinació és una resposta diferent— i acaba sent un GraphQL casolà mal fet. Si el projecte necessita de veritat aquesta flexibilitat, la resposta és GraphQL, com vam veure a 03-01.

EstacioDetallResponse és un agregat: una resposta que combina dades de diverses fonts en una sola crida.

El benefici és concret: l'app de Ribalta obté tota la pantalla de detall amb una petició en lloc de dues. En una xarxa mòbil lenta, cada anada i tornada costa centenars de mil·lisegons.

El perill també és concret: agregar massa. Si EstacioDetallResponse inclogués a més els últims cent lloguers i l'històric d'incidències, la resposta pesaria megabytes i seria lenta per a tothom, inclosos els clients que només volien el nom. Els tres criteris per decidir si una dada s'imbrica són: el client la necessita gairebé sempre en aquesta pantalla? (les bicicletes ancorades, sí); té la mida acotada? (com a màxim hi ha capacitat bicicletes; els lloguers històrics creixen sense límit); i canvia al mateix ritme?, perquè ajuntar una dada que s'actualitza cada segon amb una altra que canvia cada mes impedeix desar el conjunt a la memòria cau.

Els lloguers fallen els tres criteris, així que no s'imbriquen: es consulten amb GET /api/v1/estacions/1/lloguers?pagina=0, paginats i sota demanda.

Els DTO són el que fa possible a la pràctica la política de versionatge de 03-01. Quatre escenaris reals:

Afegir un camp és compatible: s'afegeix a EstacioResponse, s'omple al mapejador i els clients antics l'ignoren gràcies a fail-on-unknown-properties: false. Reanomenar un camp del domini deixa d'afectar el contracte: si Estacio.capacitat passa a dir-se placesTotals, es canvia una línia del mapejador i el JSON continua dient "capacitat". Aquest és, en una frase, el retorn de tota la inversió d'aquesta lliçó.

Retirar un camp del contracte requereix transició: marcar-lo obsolet a la documentació (@Schema(deprecated = true), lliçó 03-07), mesurar quants clients el fan servir amb Actuator (mòdul 7) i retirar-lo a /api/v2 quan l'ús arribi a zero.

Canviar la forma d'un camp —les coordenades soltes passant a un objecte ubicacio— es resol amb duplicitat temporal:

Els tres camps conviuen, el canvi és compatible i el mapejador omple totes dues formes. Quan les mètriques diguin que ningú no llegeix latitud solta, es retira. Sense DTO això seria impossible sense duplicar l'entitat de domini.

Exposar l'entitat "només en aquest endpoint". L'excepció es converteix en norma. Al mòdul 4, aquest endpoint serà el que provoqui la LazyInitializationException.

Fer servir el mateix DTO per a petició i resposta. Acaba amb camps nuls en una direcció i validacions inútils en l'altra. En la mateixa línia, posar validació als DTO de resposta només afegeix soroll: no es valida el que un mateix genera.

Mapejar al servei. Lliga la lògica de negoci al contracte HTTP. Quan arribi un consumidor de cua haurà de construir DTO d'API per cridar el servei.

Acceptar l'id al cos d'un POST. L'identificador l'assigna el servidor. Si el DTO l'inclou, un client pot intentar fixar-lo.

Oblidar @Mapping a MapStruct sense unmappedTargetPolicy=ERROR. El camp es queda a nul silenciosament. Activa la política al pom.xml des del primer dia.

Imbricar col·leccions sense cota. EstacioDetallResponse amb tots els lloguers històrics creix sense límit. Aplica els tres criteris de l'apartat 11.

Consell: anomena els DTO pel seu ús, no per la seva forma. CrearEstacioRequest i EstacioDetallResponse diuen on es fan servir. EstacioDTO i EstacioDTO2 no diuen res.

Consell: prova el mapejador a part. Un EstacioMapperTest sense context de Spring corre en mil·lisegons i detecta a l'instant un camp mal col·locat. És la prova amb millor relació cost-benefici del projecte (mòdul 6).

LloguerController retorna encara el record Lloguer del domini, que exposa usuariId, bicicletaId i els identificadors d'estació en cru. Dissenya LloguerResponse pensant en el que l'app mòbil necessita mostrar a l'historial del ciutadà, i implementa LloguerMapper. Justifica quins camps del domini no surten i quins camps calculats hi afegeixes.

El tauler intern dels operaris de Ribalta necessita, per a cada bicicleta, la matrícula, la bateria, l'estat, el codiAncoratgeIntern i el nombre d'incidències obertes. Cap dels tres últims no ha d'aparèixer a l'API pública. Dissenya la solució i explica com evites que un canvi futur filtri dades internes a l'endpoint públic.

Converteix l'EstacioMapper manual de l'apartat 6 en una interfície MapStruct. Resol els tres casos difícils: el camp bicicletesDisponibles que no és al domini, l'agrupació de latitud i longitud a ubicacio, i els camps calculats ancoratgesLliures i esPlena.

Solució 1.

Què no surt i per què:

Camps calculats: duradaMinuts estalvia a cada client reimplementar el càlcul, i fer-ho al servidor garanteix que tots obtinguin el mateix número.

Advertiment de disseny: aquest mapejador consulta repositoris, i això el converteix en alguna cosa més que un mapejador. En un llistat de 100 lloguers provocaria 300 consultes —el problema N+1 del mòdul 4—. Les sortides són que el servei retorni un agregat amb els noms ja resolts, o que el repositori els porti en una sola consulta. Si el teu mapejador necessita el repositori, és senyal que el servei no està retornant prou.

Solució 2.

Amb rutes separades i mapejadors separats:

Com s'evita la fuita futura, que és el fons de l'exercici:

1. Són classes diferents, no una amb camps condicionals. Un if (esOperari) dins del mapejador acaba fallant el dia que algú inverteixi la condició o l'oblidi.
2. La @Schema d'OpenAPI (03-07) documenta cadascuna per separat, i una revisió de la documentació pública deixa veure de seguida si apareix un camp que no hi hauria de ser.
3. La prova de contracte és la xarxa de seguretat definitiva. Al mòdul 6 escriurem una prova que afirma exactament quines claus retorna GET /api/v1/bicicletes; si algú afegeix un camp intern a la resposta pública, la prova falla abans del desplegament.
4. No reutilitzar mai el DTO intern "perquè ho té tot". És la temptació que provoca totes les fuites.

Un antipatró habitual que convé descartar explícitament: fer servir @JsonView per servir dues vistes des d'una sola classe. Funciona, però deixa el camp perillós dins de l'objecte que es serialitza, depenent d'una anotació per no sortir. És de nou una llista d'exclusions. Dues classes són més codi i molt més segur.

Solució 3.

Les tres lliçons de l'exercici:

• Cas 1. Quan un valor no és a l'objecte d'origen, es passa com a paràmetre addicional del mètode. MapStruct l'aparella amb el component del destí pel nom, així que int bicicletesDisponibles omple el camp bicicletesDisponibles. Si els noms no coincidissin, caldria @Mapping(target = "...", source = "...").
• Cas 2. Un mètode default la signatura del qual va del tipus origen al tipus destí es converteix en un convertidor que MapStruct fa servir automàticament allà on necessiti aquesta transformació. És el mecanisme més útil i menys conegut de la llibreria.
• Cas 3. Quan un mapatge requereix lògica real, escriu-lo com a mètode default. MapStruct permet expressions inline amb @Mapping(target = "esPlena", expression = "java(...)"), però això fica codi Java dins d'una cadena de text: sense comprovació de tipus, sense autocompletat i sense refactorització. Un default és Java normal i corrent.

I la comprovació final, que és la raó d'haver migrat: si demà algú afegeix el camp zona a EstacioResponse i no diu d'on surt, ./mvnw compile falla amb Unmapped target property: "zona". Al mapejador manual, aquest camp s'hauria quedat a nul fins que un usuari de Ribalta ho notés.

El domini de CicloUrbana i el seu contracte públic són per fi dues coses separades. Saps per què exposar les entitats és una mala idea i ho pots justificar amb quatre fallades concretes: la fuita silenciosa d'un hash de contrasenya o un DNI, l'acoblament que converteix un canvi de nom innocent en una ruptura de l'app mòbil, les referències circulars que provoquen un StackOverflowError tan bon punt hi hagi relacions, i la impossibilitat d'exposar una dada calculada com bicicletesDisponibles sense contaminar el model. Entens la diferència entre un DTO de petició —mínim, validat, sense identificadors generats— i un de resposta —amb camps calculats, sense validació, en variants de resum i detall—, i per què són record immutables el constructor compacte dels quals és el lloc natural per normalitzar. Tens la taula completa dels onze DTO del projecte, amb dues decisions de disseny que val la pena recordar: ActualitzarEstacioRequest omet les coordenades perquè una estació física no es mou, i LloguerResponse substitueix el bicicletaId intern per la matrícula que veu el ciutadà.

Saps mapejar de tres maneres i triar-ne una: manual quan hi ha pocs DTO, MapStruct tan bon punt creix —amb unmappedTargetPolicy=ERROR, que converteix l'oblit silenciós en un error de compilació— i mai ModelMapper. Has llegit el codi que MapStruct genera i saps que no és màgia. Tens la política del projecte sobre on viu el mapatge —mapejador dedicat invocat des del controlador, amb el servei parlant només el llenguatge del domini— i els criteris per decidir quan imbricar un agregat i quan paginar-lo a part. I saps com evolucionar el contracte sense trencar clients, amb la duplicitat temporal de camps que fa compatible gairebé qualsevol canvi.

Queda un últim buit, i és el més visible des de fora. Quan alguna cosa va malament, CicloUrbana respon amb {"type":"about:blank","title":"Bad Request","status":400,"detail":"Invalid request content."}, que no diu quin camp ha fallat. Una ConstraintViolationException de 03-04 surt com a 500. Els 404 els construïm a mà a cada controlador amb ResponseEntity.notFound(). I les regles de negoci de 03-03 llancen IllegalStateException que es converteixen en errors del servidor amb la traça de pila a dins, quan haurien de ser 409 nets. Tot aquest deute fa tres lliçons que s'acumula amb etiquetes TODO.

La lliçó 03-06, Gestió d'Excepcions a REST, el salda del tot. Veurem què fa Spring Boot per defecte i per què no n'hi ha prou per a una API pública; construirem la jerarquia d'excepcions de CicloUrbana amb el seu mapatge a codis HTTP; centralitzarem tot en un @RestControllerAdvice; adoptarem el format estàndard RFC 7807 Problem Details amb el suport natiu de Spring Boot 3; convertirem els errors de validació de 03-04 en una resposta amb la llista exacta de camps erronis; gestionarem les excepcions del framework mateix; i afegirem un identificador de rastreig que permeti correlacionar qualsevol error amb els logs del servidor.