/ /

/ /

튜토리얼: Panache 및 MongoDB 사용하여 Quarkus 애플리케이션 빌드

개요

Panache는 하이버네이트 기반 지속성 계층의 개발을 간소화하는 Quarkus 프레임워크 전용 라이브러리입니다. 내장 CRUD 작업 및 유형 안전 쿼리를 제공하여 상용구 코드를 줄입니다.

Panache는 데이터베이스 작업을 엔터티 클래스에 직접 포함하는 Active 기록 패턴과 데이터 액세스 로직을 전용 리포지토리 클래스로 분리하는 리포지토리 패턴 모두 지원합니다. Quarkus와 통합되어 스타트업 시간이 빠르고 메모리 사용량이 적습니다. Panache는 하이버네이트 객체 관계형 매핑(ORM) 및 Java 지속성 API (JPA)와 함께 작동하여 코드를 깔끔하게 유지하면서 데이터 액세스 간소화합니다.

이 튜토리얼에서는 MongoDB database 에서 CRUD 작업 및 애그리게이션을 수행하기 위해 Panache로 Quarkus 애플리케이션 빌드 . 이 애플리케이션 사용하면 책을 추가, 업데이트, 찾기 및 삭제 수 있을 뿐만 아니라 장르별로 책 수를 계산할 수도 있습니다.

튜토리얼

이 튜토리얼에서는 다음 조치를 수행합니다.

전제 조건 확인
프로젝트 설정
데이터 모델 만들기
REST API 엔드포인트 만들기
API 테스트

전제 조건 확인

시작하기 전에 다음이 준비되어 있는지 확인하세요.

클러스터 가 구성된 MongoDB Atlas 계정. Atlas cluster 설정하다 방법을 학습 MongoDB 시작하기 가이드 참조하세요.
Java 버전 21 이상. Java 설치에 대한 자세한 학습 은 Oracle 웹사이트 참조하세요.
선호하는 IDE.
Maven을 사용하여 프로젝트 종속성을 관리.

프로젝트 설정

Quarkus 프로젝트 저장할 폴더를 만듭니다. 이 디렉토리 로 이동하여 다음 명령을 실행 Maven으로 Quarkus 프로젝트 생성합니다.

mvn io.quarkus:quarkus-maven-plugin:create \
      -DprojectGroupId=io.quarkus.platform \
      -DprojectArtifactId=quarkus-bom \
      -DclassName="com.example.BookResource" \
      -Dpath="/books"

pom.xml 파일 에 다음 종속성을 추가합니다.

<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>

프로젝트 디렉토리 에서 다음 명령을 실행 하여 애플리케이션 빌드하고 종속성을 다운로드 .

mvn clean install

데이터 모델 만들기

먼저 프로젝트 의 루트 디렉토리 에서 src/main/java/com/<package>으로 이동합니다. 이 디렉토리 에 Book.java 파일 만듭니다. 이 파일 내에서 다음 코드에 표시된 대로 Book 클래스를 정의합니다.

import io.quarkus.mongodb.panache.PanacheMongoEntity;
import io.quarkus.mongodb.panache.common.MongoEntity;
@MongoEntity(collection = "books")
public class Book extends PanacheMongoEntity {
    public String title;
    public String author;
    public String genre;
    public int year;
    public Book() {
    }
}

이 클래스는 제목, 저자, 장르 및 연도에 대한 필드가 있는 MongoDB 컬렉션 의 책 문서 나타냅니다.

REST API 엔드포인트 만들기

패키지 디렉토리 에 BookRepository.java 파일 만듭니다. 이 파일 내에서 다음 코드에 표시된 대로 BookRepository 클래스를 정의합니다.

import com.quarkusWithPanache.model.Book;
import io.quarkus.mongodb.panache.PanacheMongoRepository;
import jakarta.enterprise.context.ApplicationScoped;
@ApplicationScoped
public class BookRepository implements PanacheMongoRepository<Book> {
}

다음으로 패키지 디렉토리 에 BookResource.java 파일 만듭니다. 다음 코드와 같이 이 파일 내에서 이전 예시 에서 생성한 BookRepository 인터페이스를 사용하는 리소스 클래스를 정의합니다.

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;
@Path("/books")
public class BookResource {
    @Inject
    BookRepository bookRepository;
    @Inject
    MongoClient mongoClient;
    private MongoCollection<Document> getCollection() {
        return mongoClient.getDatabase("test").getCollection("books");
    }
    @Inject
    public BookResource(BookRepository bookRepository) {
        this.bookRepository = bookRepository;
    }
    // Define API endpoints here
}

