Durante diez módulos hemos construido la red de bicicletas eléctricas de Ribalta capa por capa. Primero un endpoint que devolvía cuatro estaciones en memoria; después el contenedor de Spring y sus beans; el contrato REST con sus DTOs y sus errores; la persistencia sobre PostgreSQL con Flyway; la seguridad con JWT y reglas por dato; las pruebas; la operabilidad; el despliegue; y por fin la observabilidad, el criterio y la limpieza. Cada lección añadió una pieza y miró casi siempre hacia la siguiente.

Nunca hemos mirado CicloUrbana entera. Esta lección lo hace: la arquitectura completa en un diagrama, la estructura real del repositorio, el viaje de una sola petición desde el balanceador hasta la métrica —citando en cada paso dónde se estudió—, el mapa de qué construyó cada módulo, las decisiones de diseño con sus alternativas y sus contrapartidas, el pom.xml y la configuración finales, cómo poner el proyecto en marcha desde cero y hacia dónde seguir llevándolo. Si has seguido el curso, aquí vas a reconocerlo todo; lo nuevo es verlo junto.

1. La arquitectura final
2. El repositorio completo
3. El viaje de una petición: POST /api/v1/alquileres
4. Mapa del curso: qué construyó cada módulo
5. Decisiones de diseño y sus alternativas
6. El pom.xml final
7. La configuración final
8. Poner en marcha el proyecto desde cero
9. Recorrido de extremo a extremo con peticiones .http
10. Lista de comprobación final de puesta en producción
11. Hacia dónde seguir con este proyecto
12. Errores Comunes y Consejos
13. Ejercicios

Cuatro observaciones sobre el dibujo, porque un diagrama sin lectura es decoración.

La aplicación es un solo desplegable. Los cinco bloques de dentro no son servicios: son capas y módulos dentro del mismo proceso. Es el monolito modular de 07-05, y las flechas entre ellos son llamadas a métodos, no llamadas de red.

Las dependencias apuntan hacia dentro y hacia abajo. Filtros → controladores → servicios → repositorios → base de datos. Ninguna flecha sube. Es la regla de dependencia de 10-01, verificada automáticamente con las reglas de ArchUnit de 10-03.

La observabilidad es un lateral, no una capa. No está en el camino de la petición: la aplicación publica métricas, logs y trazas, y otros los recogen. Si Prometheus cae, CicloUrbana sigue funcionando.

Lo único que puede tumbar el servicio es PostgreSQL. La caché de Redis degrada a Caffeine, la pasarela tiene cortacircuitos y respaldo de cobro diferido, y el resto es opcional. Esa asimetría es deliberada y está detrás de que la sonda readiness sí consulte la base de datos y la de liveness no.

Dos cosas merecen atención. src/test es un espejo exacto de src/main, lo que permite acceder a miembros con visibilidad de paquete sin abrir la clase de producción y hace el árbol navegable. Y la separación *Test / *IT no es cosmética: Surefire ejecuta los primeros en ./mvnw test en segundos, y Failsafe los segundos en ./mvnw verify con PostgreSQL real.

Marta abre la aplicación en la estación «Plaza Mayor», elige una bicicleta y pulsa «alquilar». Esto es lo que ocurre.

El detalle paso a paso, con su lección:

Lo que se ve al juntarlo. Los pasos 9 y 10 los hace el mismo proxy, y por eso la trampa de la autoinvocación se lleva por delante la transacción y la comprobación de permisos a la vez. El paso 14 no es un detalle de estilo: con open-in-view: false es la única forma de que la respuesta se construya sin LazyInitializationException. Y los pasos 16 a 18 son la razón de que Marta reciba su 201 en decenas de milisegundos mientras el cobro tarda casi dos segundos en otro hilo.

Toda decisión de arquitectura compra algo y paga algo. Estas son las seis principales de CicloUrbana, con lo que costaron.

