Overview
Panache es una biblioteca específica del framework Quarkus que simplifica el desarrollo de capas de persistencia basadas en Hibernate. Reduce el código repetitivo al proporcionar operaciones CRUD integradas y consultas con seguridad de tipos.
Panache admite tanto el patrón Registro Activo, que integra las operaciones de la base de datos directamente en las clases de entidad, como el patrón Repositorio, que separa la lógica de acceso a los datos en clases de repositorio dedicadas. Se integra con Quarkus para ofrecer tiempos de inicio rápidos y un bajo consumo de memoria. Panache funciona con el Mapeo Objeto-Relacional (ORM) de Hibernate y la API de Persistencia de Java (JPA) para simplificar el acceso a los datos y mantener el código limpio.
En este tutorial, creará una aplicación Quarkus con Panache para realizar operaciones CRUD y agregaciones en una base de datos MongoDB. La aplicación le permite agregar, actualizar, buscar y eliminar libros, así como contarlos por género.
Tutorial
En este tutorial, realizarás las siguientes acciones:
Verificar los prerrequisitos
Configurar el proyecto
Crear el modelo de datos
Crear puntos finales de API REST
Probar la API
Verificar los prerrequisitos
Antes de comenzar, asegúrate de tener lo siguiente:
Una cuenta de MongoDB Atlas con un clúster configurado. Para saber cómo configurar un clúster de Atlas, consulte MongoDB Guía deinicio rápido.
Versión de Java 21 o posterior. Para obtener más información sobre la instalación de Java, consulte Oracle sitio web.
Su IDE preferido.
Maven para gestionar dependencias del proyecto.
Configurar el proyecto
Cree una carpeta para su proyecto de Quarkus. Acceda a este directorio y cree un proyecto de Quarkus con Maven ejecutando el siguiente comando:
mvn io.quarkus:quarkus-maven-plugin:create \ -DprojectGroupId=io.quarkus.platform \ -DprojectArtifactId=quarkus-bom \ -DclassName="com.example.BookResource" \ -Dpath="/books"
Agregue las siguientes dependencias a su pom.xml archivo:
<dependencies> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-arc</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-rest</artifactId> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-rest-client-jackson</artifactId> <version>3.16.2</version> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-resteasy-reactive-jackson</artifactId> <version>3.15.1</version> </dependency> <dependency> <groupId>io.rest-assured</groupId> <artifactId>rest-assured</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>io.quarkus</groupId> <artifactId>quarkus-mongodb-panache</artifactId> </dependency> </dependencies>
Cree la aplicación y descargue las dependencias ejecutando el siguiente comando en el directorio de su proyecto:
mvn clean install
Crear el modelo de datos
Primero, desde el directorio raíz de tu proyecto, navega a src/main/java/com/<package>. Crea un archivo Book.java en este directorio. Dentro de este archivo, define la clase Book como se muestra en el siguiente código:
import io.quarkus.mongodb.panache.PanacheMongoEntity; import io.quarkus.mongodb.panache.common.MongoEntity; public class Book extends PanacheMongoEntity { public String title; public String author; public String genre; public int year; public Book() { } }
Esta clase representa un documento de libro en la colección MongoDB con campos para el título, autor, género y año.
Crear puntos finales de API REST
Cree un archivo BookRepository.java en el directorio de su paquete. Dentro de este archivo, defina la clase BookRepository como se muestra en el siguiente código:
import com.quarkusWithPanache.model.Book; import io.quarkus.mongodb.panache.PanacheMongoRepository; import jakarta.enterprise.context.ApplicationScoped; public class BookRepository implements PanacheMongoRepository<Book> { }
A continuación, cree un archivo BookResource.java en el directorio de su paquete. Dentro de este archivo, defina una clase de recurso que utilice la interfaz BookRepository que creó en el ejemplo anterior, como se muestra en el siguiente código:
import com.mongodb.client.MongoClient; import com.mongodb.client.MongoCollection; import com.quarkusWithPanache.model.Book; import com.quarkusWithPanache.repository.BookRepository; import jakarta.inject.Inject; import jakarta.ws.rs.*; import jakarta.ws.rs.core.Response; import org.bson.Document; import org.bson.types.ObjectId; import java.util.ArrayList; import java.util.List; public class BookResource { BookRepository bookRepository; MongoClient mongoClient; private MongoCollection<Document> getCollection() { return mongoClient.getDatabase("test").getCollection("books"); } public BookResource(BookRepository bookRepository) { this.bookRepository = bookRepository; } // Define API endpoints here }
Las siguientes secciones muestran cómo implementar varios puntos finales de API para operaciones CRUD y agregaciones. Puede agregar el código de cada punto final debajo de la línea resaltada en el ejemplo anterior.
Insertar un libro
Puede insertar un solo libro agregando el siguiente código a su clase de recurso:
BookRepository bookRepository; public Response addBook(Book book) { bookRepository.persist(book); return Response.status(Response.Status.CREATED).entity(book).build(); }
Bulk insert
Puede insertar varios libros a la vez agregando el siguiente código a su clase de recurso:
public Response bulkAddBooks(List<Book> books) { // Prepare documents for bulk write List<Document> documents = new ArrayList<>(); for (Book book : books) { documents.add(new Document("title", book.title) .append("author", book.author) .append("genre", book.genre) .append("year", book.year)); } getCollection().insertMany(documents); return Response.status(Response.Status.CREATED).entity(books).build(); }
El método getCollection devuelve el nombre de la base de datos y de la colección del paquete com.mongodb.client.MongoCollection.
Encuentra todos los libros
Puedes recuperar todos los libros agregando el siguiente código a tu clase de recursos:
public List<Book> getAllBooks() { return bookRepository.listAll(); }
Encuentra un libro por ID
Puede recuperar un libro específico por su valor _id agregando el siguiente código a su clase de recurso:
public Book getBookById( String id) { return bookRepository.findById(new ObjectId(id)); }
Eliminar un libro por ID
Puede eliminar un libro por su valor _id agregando el siguiente código a su clase de recurso:
public Response deleteBook( String id) { boolean deleted = bookRepository.deleteById(new ObjectId(id)); return deleted ? Response.noContent().build() : Response.status(Response.Status.NOT_FOUND).build(); }
Actualizar un libro
Puede actualizar un libro por su valor _id agregando el siguiente código a su clase de recurso:
public Response updateBook( String id, Book book) { Book entity = bookRepository.findById(new ObjectId(id)); if (entity == null) { return Response.status(Response.Status.NOT_FOUND).build(); } entity.title = book.title; entity.author = book.author; entity.genre = book.genre; entity.year = book.year; bookRepository.update(entity); return Response.ok(entity).build(); }
Agregado por género
Puede contar libros por género agregando el siguiente código de agregación a su clase de recurso:
public Response countBooksByGenre() { List<Document> pipeline = new ArrayList<>(); pipeline.add(new Document("$group", new Document("_id", "$genre") .append("count", new Document("$sum", 1)))); List<Document> result = getCollection() .aggregate(pipeline) .into(new ArrayList<>()); return Response.ok(result).build(); }
Probar la API
Inicie su aplicación en http://localhost:8080 ejecutando el siguiente comando desde el directorio raíz de su proyecto:
mvn spring-boot:run
Puede probar los puntos finales de la API ejecutando los siguientes comandos curl:
Insertar un libro
El siguiente comando curl muestra cómo insertar un solo libro:
curl -X POST "http://localhost:8080/books" -H "Content-Type: application/json" -d '{ "title": "Quarkus in Action", "author": "John Doe", "genre": "Programming", "year": 2023 }'
Bulk insert
El siguiente comando curl muestra cómo insertar varios libros:
curl -X POST http://localhost:8080/books/bulk \ -H "Content-Type: application/json" \ -d '[ { "title": "The Midnight Library", "author": "Matt Haig", "genre": "Fiction", "year": 2020 }, { "title": "Sapiens: A Brief History of Humankind", "author": "Yuval Noah Harari", "genre": "Non-Fiction", "year": 2011 } ]'
Encuentra todos los libros
El siguiente comando curl muestra cómo recuperar todos los libros:
curl -X GET "http://localhost:8080/books" | jq
Encuentra un libro
El siguiente comando curl muestra cómo recuperar un libro específico:
curl -X GET "http://localhost:8080/books/672f873b421eaa0c3e4da49f" | jq
Eliminar un libro
El siguiente comando curl muestra cómo eliminar un libro:
curl -X DELETE "http://localhost:8080/books/673f81b65750de0757a4bbfb" | jq
Actualizar un libro
El siguiente comando curl muestra cómo actualizar un libro:
curl -X PUT "http://localhost:8080/books/672f856f421eaa0c3e4da49e" \ -H "Content-Type: application/json" \ -d '{ "title": "Quarkus in Action", "author": "John Doe", "genre": "Programming", "year": 2021 }'
Agregado por género
El siguiente comando curl muestra cómo contar libros por género:
curl -X GET "http://localhost:8080/books/aggregate/genre-count" | jq
Tip
Uso de jq para formatear la salida JSON
Utilice la jq herramienta, como se muestra en los ejemplos anteriores, para formatear la salida JSON de la API y mejorar su legibilidad. Puede instalar jq siguiendo las instrucciones del sitio web de jq.
Recursos adicionales
Para ver la versión completa del ejemplo en este tutorial, consulte el repositorio de Github quarkus-panache-with-mongodb.
Para obtener más información sobre Panache, consulte la documentación de MongoDB con Panache en el sitio web de Quarkus.