다음 섹션에서는 CRUD 작업 및 집계를 위한 다양한 API 엔드포인트를 구현 방법을 보여줍니다. 앞의 예시 에서 강조 표시된 줄 아래에 각 엔드포인트에 대한 코드를 추가할 수 있습니다.

책 한 권 삽입

리소스 클래스에 다음 코드를 추가하여 단일 책을 삽입할 수 있습니다.

@Inject
BookRepository bookRepository;
@POST
public Response addBook(Book book) {
    bookRepository.persist(book);
    return Response.status(Response.Status.CREATED).entity(book).build();
}

Bulk insert

리소스 클래스에 다음 코드를 추가하여 한 번에 여러 책을 삽입할 수 있습니다.

@POST
@Path("/bulk")
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();
}

getCollection 메서드는 com.mongodb.client.MongoCollection 패키지 에서 데이터베이스 및 컬렉션 이름을 반환합니다.

모든 책 찾기

리소스 클래스에 다음 코드를 추가하여 모든 책을 조회 할 수 있습니다.

@GET
public List<Book> getAllBooks() {
    return bookRepository.listAll();
}

ID로 하나의 결과 찾기 책

리소스 클래스에 다음 코드를 추가하여 _id 값으로 특정 책을 조회 할 수 있습니다.

@GET
@Path("/{id}")
public Book getBookById(@PathParam("id") String id) {
    return bookRepository.findById(new ObjectId(id));
}

ID 로 책 삭제

리소스 클래스에 다음 코드를 추가하여 _id 값으로 책을 삭제 수 있습니다.

@DELETE
@Path("/{id}")
public Response deleteBook(@PathParam("id") String id) {
    boolean deleted = bookRepository.deleteById(new ObjectId(id));
    return deleted ? Response.noContent().build() : Response.status(Response.Status.NOT_FOUND).build();
}

책 업데이트

리소스 클래스에 다음 코드를 추가하여 _id 값으로 책을 업데이트 할 수 있습니다.

@PUT
@Path("/{id}")
public Response updateBook(@PathParam("id") 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();
}

장르별 애그리게이션

리소스 클래스에 다음 집계 코드를 추가하여 장르별로 책 수를 계산할 수 있습니다.

@GET
@Path("/aggregate/genre-count")
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();
}

API 테스트

프로젝트 의 루트 디렉토리 에서 다음 명령을 실행 하여 http://localhost:8080 에서 애플리케이션 시작합니다.

mvn spring-boot:run

다음 curl 명령을 실행 하여 API 엔드포인트를 테스트할 수 있습니다.

책 한 권 삽입

다음 curl 명령은 단일 책을 삽입하는 방법을 보여줍니다.

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

다음 curl 명령은 여러 책을 삽입하는 방법을 보여줍니다.

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
        }
    ]'

모든 책 찾기

다음 curl 명령은 모든 책을 조회 방법을 보여줍니다.

curl -X GET "http://localhost:8080/books" | jq

책 하나의 결과 찾기

다음 curl 명령은 특정 책을 조회 방법을 보여줍니다.

curl -X GET "http://localhost:8080/books/672f873b421eaa0c3e4da49f" | jq

책 삭제

다음 curl 명령은 책을 삭제 방법을 보여줍니다.

curl -X DELETE "http://localhost:8080/books/673f81b65750de0757a4bbfb" | jq

책 업데이트

다음 curl 명령은 책을 업데이트 방법을 보여줍니다.

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
       }'

장르별 애그리게이션

다음 curl 명령은 장르별로 책 수를 계산하는 방법을 보여줍니다.

curl -X GET "http://localhost:8080/books/aggregate/genre-count" | jq

팁

jq를 사용하여 JSON 출력 형식 지정

앞의 예시와 같이 jq 도구를 사용하여 가독성을 높이기 위해 API 의 JSON 출력 형식을 지정합니다. jq 웹사이트의 지침에 따라 jq 를 설치할 수 있습니다.

추가 리소스

이 튜토리얼에서 예시 의 전체 버전을 보려면 quarkus-panache-with-mongodb Github 리포지토리 참조하세요.

Panache에 대해 자세히 학습하려면 Quarkus 웹사이트에서 MongoDB with Panache 설명서를 참조하세요.

돌아가기

Spring 세션 MongoDB 시작하기

Testcontainers 통합 테스트