Proof of Concept: Spring Boot 3 en Render

Hola pingüinos! 🐧Este es el primer post de mi blog 🥳🎉.

En días anteriores, hice un Live en mi canal de Twitch en respuesta a diferentes consultas realizadas por los equipos que se encuentran juiciosamente trabajando en la iniciativa de la comunidad Try-Catch (A quienes aprovecho la oportunidad de permitirme, de forma voluntaria y gratuita, ayudarles como consultor a los diferentes miembros que están aprendiendo construcción de software) respecto a las siguientes situaciones que les empezaron a suceder:

• Únicamente podían crear ambientes de ejecución en Render con Java 11.
• Esto conllevaba a bajar de versión de Spring Boot a la versión 2, y tampoco poder utilizar la más reciente versión de Java LTS, Java 17.
• El ambiente de ejecución en Render no soportaba correctamente la inclusión de librerías como Swagger.

Así que con el fin de encontrar una propuesta de solución a estas inquietudes y necesidades de los equipos, estuve trabajando en la siguiente prueba de concepto (PoC, Proof of Concept, por sus siglas en inglés) para desplegar una aplicación backend en Spring Boot 3 que exponga una REST API simple y se pueda desplegar correctamente en el ecosistema Render.

Pero primero, revisemos los siguientes conceptos:

Spring Boot

• Framework de código abierto que facilita la creación de aplicaciones empresariales en Java.
• Proporciona una plataforma integral que incluye características como configuración automática, gestión de dependencias y una estructura de proyecto fácil de usar.
• Simplifica significativamente el proceso de creación de aplicaciones al reducir la cantidad de código que necesita ser escrito.
• Permite a los desarrolladores enfocarse en la lógica de negocio y no en la configuración y detalles técnicos de bajo nivel.

Render

• Plataforma en la nube que permite a los desarrolladores implementar y escalar aplicaciones web y API de forma rápida y fácil.
• Ofrece características útiles para los desarrolladores, como alojamiento de aplicaciones, bases de datos y más.
• Una de sus principales ventajas es su facilidad de uso y configuración. Los desarrolladores pueden configurar y lanzar aplicaciones en cuestión de minutos.

Ahora que hemos repasado los principales conceptos técnicos correspondiente a la prueba de concepto, determinemos cuál es la alternativa de solución.

Docker

Tan simple como eso. Crear imágenes de nuestra aplicación de las cuales podamos ejecutar contenedores en Render, definiendo las condiciones necesarias para la correcta ejecución de nuestro sistema. Pero recordemos, qué es Docker:

• Plataforma de contenedores de software que permite empaquetar y distribuir aplicaciones independientemente del sistema operativo.
• Los contenedores son una especie de paquete que incluye todo lo que una aplicación necesita para ejecutarse, como código, bibliotecas y dependencias.
• Los contenedores pueden ejecutarse en cualquier lugar donde Docker esté instalado, lo que significa que se pueden crear aplicaciones en cualquier entorno y distribuirlas fácilmente.

Requerimientos

Ahora que hemos definido cuál es nuestra alternativa de solución, delimitemos el alcance de nuestra prueba de concepto a través de una lista de requerimientos funcionales y no funcionales. Vamos a crear un microservicio para administrar transacciones a través de un REST API.

Funcionales

• Registrar Transacciones (Fecha, Valor y Descripción).
• Consultar (una o todas), editar y eliminar transacciones.
• Consultar el saldo actual, resultado de las transacciones.

No Funcionales

• Utilizar una base de datos relacional.
• Desplegar en Render.
• Utilizar Spring Boot 3 y Java 17.
• Exponer en REST API.
• Generar documentación OpenAPI.
• Realizar pruebas unitarias.

Modelo de Arquitectura

Para darnos una idea más general de la prueba de concepto, vamos a utilizar el modelo de arquitectura C4 para ir describiendo a diferentes niveles, cómo vamos a construir nuestra aplicación. Es verdad, que para ser una prueba de concepto tan sencilla, se podría decir que no es necesario llegar a generar este modelado ni entrar a tanto nivel de detalle, pero quise realizar este ejercicio para enseñar a los miembros de la comunidad que deben primero analizar la problemática y diseñar la solución antes de comenzar a programar código.

Contexto

En este diagrama encontramos el contexto completo para nuestra aplicación. Tenemos nuestro Sistema de Transacciones que funcionará para el registro y consulta de esta información, operaciones que serán realizadas por el Usuario de la misma. Nuestro contexto es bastante simple, y estamos asumiento que el Usuario realizará las peticiones al REST API directamente.

