Vamos a instrumentalizar un SDD para un microservicio bancario. En este artículo sobre SDD – Spec Driven Development, instrumentalizado sobre OpenSpec vamos a construir una PoC de algo más serio que una tabla periódica. Un microservicio bancario muy simplificado que gestione cuentas y permita hacer transferencias
Índice de contenidos
- 1. Introducción a Spec Driven Development (SDD)
- 2. No lo intentes hacer todo de golpe
- 3. SDD para un microservicio bancario
- 4. Patrón Active Record
- 5. Usar IBAN como PK en lugar de un UUID
- 6. Renombrar la paquetería
- 7. Añadir el serialVersionUID a las clases serializables
- 8. Añadir un frontal Web
- 9. Ajustar el IBAN
- 10. Conclusiones
- 11. Enlaces y referencias
1. Introducción
Esto del SDD empieza a gustarme mucho. Toca hacer la prueba con algo más serio que una tabla periódica. En esta PoC voy a implementar un microservcio bancario muy simplificado que gestione cuentas y haga transferencias. Y lo voy a hacer con un modelo local gratuito, para simular que no tengo acceso a los grandes modelos de Anthropic y pensando en optimización de recursos y tiempo.
Lo primero que hago es optimizar mi modelo local. Me habían hablado muy bien del modelo que estaba usando yo, pero el QAT, sin cuantización. Bueno, realmente hacen la cuatización cuando entrenan al modelo y no a posteriori, con lo que no pierden precisión. Me lo descargo y hago una prueba.
Borro el código de los artículos anteriores, el de la tabla periódica, y le pido al modelo que regenere el código en base a las specs.
- Con Gemma 4 (modelo gratuito local)
revisar specs y preparar propuesta: 3′ 35″
aplicar propuesta: 3′ 07″ - Con Claude – Sonnet 4.6
revisar specs y preparar propuesta: 3′ 37″
aplicar propuesta: 11′ 16″ - Con Gemma 4 (modelo QAT)
revisar specs y preparar propuesta: 2′ 11″
aplicar propuesta: 1′ 43″
La diferencia es evidente. Me quedo con el modelo Gemma 4, pero QAT, que ocupa unos 2,4 GB menos de RAM y va bastante más rápido.
En este contexto me dispongo a hacer un microservicio bancario.
2. No lo intentes hacer todo de golpe.
Mi primera aproximación fue:
/opsx-propose quiero implementar un microservicio bancario en Quarkus en la version LTS 3.35.4 1) que gestione cuentas y permita la operativa de transferencias. 1.1) usa maven. artifactId="account" y groupId="com.microbanco" 2) Tengo instalado Java 25 (GraalVM) con la intención de poder compilar a nativo 3) la capa de persistencia será un postgreSQL que está en localhost. usuario y contraseña son postgres 4) quiero usar el patrón active record de panache (el ORM) y no el patrón repository 4.1) La entidad para la cuenta debe ser "account" 4.2) La entidad para las trasferencias debe ser "transfer" 4.3) Todas las entidades deben tener propiedades "created_at" y "last_updated_at" 4.4) Y los tipos java para tiempo que sean de tipo Instant para no usar LocalDate con TimeZone 4.5) para las cifras de dinero usa BigDecimal, no float ni double. 5) el ID de la cuenta debe ser el IBAN 6) los IBAN de esta prueba de concepto deben ser del tipo 'ES' + digitoDeControl + '00830001' y luego 12 digitos aleatorios. 7) la paquetería debe commenzar por 'com.microbanco.account' 7.1) la paquetería será "entities" para las entidades 7.2) "services" para los servicios 7.3) "boundary" para las APIS 7.4) "dto" para los pojos 7.5) "exceptions" y reunificar mappers y excepciones 8) no compiles la imagen nativa
La realidad es que lo hizo, revisé las specs generadas y apliqué. Unos 8′ después tenía todo el código generado y, en apariencia, razonable, pero hubo un pequeño problema. NO levantó el servidor y quedé mal ante mi auditorio. Había repetido esa prueba varias veces antes. ¿Qué pasó?
Lo primero:
– estamos tratando con LLMs. La respuesta no es determinista. No es siempre la misma
– quisimos hacer muchas cosas de un solo tiro.
¿Podíamos haber depurado, detectar el error y haber iterado corrigiéndolo?
Sin duda.
Pero creo que es mejor una aproximación más lenta, pasito a pasito, a lo que queremos. Solo un cambio cada vez. Empecemos desde el principio.
3. SDD para un microservicio bancario
/opsx-propose quiero implementar un microservicio bancario en Quarkus LTS que gestione cuentas y permita la operativa de transferencias. Tengo instalado Java 25 (GraalVM) con la intención de poder compilar a nativo
Tras eso revisamos las specs, estamos de acuerdo o enmendamos, y hacemos el apply
/opsx-apply
4. Patrón Active Record
Hay muchos patrones y, en general en el mundo spring, el patrón repository está muy extendido. Sin embargo, aunque se puede implementar en Quarkus, éste es mucho más moderno y la mayoría de la gente prefiere una simplificación llamada Patrón Active Record. Usándolo nos vamos a quitar muchas clases de en medio. No tenemos entidades y repositorios. Solo entidades.
/opsx-propose quiero usar mejor la estrategia Active Record de Panache en lugar del patrón repository.
Tras revisar los cambios y lo que propone, aplicamos.
/opsx-apply
5. Usar el IBAN como PK en lugar de un UUID
Otra de las cosas que me he dado cuenta es que la PK de la entidad cuenta es un UUID en lugar del IBAN.
Prefiero que la PK de la tabla cuenta sea el IBAN
/opsx-propose quiero cambiar y que la cuenta sea un IBAN en lugar de un UUID
Reviso los cambios propuestos, las specs y las tareas y le doy al apply
/opsx-apply
6. Renombrar la paquetería
/opsx-propose quiero renombrar la paquetería 1) cambiar 'com.microbanco.account.infraestructura.persistence' por 'com.microbanco.account.entities' 2) al estar las entidades en ese paquete ya no necesitan llamarse AlgoEntity. El sufijo Entity sobra. 3) cambiar "com.microbanco.account.application" por "com.microbanco.account.services" 4) cambiar "com.microbanco.account.infrastructure.rest" por "com.microbanco.account.boundary" 5) cambiar "com.microbanco.account.infrastructure.rest.dto" por "com.microbanco.account.dto" 6) cambiar "com.microbanco.account.infrastructure.rest.exception" por "com.microbanco.account.exceptions" y reunificar mappers y excepciones en ese paquete. 7) creo que AccountApplication no vale para nada. Si es así, borradla. 8) AccountStatus ponlo como un enum anidado interno de la entidad Account 9) limpia los imports que ya no sean necesarios.
Tras revisar todos los cambios propuestos aplicamos
7. Añadir el serialVersionUID a las clases serializables
/opsx-propose genera el serialVersionUID para las excepciones que son serializables y quita los imports que no se usen
Y aplicamos
8. Añadir un frontal Web
/opsx-propose quiero añadir un frontal sobrio y elegante, con colores suaves, que se levante con el microservicio quarkus. No requiere autenticación, pues es una PoC. Y debe tener una pantalla para consultar la posición global, donde se verán las cuentas del usuario con su saldo y podrá dar de alta cuentas nuevas. Al entrar en una de las cuentas, se mostrará el saldo y la posibilidad de hacer transferencias hacia cuentas propias o externas utilizando las APIs existentes
Aplicamos los cambios tras revisarlos
9. Ajustar el IBAN
Queremos ajustar el IBAN para que trabaje con una entidad determinada
/opsx-propose en el **back** quiero que al generar el IBAN siempre comiencen por 'ES' + checkDigits + '00830001' y luego 12 digitos aleatorios. en el **frontal**, quiero que 1) al introducir un IBAN se pueda introducir en bloques de cuatro caracteres separados por un espacio, pero cuando se envía al API que vaya sin los espacios. 2) Por otro lado, cuando haces transferencias a otras cuentas que no están en nuestra entidad (que no empiecen por 'ES' + checkDigits + '00830001') que no muestre la validación de que la cuenta no existe
Revisamos todo lo que nos propone y, si estamos de acuerdo, aplicamos
10. Resultado
El caso es que ya tenemos un frontal que nos muestra nuestras cuentas.
Con su historial de transferencias
Y tenemos el Swagger-UI y el OpenAPI de nuestros servicios REST
10. Conclusiones
Hemos aprendio a hacer SDD para un microservicio bancario. No hemos tocado una sola línea de código. De hecho, nos hemos centrado en el propose y en el apply, pero lo cierto es que, tras cada apply debemos hacer el archive. El primero lo hará sin problema porque no hay specs generales, pero el segundo y siguientes hará un sync. Esto quiere decir que aplicará los deltas a las specs. Añadirá las nuevas y quitará las que ya no apliquen, modificando las que sean necesarias.
Es tras este archive cuando debemos hacer commit con los cambios y con las specs, que también debemos repositarlas.
Otro dato, es que si quieres cambiar algo del código, no debes hacerlo por tu cuenta, porque se pierde la trazabilidad. Debes indicárselo en una propuesta y que genere las specs con el cambio. Para mantener el ciclo iterativo.
Yo estoy muy satisfecho con el código generado. La simplicidad y el estilo de codificación es casi como si lo hubiese hecho yo.
11. Enlaces y referencias
- El código fuente de este tutorial en GitHub
https://github.com/eContento/lab/tree/main/microbanco-sdd