Y dos decisiones menores que ilustran el mismo modo de pensar. open-in-view: false compra que ninguna consulta se dispare durante la serialización, y paga con la obligación de mapear a DTO dentro de la transacción —lo que, de paso, refuerza una práctica que queríamos igualmente—. La denegación por defecto compra que un olvido produzca un 403 visible en vez de un endpoint abierto, y paga con que cada ruta nueva exija una regla explícita.

Ninguna de estas seis es universalmente correcta. Lo que las hace defendibles es que se tomaron con la contrapartida a la vista y quedaron escritas.

Las dependencias acumuladas, agrupadas por el módulo que las introdujo. La columna de versión es la información importante: solo llevan versión propia las que el BOM de Spring Boot no gestiona, y son exactamente las que hay que revisar a mano en cada actualización.

Y la parte del pom.xml que de verdad hay que leer con atención, porque es la que rompe la construcción ante un problema concreto:

Los seis plugins no son adorno: cada uno rompe la construcción ante un problema concreto —un campo sin mapear, una prueba de integración fallida, código sin formatear, una vulnerabilidad alta—. Es la idea de fondo de 10-01: mover la comprobación de la cabeza de una persona a la construcción.

Y las diferencias por entorno, que es lo único que cambia:

El paso 3 merece un comentario: ./mvnw verify levanta un PostgreSQL efímero con Testcontainers y aplica las nueve migraciones sobre él antes de ejecutar las *IT. Si ese comando pasa en tu máquina, el proyecto está sano de arriba abajo.

Y las tres comprobaciones que cierran el recorrido, que son las que demuestran que la observabilidad del módulo 9 funciona de verdad:

Si los tres devuelven datos, las tres señales están conectadas: la métrica detecta, la traza localiza y el log explica.

El punto 13 no apareció en ninguna lección y es de los que más caro salen: una copia de seguridad que nunca se ha restaurado no es una copia de seguridad, es una esperanza. Y el 15 repite la advertencia del módulo 5: todo lo construido en este curso es un punto de partida didáctico y necesita revisión profesional antes de exponerse a Internet.

CicloUrbana está terminada como material de curso, no como producto. Estas siete extensiones están ordenadas por dificultad y cada una combina lecciones que ya conoces.

Sobre la número 7, que es la que más gente quiere hacer primero: es la última de la lista por una razón. Repartir el sistema en dos procesos convierte una transacción local en una saga con compensaciones, una traza de pila en una investigación entre dos despliegues, y una llamada a método en una llamada de red que puede fallar. Hazla solo cuando tengas trazabilidad distribuida funcionando y una razón concreta —escalado o equipo independiente—, no como ejercicio de estilo.

Y una recomendación sobre el método: para cualquiera de las siete, empieza por escribir la prueba del comportamiento que quieres, sigue por la migración si toca el esquema, y deja el controlador para el final. Es el orden que menos código tira a la basura.

Creer que el diagrama es la arquitectura. El diagrama del apartado 1 es una vista; la arquitectura real es lo que hacen las dependencias del código. Por eso existen las reglas de ArchUnit: son el único diagrama que no puede mentir.

Copiar el pom.xml entero a un proyecto nuevo. Trae Redis, ShedLock, Resilience4j y Testcontainers a un proyecto que quizá no los necesita, y cada dependencia es superficie de mantenimiento y de vulnerabilidades. Empieza por web, data-jpa y test, y añade cuando duela algo.

Levantar la observabilidad entera en local siempre. Prometheus, Grafana, Loki, Tempo y el Collector consumen memoria y tiempo de arranque. En el día a día basta con la aplicación y PostgreSQL; la pila completa se levanta cuando se está trabajando en observabilidad.

Olvidar que el .env no está en el repositorio. Es lo primero que rompe a quien clona el proyecto por primera vez. Un .env.ejemplo versionado con las claves y sin los valores ahorra esa media hora a cada persona nueva.

Consejo: recorre el apartado 3 con un depurador. Poner un punto de interrupción en AlquilerService.iniciar y subir por la pila de llamadas hasta el filtro es el ejercicio que más consolida todo el curso: se ven, en una sola pantalla, el proxy, la transacción, el SecurityContext y el MDC.