Contenedores

Para construir el sistema de nuestra prueba de concepto, utilizaremos dos contenedores:

• Aplicación API: Contenedor de Spring Boot 3 correspondiente al REST API de las transacciones.
• Aplicación DB: Contenedor de la base de datos relacional, en el motor PostgreSQL que almacenará la información de las transacciones.

Componentes

Detallando los diferentes componentes que tendrá el contenedor del microservicio de aplicación REST API para las transacciones, encontramos los siguientes:

• Controlador REST de Transacciones: Corresponde a un Spring REST Controller que expondrá los endpoints para interactuar con los clientes y realizar las operaciones de las transacciones.
• Servicio de Transacciones: Es un Spring Service que contrendrá toda la lógica de negocio referente a las operaciones de las transacciones.
• Repositorio de Transacciones: Un Spring Repository que gestionará todo el acceso a los registros de los transacciones y que realizará la comunicación con la capa de persistencia, representada por la base de datos de la aplicación.
• Configuración OpenAPI: Hace referencia a un Spring Configuration que manejará la configuración necesaria que se genere la documentación OpenAPI referente a los endpoints expuestos por el Controlador REST.

Código

El modelo de código lo dividiremos en dos, dado que antes de iniciar con el modelo de clases, creo conveniente que revisemos el modelo de entidades de base de datos.

Entidades de Base de Datos

Este podrá ser el diagrama de base de datos más simple que hayamos visto 😅, pero dado los requerimientos que definimos para la prueba de concepto no necesitamos más. Cada una de las transacciones que serán almacenadas en la base de datos tendrán los siguientes atributos:

• id: Identificador primario de cada transacción. Será un UUID.
• date_time: Fecha y hora de la transacción. El tipo de dato es un Timestamp.
• amount: Monto de la transacción. Podrá ser tanto positivo como negativo. El tipo de dato es un Double.
• description: Descripción de la transacción. Será un Varchar.

Clases

En este modelo de nuestra prueba de concepto encontraremos los siguientes paquetes y clases:

• model: Paquete que contiene el modelo de nuestra aplicación.
  • entity: Paquete que contiene las entidades persistentes.
    • Transaction: Entidad referente a las transacciones.
  • repository: Paquete que contiene los repositorios de persistencia.
    • TransactionRepository: Interfaz que hereda de JpaRepository del framework de Spring y que define las operaciones persistentes referentes a las transacciones.
  • service: Paquete que contiene los servicios de lógica de negocio.
    • TransactionService: Clase que posee todas las operaciones de la lógica de negocio referente a las transacciones.
  • exception: Paquete que contiene las excepciones propias de las operaciones de la lógica de negocio.
  • TransactionException: Excepción referente a los errores generados por las operaciones de las transacciones. Hereda de la clase Exception de Java.
• controller: Paquete que contiene la gestión de los controladores de nuestro contenedor de aplicación.
  • rest: Paquete que contiene los controladores REST.
    • TransactionRestController: Clase del controlador REST que expone los endpoints del API de las transacciones. Cada una de las funcionalidades referentes a los endpoints, tiene su descripción para la documentación OpenAPI.
  • advice: Paquete que contiene los manejadores de excepción.
    • RestResponseEntityExceptionHandler: Clase que hereda de ResponseEntityExceptionHandler del framework de Spring y que maneja las excepciones del tipo definido TransactionException que llegan a la capa de los controladores REST, para que se presenten con un formato definido.
    • ErrorResponse: Record que define el formato de respuesta a presentar cuando una TransactionException es generada y llega hasta la capa de los controladores REST.
• config: Paquete que contiene las clases de configuración del contenedor de aplicación.
  • openapi: Paquete que contiene las clases de configuración para OpenAPI.
    • OpenApiConfig: Clase de configuración para la gestión de la generación de la documentación OpenAPI.

Dependencias

Para poder construir nuestra aplicación de transacciones de forma ordenada y eficiente, debemos utilizar una herramienta de gestión y construcción. Para nuestra prueba de concepto, utilizaremos Apache Maven. Las dependencias que necesitamos para construir nuestro proyecto se definen dentro del archivo pom.xml y son las siguientes:

• org.springframework.boot
  • spring-boot-starter-data-jpa: Dependencia de Spring Boot que incluye el framework Spring Data JPA para trabajar con bases de datos relacionales de manera simplificada.
  • spring-boot-starter-web: Dependencia de Spring Boot que incluye las librerías necesarias para crear aplicaciones web, incluyendo un servidor web integrado.
  • spring-boot-starter-validation: Dependencia de Spring Boot que incluye el framework de validación de datos Hibernate Validator.
