/ /

/ /

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

개요

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

Panache는 데이터베이스 작업을 엔터티 클래스에 직접 포함하는 Active Record 패턴 과 데이터 액세스 로직을 전용 리포지토리 클래스로 분리하는 Repository 패턴 모두 지원합니다. 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 로 1권의 책 찾기

리소스 클래스에 다음 코드를 추가하여 _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

1권의 책 찾기

다음 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 출력 형식 지정

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

추가 리소스

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

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

돌아가기

Spring Data MongoDB

Testcontainers 통합 테스트