From d9bb7017fd0294be4c3ed463292e28d66468260e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Hern=C3=A1ndez?= <111492700+danielhhdev@users.noreply.github.com> Date: Sat, 7 Jun 2025 11:29:38 +0200 Subject: [PATCH 1/3] Clarify native image benefits --- README.md | 61 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 34 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 4b4dd47..5f9bf6b 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,60 @@ # API REST con Spring Boot 3.5 -Este proyecto es una demostraci\u00f3n de una API REST desarrollada con **Spring Boot 3.5** y **Java 21**. +Proyecto de ejemplo construido con **Spring Boot 3.5** y **Java 21**. Forma parte de mi portafolio personal y demuestra el uso de hilos virtuales y la generación de una imagen nativa para la aplicación. -## Prop\u00f3sito +## Propósito -Implementar un ejemplo de backend que expone operaciones CRUD y procesamiento as\u00edncrono usando hilos virtuales. +Implementar un backend sencillo que exponga operaciones CRUD de clientes y un procesamiento asíncrono. El proyecto sirve para explorar las nuevas capacidades de la plataforma, incluyendo la construcción de un contenedor con imagen nativa. -## Tecnolog\u00edas principales +## Tecnologías principales -- **Maven** para la gesti\u00f3n del proyecto. -- **Spring Data JPA** con **PostgreSQL** como base de datos. +- **Maven** para la gestión y empaquetado. +- **Spring Data JPA** + **PostgreSQL** para persistencia. - **MapStruct** para el mapeo entre entidades y DTOs. -- **Lombok** para reducir c\u00f3digo boilerplate. -- **Jakarta Validation** para validaciones de datos de entrada. -- **SpringDoc OpenAPI** para la documentaci\u00f3n de la API. -- Hilos virtuales para tareas as\u00edncronas (ver `VirtualThreadConfig`). +- **Lombok** para eliminar código repetitivo. +- **Jakarta Validation** para validar datos de entrada. +- **SpringDoc OpenAPI** para documentar la API. +- **Spring Boot Actuator** junto con **Micrometer** para observabilidad. +- Procesamiento asíncrono con **hilos virtuales** (ver `VirtualThreadConfig`). - Pruebas con **JUnit/Mockito** y **Testcontainers**. ## Requisitos previos - **JDK 21** instalado. -- **PostgreSQL** accesible y configurado seg\u00fan `src/main/resources/application.yml`. +- **PostgreSQL** accesible y configurado según `src/main/resources/application.yml`. -## Compilar y ejecutar +## Imagen nativa -```bash -mvn spring-boot:run -``` +La aplicación puede compilarse en una **imagen nativa** gracias a GraalVM y [Paketo Buildpacks](https://paketo.io/). Una imagen nativa ejecuta código máquina precompilado, lo que reduce el tiempo de arranque y el consumo de memoria, ideal para despliegues en contenedores. -Para ejecutar las pruebas: +Para construirla basta con ejecutar: ```bash -mvn test +mvn spring-boot:build-image ``` +El `spring-boot-maven-plugin` crea un contenedor optimizado cuando la variable `BP_NATIVE_IMAGE=true` está presente en el `pom.xml`. + ## Endpoints principales -- `GET /api` - Lista todos los clientes. -- `POST /api` - Crea un nuevo cliente. -- `PUT /api/{id}` - Actualiza un cliente existente. -- `DELETE /api/{id}` - Elimina un cliente. -- `GET /api/consultar-lote` - Procesa de manera as\u00edncrona un lote de clientes. +- `GET /api` – Lista todos los clientes. +- `POST /api` – Crea un nuevo cliente. +- `PUT /api/{id}` – Actualiza un cliente existente. +- `DELETE /api/{id}` – Elimina un cliente. +- `GET /api/consultar-lote` – Procesa de forma asíncrona un lote de clientes. + +El procesamiento en lote se orquesta en `OrchestatorServiceImpl` y utiliza hilos virtuales a través del `virtualThreadTaskExecutor` definido en `VirtualThreadConfig`. + +## Observabilidad -Estas operaciones se encuentran en `ClientControllerImpl`. El procesamiento as\u00edncrono est\u00e1 orquestado por `OrchestatorServiceImpl` y `ClientThreadVirtualServiceImpl` empleando el `virtualThreadTaskExecutor` definido en `VirtualThreadConfig`. +El proyecto expone métricas y endpoints de salud mediante Actuator. Además, gracias a **Micrometer** y su registrador de Prometheus, se pueden recolectar métricas desde `/actuator/prometheus`. -## Archivos y clases relevantes +## CI y despliegue -- `pom.xml` define todas las dependencias y plugins mencionados. -- `application.yml` contiene la configuraci\u00f3n de la base de datos y de SpringDoc OpenAPI. -- Clases en `src/main/java/com/dhh/apiRestSpringboot3` implementan los controladores, servicios y mapeos de la aplicaci\u00f3n. +Existe un flujo de trabajo en **GitHub Actions** encargado de construir y ejecutar las pruebas con Testcontainers. Tras completarse, se solicita un despliegue en **Render** mediante su API. +## Archivos destacados +- `pom.xml` – Dependencias y configuración del plugin para la imagen nativa. +- `application.yml` – Propiedades de base de datos, Swagger y Actuator. +- Carpeta `src/main/java` – Controladores, servicios y configuración principal. From 3c67906fdf29adcc3a40809a1e37a12f5e3c07f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Hern=C3=A1ndez?= Date: Sat, 7 Jun 2025 11:32:53 +0200 Subject: [PATCH 2/3] cambiar ci.yml --- .github/workflows/ci.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0f378b9..fecbf0b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,9 +4,6 @@ on: push: branches: - main - pull_request: - branches: - - main jobs: build: From ab3a0fb502008e437e049f51eaf0e1c9697bc921 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Hern=C3=A1ndez?= Date: Sat, 7 Jun 2025 11:57:10 +0200 Subject: [PATCH 3/3] modificacion readme --- README.md | 137 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 102 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 5f9bf6b..e88e6ef 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,127 @@ -# API REST con Spring Boot 3.5 +# API REST con Spring Boot 3.5 + Java 21 -Proyecto de ejemplo construido con **Spring Boot 3.5** y **Java 21**. Forma parte de mi portafolio personal y demuestra el uso de hilos virtuales y la generación de una imagen nativa para la aplicación. +Proyecto de ejemplo construido con **Spring Boot 3.5** y **Java 21**. Forma parte de un portafolio personal y demuestra el uso de hilos virtuales de Project Loom, procesamiento asíncrono en lotes y la generación de una imagen nativa para despliegues ligeros. ## Propósito -Implementar un backend sencillo que exponga operaciones CRUD de clientes y un procesamiento asíncrono. El proyecto sirve para explorar las nuevas capacidades de la plataforma, incluyendo la construcción de un contenedor con imagen nativa. +Implementar un backend sencillo que exponga operaciones CRUD de clientes y un procesamiento asíncrono de lotes. El proyecto sirve para explorar: + +- **Virtual Threads** (hilos virtuales) para alta concurrencia. +- **GraalVM Native Image** Inicio instantáneo y consumo de memoria reducido. +- Integración con **Spring Boot Actuator** y **Micrometer** para observabilidad. +- Documentación automática con **SpringDoc OpenAPI (Swagger UI)**. +- Pruebas unitarias e integración con **JUnit**, **Mockito** y **Testcontainers**. ## Tecnologías principales -- **Maven** para la gestión y empaquetado. +- **Maven** para gestión de dependencias y empaquetado. - **Spring Data JPA** + **PostgreSQL** para persistencia. - **MapStruct** para el mapeo entre entidades y DTOs. -- **Lombok** para eliminar código repetitivo. -- **Jakarta Validation** para validar datos de entrada. -- **SpringDoc OpenAPI** para documentar la API. -- **Spring Boot Actuator** junto con **Micrometer** para observabilidad. -- Procesamiento asíncrono con **hilos virtuales** (ver `VirtualThreadConfig`). -- Pruebas con **JUnit/Mockito** y **Testcontainers**. +- **Lombok** para reducir código repetitivo. +- **Jakarta Validation** para validación de datos de entrada. +- **Spring Boot Actuator** y **Micrometer** para métricas y salud. +- **SpringDoc OpenAPI** para generación de documentación REST. +- **Procesamiento asíncrono** con hilos virtuales (`VirtualThreadConfig`). +- **Pruebas** con JUnit 5, Mockito y Testcontainers. + +## Pre-requisitos + +- **JDK 21** instalado y en el `PATH`. +- **PostgreSQL** accesible y configurado (ver `application.yml`). +- (Opcional) **Docker** si se desea generar la imagen nativa localmente o ejecutar contenedores de prueba. + +## Instalación y configuración + +1. Clonar el repositorio: + ```bash + git clone https://github.com/tu-usuario/spring-boot-3.5-java21-rest.git + cd spring-boot-3.5-java21-rest + ``` +2. Configurar la conexión a la base de datos en `src/main/resources/application.yml`: + ```yaml + spring: + datasource: + url: jdbc:postgresql://localhost:5432/mi_db + username: postgres + password: secret + jpa: + hibernate: + ddl-auto: update + threads: + virtual: + enable: true + + ``` +3. Ajustar parámetros adicionales (puertos, credenciales, etc.) según necesidad. + +## Construir y ejecutar + +### Modo JVM -## Requisitos previos +```bash +mvn clean spring-boot:run +``` -- **JDK 21** instalado. -- **PostgreSQL** accesible y configurado según `src/main/resources/application.yml`. +### Imagen nativa (GraalVM + Paketo Buildpacks) -## Imagen nativa +1. Asegurarse de tener `BP_NATIVE_IMAGE=true` en el `pom.xml`. +2. Ejecutar: + ```bash + mvn clean spring-boot:build-image + docker run --rm -p 8080:8080 tu-imagen-nativa:latest + ``` -La aplicación puede compilarse en una **imagen nativa** gracias a GraalVM y [Paketo Buildpacks](https://paketo.io/). Una imagen nativa ejecuta código máquina precompilado, lo que reduce el tiempo de arranque y el consumo de memoria, ideal para despliegues en contenedores. +## Endpoints REST -Para construirla basta con ejecutar: +| Método | Ruta | Descripción | +|-------:|------------------------|----------------------------------| +| GET | `/api` | Listar todos los clientes | +| POST | `/api` | Crear un nuevo cliente | +| PUT | `/api/{id}` | Actualizar un cliente existente | +| DELETE | `/api/{id}` | Eliminar un cliente | +| GET | `/api/consultar-lote` | Procesar un lote de clientes | -```bash -mvn spring-boot:build-image -``` +## Procesamiento asíncrono de lotes + +- Servicio orquestador: `OrchestratorServiceImpl`. +- Configuración de hilos virtuales en `VirtualThreadConfig`: + ```java + @Bean + VirtualThreadTaskExecutor virtualThreadTaskExecutor() { + return new VirtualThreadTaskExecutor(); + } + ``` +- El endpoint dispara tareas en hilos virtuales, maneja resultados de forma no bloqueante. + +## Observabilidad y métricas -El `spring-boot-maven-plugin` crea un contenedor optimizado cuando la variable `BP_NATIVE_IMAGE=true` está presente en el `pom.xml`. +- Endpoints de Actuator: + - `/actuator/health` + - `/actuator/metrics` + - `/actuator/prometheus` (Micrometer) +- Trazas distribuidas con OpenTelemetry. -## Endpoints principales +## Pruebas -- `GET /api` – Lista todos los clientes. -- `POST /api` – Crea un nuevo cliente. -- `PUT /api/{id}` – Actualiza un cliente existente. -- `DELETE /api/{id}` – Elimina un cliente. -- `GET /api/consultar-lote` – Procesa de forma asíncrona un lote de clientes. +- **Unitarias**: JUnit 5 + Mockito (`mvn test`). +- **Integración**: Testcontainers para PostgreSQL. -El procesamiento en lote se orquesta en `OrchestatorServiceImpl` y utiliza hilos virtuales a través del `virtualThreadTaskExecutor` definido en `VirtualThreadConfig`. +## CI / CD -## Observabilidad +Flujo de GitHub Actions para: -El proyecto expone métricas y endpoints de salud mediante Actuator. Además, gracias a **Micrometer** y su registrador de Prometheus, se pueden recolectar métricas desde `/actuator/prometheus`. +1. Ejecutar pruebas unitarias e integración. +2. Construir y empaquetar la aplicación. +3. Generar y publicar la imagen nativa. +4. (Opcional) Desplegar a Render u otro servicio. -## CI y despliegue +## Contribuciones -Existe un flujo de trabajo en **GitHub Actions** encargado de construir y ejecutar las pruebas con Testcontainers. Tras completarse, se solicita un despliegue en **Render** mediante su API. +1. Hacer fork del repositorio. +2. Crear una rama feature (`git checkout -b feature/nueva-funcionalidad`). +3. Realizar cambios y commit. +4. Enviar pull request. -## Archivos destacados +## Licencia -- `pom.xml` – Dependencias y configuración del plugin para la imagen nativa. -- `application.yml` – Propiedades de base de datos, Swagger y Actuator. -- Carpeta `src/main/java` – Controladores, servicios y configuración principal. +Este proyecto está bajo la **Licencia MIT**.