• org.postgresql
  • postgresql: Dependencia de PostgreSQL que permite la conexión a una base de datos PostgreSQL utilizando JDBC.
• org.projectlombok
  • lombok: Dependencia que agiliza la creación de clases Java, permitiendo crear getters y setters, constructores y otros métodos de forma más sencilla.
• org.springdoc
  • springdoc-openapi-starter-webmvc-ui: Dependencia de Spring Boot que permite la generación de documentación OpenAPI (anteriormente conocida como Swagger) para APIs REST.
• org.apache.commons
  • commons-lang3: Librería de Apache que proporciona utilidades para manipulación de cadenas, operaciones con objetos, manejo de excepciones y otras operaciones comunes en programación.

Implementación

Listo! Ya teniendo claro nuestros requerimientos y el diseño de solución, realizamos la implementación de nuestro código de aplicación.

Nuestra prueba de concepto se llama render-spring-boot-rest-api-poc y se encuentra disponible en el siguiente repositorio de Github: https://github.com/george-the-penguin/render-spring-boot-rest-api-poc . En el archivo README del repositorio se encuentran las instrucciones para la creación, construcción y despliegue de la aplicación (En inglés).

Solución Docker

Los siguientes son los aspectos más importantes para construir la solución a partir de Docker para realizar un despliegue correcto en la plataforma Render:

Propiedades Aplicación

El archivo application.properties debe contener las siguientes propiedades para que funcione la conexión a la base de datos:

• spring.datasource.driver-class-name: Indica la clase del controlador JDBC que se utilizará para conectarse a la base de datos. Obligatoria.
• spring.jpa.hibernate.ddl-auto: Indica cómo Hibernate debe manejar la creación y actualización de tablas de la base de datos. Los valores comunes son “create”, “update” y “validate”. Obligatoria.
• spring.jpa.show-sql: Indica si Hibernate debe imprimir las consultas SQL generadas en la consola. Opcional.
• spring.jpa.properties.hibernate.format_sql: Indica si Hibernate debe formatear las consultas SQL generadas para que sean más legibles. Opcional.
• spring.jpa.properties.hibernate.dialect: Indica el dialecto de la base de datos que se está utilizando. El dialecto se utiliza para generar las consultas SQL adecuadas para la base de datos. Obligatoria.

spring.datasource.driver-class-name=org.postgresql.Driver
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect

Es importante JAMÁS COLOCAR LAS CREDENCIALES DE CONEXIÓN A LA BASE DE DATOS EN EL ARCHIVO DE PROPIEDADES. ⚠️

Dockerfile

Un Dockerfile es un archivo de texto que contiene las instrucciones para construir una imagen de Docker. El Dockerfile especifica los componentes y dependencias necesarios para construir la imagen, así como cualquier configuración que deba aplicarse al contenedor.

En este caso, creamos un Dockerfile con dos orígenes. En el primero usamos una imagen de Apache Maven compatible con Java 17 a la cual le pasamos el código fuente de la aplicación y el archivo pom.xml y ejecutamos los comandos de construcción del ejecutable. En el segundo origen, utilizamos una imagen que contenga Java 17, en la cual exponemos el puerto de aplicación (8080) y copiamos el JAR (Archivo ejecutable) resultado del anterior origen; también copiamos un script bash que contiene las instrucciones de ejecución, le damos permiso de ejecutarse dentro del contenedor y establecemos la instrucción de ejecución de dicho script.

FROM maven:3.9.1-eclipse-temurin-17-focal AS build
COPY src /home/app/src
COPY pom.xml /home/app
RUN mvn -f /home/app/pom.xml clean package

FROM openjdk:17-jdk-alpine
EXPOSE 8080
COPY --from=build /home/app/target/render-spring-boot-rest-api-poc*.jar /usr/local/lib/app.jar
COPY start.sh start.sh
RUN chmod +x start.sh
ENTRYPOINT ["./start.sh"]

Script Bash

El principal ingrediente de nuestra receta de solución. Este script Bash nos permite ejecutar el JAR de aplicación y pasar los valores de conexión de base de datos de forma oculta a través de variables de entorno. En el script pasamos las siguientes propiedades de Spring:

• spring.datasource.url: Indica la URL de conexión a la base de datos. La URL incluye el protocolo de la base de datos (como “jdbc:postgresql”), la dirección IP o el nombre de host del servidor de la base de datos y el nombre de la base de datos.
• spring.datasource.username: Indica el nombre de usuario que se utilizará para conectarse a la base de datos.
• spring.datasource.password: Indica la contraseña que se utilizará para conectarse a la base de datos.

