Overview
Panache es una librería específica del marco Quarkus que simplifica el desarrollo de capas de persistencia basadas en Hibernate. Reduce el código accidental proporcionando operaciones CRUD integradas y consultas seguras por tipo.
Panache soporta tanto el patrón Active Record, que incorpora operaciones de bases de datos directamente en las clases de entidades, como el patrón Repository, 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 Hibernate Object-Relational Mapping (ORM) y Java Persistence API (API) para simplificar el acceso a los datos manteniendo el código limpio.
En este tutorial, crearás una aplicación Quarkus con Panache para realizar operaciones CRUD y agregaciones en una base de datos MongoDB. La aplicación permite agregar, actualizar, buscar y borrar libros, así como contar libros por género.
Tutorial
En este tutorial, realice las siguientes acciones:
Verifique los requisitos previos
Configura el proyecto
Crear el modelo de datos
Crear puntos finales de REST API
Probar la API
Verifique los requisitos previos
Antes de comenzar, asegúrate de tener lo siguiente:
Una cuenta de MongoDB Atlas con un clúster configurado. Para aprender a configurar un clúster de Atlas, consulte la MongoDB Guía introductoria.
Versión de Java 21 o posterior. Para obtener más información sobre cómo instalar Java, consulta el Oracle sitio web.
Tu IDE preferido.
Maven para gestionar dependencias de proyectos.
Configura el proyecto
Cree una carpeta para contener su proyecto Quarkus. Navegue a este directorio y cree un proyecto 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"
Agrega las siguientes dependencias a tu 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>
Compila la aplicación y descarga las dependencias ejecutando el siguiente comando en el directorio del 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 de MongoDB con campos para el título, el autor, el género y el año.
Crear puntos finales de REST API
Crea un archivo BookRepository.java en tu directorio de paquete. Dentro de este archivo, define 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 su directorio de paquetes. Dentro de este archivo, define una clase de recurso que utilice la interfaz BookRepository que has creado 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 endpoints de API para operaciones CRUD y agregaciones. Puede agregar el código para cada punto de conexión debajo de la línea resaltada en el ejemplo anterior.
Inserta un libro
Puede insertar un solo libro agregando el siguiente código a su clase de recursos:
BookRepository bookRepository; public Response addBook(Book book) { bookRepository.persist(book); return Response.status(Response.Status.CREATED).entity(book).build(); }
Bulk insert
Puedes insertar varios libros a la vez añadiendo el siguiente código a tu clase de recursos:
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 la base de datos y el nombre de la colección del paquete com.mongodb.client.MongoCollection.
Encontrar 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
Puedes recuperar un libro específico por su valor _id añadiendo el siguiente código a tu clase de recurso:
public Book getBookById( String id) { return bookRepository.findById(new ObjectId(id)); }
Borrar un libro por ID
Puedes borrar un libro por su valor _id agregando el siguiente código a tu 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(); }
Actualiza un libro
Puedes actualizar un libro por su valor _id añadiendo el siguiente código a la clase de recursos:
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(); }
Agrupar por género
Puedes contar libros por género al añadir el siguiente código de agregación a tu 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
Inicia tu aplicación en http://localhost:8080 ejecutando el siguiente comando desde el directorio raíz de tu proyecto:
mvn spring-boot:run
You can test the API endpoints by running the following curl Commands:
Inserta un libro
El siguiente comando curl muestra cómo insertar un único 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 } ]'
Encontrar 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
Borrar un libro
El siguiente comando curl muestra cómo borrar un libro:
curl -X DELETE "http://localhost:8080/books/673f81b65750de0757a4bbfb" | jq
Actualiza un libro
El siguiente comando curl muestra cómo actualizar un book:
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 }'
Agrupar 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 dar formato a la salida JSON
Utilice la herramienta jq, como se muestra en los ejemplos anteriores, para formatear la salida JSON de la API para una mejor legibilidad. Puedes instalar jq siguiendo las instrucciones en el sitio web jq.
Recursos adicionales
Para ver la versión completa del ejemplo de este tutorial, consulta el quarkus-panache-with-mongodb repositorio Github.
Para obtener más información sobre Panache, consulte la documentación de MongoDB con Panache en el sitio web de Quarkus.