Consejo: guarda el registro de decisiones. La tabla del apartado 5 —decisión, alternativa, motivo, contrapartida— es el documento que más se agradece dentro de un año, y el único que responde a «¿por qué está hecho así?».

Consejo: mide antes de extender. Cualquiera de las siete extensiones del apartado 11 cambia el perfil de carga. Guarda la línea base de k6 de hoy: será la referencia para saber si la extensión ha costado algo.

En producción, a las 09:12, la app móvil empieza a recibir 500 en POST /api/v1/alquileres. El cuerpo del error es un ProblemDetail con "code": "ERROR_INTERNO" y un traceId. Describe, paso a paso y con las herramientas concretas del proyecto, cómo investigarías el incidente desde ese traceId hasta la causa raíz, indicando qué pieza de qué módulo usarías en cada paso y qué descartarías con cada una.

Diseña la extensión número 4 del apartado 11: un ciudadano puede reservar una bicicleta concreta durante 10 minutos antes de recogerla; pasado ese tiempo, la reserva caduca y la bicicleta vuelve a estar disponible. Especifica el cambio en el modelo, la migración, el contrato de la API, el control de concurrencia, la tarea de caducidad, las reglas de seguridad, las métricas y las pruebas que escribirías.

El ayuntamiento de una ciudad vecina quiere reutilizar CicloUrbana. Sus números: 40 estaciones (frente a 4), 300 000 alquileres al mes, dos equipos de desarrollo y un requisito nuevo —integración en tiempo real con el sistema de transporte público—. Analiza qué decisiones del apartado 5 seguirían siendo correctas, cuáles habría que revisar y en qué orden abordarías la adaptación.

Solución 1

Paso 1 — de la alerta al cuadro de mando (09-04). Antes de tocar el traceId, mirar la fila RED del panel: ¿es un pico de errores o un goteo? ¿empezó con el despliegue de las 09:05? Con esto se distingue un fallo sistemático de uno puntual, y se decide si hay que revertir ya.

Paso 2 — el log de esa petición exacta (09-05). En Loki: {app="ciclourbana", entorno="prod"} | json | traceId = "...". Devuelve la historia completa de la petición, incluida la traza de pila que no se le envió al cliente. La mayoría de los incidentes se cierran aquí, con el nombre de la excepción y la línea.

Paso 3 — la cascada de spans (09-06). En Tempo, la misma traza. Aquí se responde algo que el log no dice: dónde se fue el tiempo y qué falló. Una barra roja en el span de la pasarela descarta que el problema sea nuestro; veinte spans select idénticos delatan un N+1 nuevo; un hueco de 900 ms sin instrumentar apunta a espera de conexión o a una pausa de GC.

Paso 4 — descartar recursos (09-03). hikaricp.connections.pending, jvm.gc.pause y resilience4j.circuitbreaker.state en el instante del fallo. Si pending está en 60, el problema no es la lógica: algo retiene conexiones —una llamada HTTP dentro de una transacción es el sospechoso número uno—.

Paso 5 — reproducir (06-05). Con la causa identificada, escribir la prueba que la reproduce antes de arreglar nada. Si el fallo depende de datos reales, una *IT con Testcontainers y el estado exacto que lo provoca.

Paso 6 — decidir (08-05). Si el fallo llegó con el despliegue de las 09:05, revertir primero y diagnosticar después: el tiempo de restauración es una métrica DORA y la reversión es un comando. Si es un problema externo, la decisión es de negocio —degradar, abrir el cortacircuitos, esperar—, como en el caso práctico de 09-06.

Lo que el ejercicio enseña: el recorrido va de lo general a lo particular y de lo barato a lo caro. La métrica cuesta un vistazo, la traza un clic, el log una consulta, y el depurador media mañana. Empezar por el depurador es el error más común.

Solución 2

Modelo. EstadoBicicleta gana el valor RESERVADA. Aparece la entidad Reserva(id, usuario, bicicleta, estacion, creada, expira, estado) con EstadoReserva { ACTIVA, CONSUMIDA, CADUCADA, CANCELADA }. La reserva es un agregado propio y no un campo de Bicicleta, porque tiene ciclo de vida, histórico y reglas propias.