#!/bin/sh
java -jar /usr/local/lib/app.jar --spring.datasource.url=$DB_URL --spring.datasource.username=$DB_USER \
--spring.datasource.password=$DB_PASSWD

Las variables de entorno DB_URL, DB_USER y, DB_PASSWD deben ser establecidas en el ambiente del servicio web correspondiente a la aplicación en Render.

Configuración en Render

Dentro del dashboard de nuestra cuenta de Render, debemos realizar las siguientes operaciones:

Configuración de Base de Datos

En nuestra configuración de base de datos PostgreSQL en Render, buscamos en la sección “Connections” la información del nombre de usuario (Username), contraseña (Password) y URL.

Configuración de Servicio Web

Luego, con la información obtenida de la configuración de base de datos de Render, ingresamos a la configuración del servicio web a exponer, correspondiente a nuestra aplicación. Tras indicar cuál es el repositorio Github de nuestra aplicación, en la sección “Advanced” ingresamos las siguientes variables de ambiente que serán pasadas a nuestro contenedor. Esta información tras ser almacenada en la configuración de Render, serán almacenadas como secretos y no podrán volver a ser consultadas posteriormente, lo que hace este mecanismo mucho más seguro respecto al uso de nuestras credenciales.

• PORT: Puerto expuesto en nuestra imagen de Docker. Internamente, Render hará una redirección del puerto HTTPS por defecto del servicio web expuesto resultante hacia este puerto interno.
• DB_URL: URL JDBC de nuestra base de datos.
• DB_USER: Usuario de nuestra base de datos.
• DB_PASSWD: Contraseña de nuestra base de datos.

Resultado

Finalmente, tendremos nuestra aplicación desplegada y disponible en internet. 🏆

En el caso de mi prueba de concepto desplegada, está en https://render-spring-boot-rest-api-poc.onrender.com/swagger-ui/index.html . Allí se puede consultar la documentación OpenAPI del servicio REST.

Conclusiones

Tras realizar este ejercicio de prueba de concepto, he llegado a las siguientes conclusiones:

• Docker es la mejor forma de exportar nuestras aplicaciones a cualquier entorno.
• Spring Boot requiere recursos de hardware para una efectiva ejecución. Render Free únicamente ofrece 512MB de RAM y 0.1 CPU (Tiempo de Start-Up aprox. 3 minutos).
• Podría ser más efectivos frameworks más ligeros como Micronaut o Quarkus con generación de imágenes nativas?
• Para la siguiente fase de la iniciativa TryCatch, es recomendable usar un entorno cloud más poderoso como AWS, por ejemplo.

Oportunidades

Y las anteriores conclusiones y reflexiones del ejercicio realizado nos abre las siguientes oportunidades de estudio para los miembros de la comunidad Try-Catch, para así continuar mejorando nuestra prueba de concepto y aprendizaje:

• Hay un error de diseño en la aplicación. Pueden detectar cuál es?
• Cuál técnica se puede utilizar para revisar que el código fuente cumpla los estándares? Cuáles posibles errores se podrían encontrar?
• Revisar las pruebas unitarias con JUnit 5 y el uso de Mockito.
• Aprender a usar Lombok y OpenAPI.
• Importante: Aprender Docker!
• Crear una interfaz gráfica (Web o móvil).
• Pregunten a los Team Leaders y Consultores de la iniciativa TryCatch. No desaprovechen esta oportunidad. Pidan revisión de código a través de los Pull Request.

Quienes quieran responder a estas inquietudes, recibo sus respuestas en los comentarios de este post o en mis redes sociales. También pueden crear forks del repositorio en Github y solicitar Pull Requests para mejorar nuestra prueba de concepto. Finalmente, pueden también proponer nuevas pruebas de concepto para que revisemos y trabajemos.

Recursos de Aprendizaje

• Spring Boot: https://spring.io/
• Render: https://render.com/
• Java: https://dev.java/
• OpenAPI: https://www.openapis.org/
• Docker: https://www.docker.com/
• Modelo C4: https://c4model.com/
• PostgreSQL: https://www.postgresql.org/
• Lombok: https://projectlombok.org/
• Apache Commons Lang: https://commons.apache.org/proper/commons-lang/
• JUnit: https://junit.org/junit5/
• Mockito: https://site.mockito.org/
• Micronaut: https://micronaut.io/
• Quarkus: https://quarkus.io/