Migración V10__reservas.sql. Tabla con secuencia (allocationSize = 50, nunca IDENTITY, por los lotes de 09-01), claves ajenas a usuarios, bicicletas y estaciones, columnas de auditoría, CHECK sobre el estado, índice (expira) WHERE estado = 'ACTIVA' —parcial, unas decenas de filas frente a millones— y un índice único parcial que impide dos reservas activas del mismo usuario, la misma técnica del uk_alquileres_usuario_en_curso. El enum de la columna estado de bicicletas amplía su CHECK: cambio compatible hacia atrás.

Contrato. POST /api/v1/reservas con { "bicicletaId": 12 } devuelve 201 con Location y ReservaResponse(id, matricula, estacion, expira, segundosRestantes). DELETE /api/v1/reservas/{id} cancela (204). Y POST /api/v1/alquileres acepta opcionalmente reservaId: si viene, consume la reserva en lugar de buscar bicicleta.

Concurrencia. Es el punto delicado. SELECT … FOR UPDATE sobre la bicicleta con timeout de 3 s, comprobación de que sigue DISPONIBLE, y cambio a RESERVADA en la misma transacción. Sin bloqueo, dos ciudadanos reservan la misma bicicleta y uno se lleva un 409 innecesario cuando el sistema podría haberle ofrecido otra.

Caducidad. CaducadorReservas, hermano de CaducadorAlquileres: @Scheduled(fixedDelayString = "${ciclourbana.reservas.caducador.intervalo:PT30S}") con @SchedulerLock —tres réplicas, una ejecución—, lógica en un método público invocable para poder probarla, Clock inyectado y idempotencia: marcar como caducada una reserva ya caducada no cambia nada.

Seguridad. @PreAuthorize("isAuthenticated()") para crear; @PreAuthorize("hasAnyRole('OPERARIO','ADMIN') or @seguridadReservas.esPropietario(#idReserva, principal)") para cancelar y consultar, con un bean nuevo idéntico en forma a SeguridadAlquileres. El listado filtra en la consulta, nunca con @PostFilter.

Métricas. Un Counter ciclourbana.reservas.creadas{estacion} y otro ciclourbana.reservas.caducadas, con la etiqueta de estación —cuatro valores— y nunca el identificador de usuario. La tasa de caducidad es el indicador de negocio interesante: si es alta, la ventana de 10 minutos es demasiado corta o demasiado larga.

Pruebas. Unitaria de Reserva.caducar() con Clock.fixed y del caso límite de los 10 minutos exactos; @DataJpaTest del índice único parcial —dos reservas activas del mismo usuario deben violar la restricción—; rodaja de seguridad con dos ciudadanos cruzando identificadores; y una *IT del flujo completo reservar → alquilar → finalizar, más otra de reservar → esperar → comprobar que caducó, con el reloj controlado.

La decisión de diseño que hay que saber defender: la reserva es un agregado propio. Modelarla como dos campos en Bicicleta parece más barato y hace imposible el histórico, complica la caducidad y mete estado transitorio en una entidad que debería ser estable.

Solución 3

Lo que sigue siendo correcto sin discusión. Flyway, DTOs, denegación por defecto, @Transactional en el servicio, Testcontainers, logs estructurados y observabilidad: son decisiones cuyo beneficio crece con el tamaño, no decrece. MapStruct pasa de opcional a claramente rentable, porque el número de DTOs se multiplica.

Lo que hay que revisar, con su motivo.

El orden de la adaptación, que es lo que el ejercicio pregunta de verdad:

1. Medir con los datos nuevos antes de tocar nada. Cargar 40 estaciones y 300 000 alquileres en pre y ejecutar el escenario de k6. Casi todas las decisiones anteriores se resuelven con datos, no con opiniones.
2. Índices y consultas. Lo que se degrada con el volumen se degrada primero, y es lo más barato de arreglar.
3. Fronteras de módulo antes que equipos. Con dos equipos, el conflicto no es técnico sino de propiedad del código: reglas de ArchUnit por módulo y fronteras explícitas antes de repartir el trabajo.
4. Caché distribuida y pool redimensionado, con la prueba de carga como juez.
5. La integración de transporte público, la última, porque introduce una tecnología nueva —mensajería— y conviene hacerlo sobre una base ya estable y medida.

Lo que no haría: dividir en microservicios desde el principio «porque ahora es más grande». Cuarenta estaciones y siete alquileres por minuto no son un problema de escala: son un problema de organización, y ese se resuelve con fronteras internas antes que con procesos separados.

CicloUrbana está completa y, por primera vez, la has visto entera. Tienes la arquitectura final en un diagrama que se lee: un solo desplegable con módulos internos, dependencias que apuntan siempre hacia dentro, la observabilidad como lateral y no como capa, y una única dependencia capaz de tumbar el servicio —PostgreSQL—, lo que explica por qué la sonda readiness la consulta y la de liveness no. Tienes la estructura real del repositorio, con los paquetes por funcionalidad, el árbol de pruebas como espejo del de producción, la separación *Test/*IT y todo lo que rodea al código: Dockerfile, docker-compose, helm/, .github/workflows, observabilidad/ y carga/.

Y tienes el viaje de una petición contado en veintiún pasos, del balanceador a la métrica, con la lección de cada uno. Ese recorrido es el mejor resumen del curso porque en él aparece todo: el filtro que abre el span, el JWT que se valida, el binding y la validación del DTO, el proxy que evalúa el permiso y abre la transacción en el mismo punto —de ahí que la autoinvocación se lleve las dos por delante—, el bloqueo pesimista sobre la última bicicleta de «Plaza Mayor», el mapeo dentro de la transacción que hace posible open-in-view: false, el AFTER_COMMIT que saca el cobro del hilo HTTP y la métrica de negocio que cierra el ciclo.

Tienes también el mapa de qué construyó cada módulo, el pom.xml final donde se ve qué versiones gestiona el BOM y cuáles hay que revisar a mano, la configuración consolidada con la tabla de lo único que cambia entre entornos, los comandos para poner el proyecto en marcha desde cero y la colección .http que recorre registro, login, consulta, alquiler, factura y la comprobación de que un ciudadano no puede leer el alquiler de otro —seguida de las tres consultas que demuestran que la métrica, el log y la traza están unidos por el mismo traceId—.

Y tienes las dos piezas que separan un proyecto de curso de un producto: la tabla de decisiones con sus contrapartidas, que es el documento que responde dentro de un año a «¿por qué está hecho así?», y la lista de comprobación final con sus quince puntos, incluido el que ninguna lección había mencionado —una copia de seguridad que nunca se ha restaurado no es una copia de seguridad— y el que se repite desde el módulo 5: esto es un punto de partida didáctico y necesita revisión profesional antes de exponerse a Internet.

El proyecto no termina aquí, y esa es la idea. Las siete extensiones del apartado 11 están ordenadas por dificultad y cada una te dice qué lecciones combinar, desde el informe con exportación hasta extraer la facturación a un servicio propio —la última de la lista, y con motivo—. Construir cualquiera de ellas sobre esta base es la mejor forma de convertir lo aprendido en algo tuyo.

Queda una última lección, y es la única del curso que no habla de CicloUrbana. Porque saber Spring Boot no es haber terminado un curso: es haber empezado a poder leer la documentación con criterio, distinguir un recurso actualizado de uno que confunde, planificar una actualización de versión mayor sin miedo y elegir qué aprender después entre veinte caminos posibles. Recursos para Aprendizaje Adicional se ocupa de eso: la documentación oficial y cómo leerla, el código fuente como la mejor fuente, cómo mantenerse al día con el ciclo de publicación de Spring, el ecosistema Java, los libros que de verdad valen la pena, las certificaciones con una valoración honesta, la comunidad, la práctica deliberada, los temas naturales para el siguiente paso y una hoja de ruta razonada para los próximos seis meses.