AI 에이전트의 경우: 문서 인덱스는 https://www.mongodb.com/ko-kr/docs/llms.txt에서 사용할 수 있으며, 모든 페이지의 마크다운 버전은 어떤 URL 경로에 .md를 추가하여 사용할 수 있습니다.

MongoDB 와 Quarkus 통합

이 가이드 에서는 Quarkus 를 웹 프레임워크 로 사용하고 Eclipse JNoSQL 을 사용하여 MongoDB 에 액세스 Java REST API 만드는 방법을 학습 수 있습니다. Quarkus는 클라우드 네이티브 마이크로서비스 및 서버리스 개발을 위해 설계된 오픈 소스 Java 프레임워크 입니다. Eclipse JNOSQL은 자카르타 NoSQL 및 자카르타 데이터 사양을 구현하여 Java 애플리케이션과 NoSQL 데이터베이스의 통합을 간소화합니다.

이 튜토리얼의 애플리케이션 다음과 같은 계층으로 구성되어 있습니다.

  • 데이터베이스 계층: MongoDB 데이터 저장 및 검색을 제공합니다.

  • 애플리케이션 계층: Quarkus는 HTTP 요청, 라우팅 및 종속성 주입을 처리합니다.

  • 데이터 액세스 계층: JNoSQL은 MongoDB 문서 매핑 및 리포지토리 패턴을 제공합니다.

이 튜토리얼에서는 Quarkus JNoSQL Extension을 사용하여 NoSQL 데이터베이스를 위한 통합 API 제공하고 친숙한 Java 패턴과 주석을 사용하여 MongoDB 로 작업할 수 있는 MongoDB 에 액세스 . 따라서 MongoDB 와 Quarkus를 사용하여 최소한의 구성으로 경량 애플리케이션을 개발할 수 있습니다.

MongoDB Quarkus와 통합하면 MongoDB의 유연한 document model 과 함께 Quarkus의 빠른 스타트업 시간과 효율적인 리소스 사용을 활용할 수 있습니다. 이 조합은 유형 안전성, 확장성 및 빠른 개발 주기가 필요한 애플리케이션을 지원합니다. MongoDB 와 Quarkus를 사용하여 마이크로서비스, 클라우드 네이티브 API 또는 고성능과 낮은 리소스 소비가 필요한 시스템과 같은 실제 애플리케이션을 만들 수 있습니다.

이 튜토리얼에서는 MongoDB 와 Quarkus를 사용하는 REST API 빌드 방법을 보여줍니다. 애플리케이션 샘플 레스토랑 데이터에 액세스하고, 데이터를 쿼리하고, RESTful 엔드포인트를 통해 결과를 반환합니다. 이 튜토리얼에는 MongoDB Atlas 에서 호스팅되는 MongoDB 클러스터 에 연결하기 위한 지침도 포함되어 있습니다.

팁

Quarkus 없이 Java 드라이버를 사용하여 MongoDB에 연결하려면 Java 드라이버 시작하기 튜토리얼을 참조하세요.

이 섹션의 단계에 따라 프로젝트 종속성을 설치하고, Atlas 클러스터를 만들고, 애플리케이션 구조를 설정하세요.

1

빠른 시작 애플리케이션 만들려면 개발 환경에 다음 소프트웨어를 설치하세요.

전제 조건
참고 사항

JDK 버전 21 이상을 설치합니다.

버전 3.8.1 이상을 사용하세요.

이 명령줄 인터페이스를 사용하였 터미널에서 Quarkus 프로젝트를 생성하고 관리할 수 있습니다.
중요: 이 튜토리얼에서는 버전 3.30.6을 사용하며, 나중 버전에서는 오류가 발생할 수 있습니다. 운영 체제에 해당하는 설치 지침 에 따라 특정 버전을 설치합니다.

코드 편집기

원하는 코드 편집기를 사용하세요.

터미널 앱 및 shell

MacOS 사용자의 경우 터미널 또는 유사한 앱 사용하세요. Windows 사용자의 경우 PowerShell 또는 명령 프롬프트를 사용하세요.

2

MongoDB Atlas 는 MongoDB 배포서버를 호스팅하다 완전 관리형 클라우드 데이터베이스 서비스입니다. MongoDB 배포서버 없는 경우, MongoDB 시작하기 튜토리얼을 완료하여 MongoDB 클러스터 무료로 만들 수 있습니다. MongoDB 시작하기 튜토리얼에서는 이 튜토리얼에서 사용되는 sample_restaurants 데이터베이스 포함하여 샘플 데이터 세트를 클러스터 에 로드하는 방법도 보여줍니다.

MongoDB cluster 에 연결하려면 연결 문자열 사용해야 합니다. 연결 문자열 조회 방법을 학습하려면 MongoDB 시작하기 튜토리얼의 연결 문자열 추가하기 섹션을 참조하세요.

중요

연결 string 을 안전한 위치 에 저장합니다.

3

터미널에서 다음 명령을 실행 MongoDB 용 Quarkus JNoSQL 확장 및 REST 엔드포인트를 위한 JSON 직렬화를 구성하는 quarkus-quickstart 라는 새 Quarkus 프로젝트 생성합니다.

quarkus create app quarkus-quickstart --extensions=jnosql-mongodb,resteasy-jackson

그런 다음 다음 명령을 실행 하여 프로젝트 디렉토리 로 이동합니다.

cd quarkus-quickstart
4

src/main/resources/application.properties 파일 로 이동하여 다음 구성 속성을 추가합니다.

jnosql.document.database=sample_restaurantsquarkus.mongodb.connection-string=<connection string>

이 코드는 MongoDB cluster 의 sample_restaurants 데이터베이스 에 대한 연결을 구성합니다. <connection string> 자리 표시자를 이전 단계에서 저장한 연결 문자열로 바꿉니다.

5

Quarkus 프로젝트 템플릿에는 이 튜토리얼에서 제거 할 수 있는 몇 가지 샘플 파일이 포함되어 있습니다. 이러한 불필요한 파일을 삭제 하려면 운영 체제에 해당하는 탭 선택하고 quarkus-quickstart 디렉토리 에서 다음 명령을 실행 .

rm src/main/java/org/acme/Car.javarm src/main/java/org/acme/Garage.javarm src/test/java/org/acme/GarageTest.javarm src/main/java/org/acme/GreetingResource.javarm src/test/java/org/acme/GreetingResourceIT.javarm src/test/java/org/acme/GreetingResourceTest.java

프로젝트 구조 및 종속성을 설정한 후 이 섹션의 단계에 따라 데이터 모델, 리포지토리 클래스 및 REST 엔드포인트를 생성합니다.

1

src/main/java/org/acme 디렉토리 에 Restaurant.java 이라는 파일 만들고 다음 코드를 붙여넣습니다.

quarkus-quickstart/src/main/java/org/acme/Restaurant.java

package org.acme; import jakarta.nosql.Column;import jakarta.nosql.Entity;import jakarta.nosql.Id; /** * Represents a restaurant entity from the sample_restaurants database . * This class is used as an entity in the MongoDB database. */@Entity("restaurants")public class Restaurant { @Id private String id; @Column private String name; @Column private String borough; @Column private String cuisine; // Default constructor required by JNoSQL public Restaurant() {} // Constructor public Restaurant(String id, String name, String borough,String cuisine) { this.id = id; this.name = name; this.borough = borough; this.cuisine = cuisine; } // Getters and setters public String getId() { return id; } public void setId(String id) { this.id = id; } public String getName() { return name; } public void setName(String name) { this.name = name; } public String getBorough() { return borough; } public void setBorough(String borough) { this.borough = borough; } public String getCuisine() { return cuisine; } public void setCuisine(String cuisine) { this.cuisine = cuisine; }}

이 파일 sample_restaurants.restaurants 컬렉션 의 문서에 매핑되는 Restaurant 엔티티 클래스를 정의합니다. @Entity 주석은 이 클래스를 JNoSQL 엔터티로 표시하고 필드 주석은 Java 속성을 문서 필드에 매핑합니다.

2

src/main/java/org/acme 디렉토리 에 RestaurantRepository.java 이라는 파일 만들고 다음 코드를 붙여넣습니다.

quarkus-quickstart/src/main/java/org/acme/RestaurantRepository.java

package org.acme; import jakarta.data.repository.Repository;import org.eclipse.jnosql.mapping.NoSQLRepository; import java.util.List; /** * Interface for managing restaurant data. * * It uses the Jakarta Data Specification capabilities. * */@Repositorypublic interface RestaurantRepository extends NoSQLRepository<Restaurant, String> { List<Restaurant> findByBorough(String borough); List<Restaurant> findByCuisine(String cuisine);}

이 리포지토리 클래스는 MongoDB 에서 레스토랑 데이터에 액세스하기 위한 메서드를 제공합니다. 사용자 지정 findByBorough() 및 findByCuisine() 쿼리 메서드를 정의하며 RestaurantRepository 인스턴스 사용하여 내장 생성, 읽기, 업데이트 및 삭제 메서드에 액세스 할 수도 있습니다.

3

src/main/java/org/acme 디렉토리 에서 RestaurantResource.java 이라는 파일 만들고 다음 코드를 붙여넣습니다.

quarkus-quickstart/src/main/java/org/acme/RestaurantResource.java

package org.acme; import jakarta.inject.Inject;import jakarta.ws.rs.*;import jakarta.ws.rs.core.MediaType;import jakarta.ws.rs.core.Response;import java.util.List; /** * REST API controller for restaurant operations. * Provides endpoints for retrieving restaurant data from MongoDB. */@Path("/restaurants")@Produces(MediaType.APPLICATION_JSON)@Consumes(MediaType.APPLICATION_JSON)public class RestaurantResource { @Inject RestaurantRepository restaurantRepository; /** * Retrieves all restaurants from the database. * * @return List of all restaurants */ @GET public Response getAllRestaurants() { try { List<Restaurant> restaurants = restaurantRepository.findAll().toList(); System.out.println("Found " + restaurants.size() + " restaurants"); return Response.ok(restaurants).build(); } catch (Exception e) { e.printStackTrace(); return Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity("Error retrieving restaurants: " + e.getMessage()) .build(); } } /** * Retrieves filtered restaurants in Queens that contain "Moon" in the name. * * @return List of filtered restaurants */ @GET @Path("/browse") public Response getFilteredRestaurants() { try { // Temporarily use findAll() to test basic connectivity List<Restaurant> allRestaurants = restaurantRepository.findAll().toList(); System.out.println("Total restaurants found: " + allRestaurants.size()); // Filter for Queens restaurants that also have "Moon" in the name List<Restaurant> queensRestaurants = allRestaurants.stream() .filter(restaurant -> "Queens".equals(restaurant.getBorough()) && restaurant.getName() != null && restaurant.getName().toLowerCase().contains("moon")) .toList(); System.out.println("Queens restaurants found: " + queensRestaurants.size()); return Response.ok(queensRestaurants).build(); } catch (Exception e) { e.printStackTrace(); return Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity("Error retrieving filtered restaurants: " + e.getMessage()) .build(); } } /** * Retrieves restaurants by cuisine type. * * @param cuisine The cuisine type to filter for * @return List of restaurants that have the specified cuisine */ @GET @Path("/cuisine/{cuisine}") public Response getRestaurantsByCuisine(@PathParam("cuisine") String cuisine) { try { List<Restaurant> restaurants = restaurantRepository.findByCuisine(cuisine); return Response.ok(restaurants).build(); } catch (Exception e) { return Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity("Error retrieving restaurants by cuisine: " + e.getMessage()) .build(); } }}

이 REST 리소스 클래스는 다음 HTTP 엔드포인트를 정의합니다.

  • GET /restaurants/: restaurants 컬렉션 에서 모든 문서를 조회합니다.

  • GET /restaurants/browse: 대소문자를 구분하지 않는 쿼리 수행하여 이름에 "Moon" 가 포함된 퀸즈의 레스토랑을 나타내는 문서를 조회합니다.

  • GET /restaurants/cuisine/{cuisine}: 지정된 cuisine 값을 제공하는 레스토랑을 나타내는 문서를 검색합니다.

4

src/test/java/org/acme 디렉토리 에서 RestaurantRepositoryTest.java 이라는 파일 만들고 다음 코드를 붙여넣습니다.

quarkus-quickstart/src/test/java/org/acme/RestaurantRepositoryTest.java

package org.acme; import io.quarkus.test.junit.QuarkusTest;import jakarta.inject.Inject;import org.junit.jupiter.api.DisplayName;import org.junit.jupiter.api.Test; import java.util.List; import static org.assertj.core.api.Assertions.assertThat; /** * RestaurantRepositoryTest is a test class for testing the RestaurantRepository operations. * * It uses the Quarkus Test framework to test the restaurant data access. */@QuarkusTestpublic class RestaurantRepositoryTest { @Inject RestaurantRepository restaurantRepository; @Test @DisplayName("Should retrieve restaurants from the database") public void testRetrieveRestaurants() { // Test repository injection and MongoDB connection assertThat(restaurantRepository).isNotNull(); } @Test @DisplayName("Should find restaurants by borough") public void testFindRestaurantsByBorough() { // Test that the method exists and returns data List<Restaurant> restaurants = restaurantRepository.findByBorough("Queens"); assertThat(restaurants).isNotNull(); }}

이 파일 통합 테스트를 위해 Quarkus의 테스트 프레임워크 사용합니다. 이 코드는 MongoDB 연결을 테스트하기 위해 다음과 같은 메서드를 정의합니다.

  • testRetrieveRestaurants(): RestaurantRepository 클래스가 MongoDB 액세스하는지 확인합니다.

  • testFindRestaurantsByBorough(): findByBorough() 메서드가 MongoDB 데이터를 조회하는지 확인합니다.

마지막으로 이 섹션의 단계에 따라 curl 명령을 사용하여 REST API 실행 하고 엔드포인트를 테스트합니다.

1

먼저 프로젝트 디렉토리 에서 다음 명령을 실행 테스트 제품군을 실행 .

./mvnw test

이 명령은 RestaurantRepositoryTest 클래스를 실행하고 애플리케이션 이 MongoDB 데이터에 액세스 할 수 있는지 확인합니다. 성공적인 하면 명령 출력에 다음 정보가 포함됩니다.

[INFO] Results:[INFO][INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0[INFO][INFO] ------------------------------------------------------------------------[INFO] BUILD SUCCESS[INFO] ------------------------------------------------------------------------[INFO] Total time: ... s[INFO] Finished at: ...[INFO] ------------------------------------------------------------------------
2

프로젝트 디렉토리 에서 다음 명령을 실행 애플리케이션 컴파일하고 개발 모드 에서 시작합니다.

./mvnw quarkus:dev
3

별도의 터미널 창 에서 다음 curl 명령을 실행 REST 엔드포인트를 테스트합니다. 각 엔드포인트는 sample_restaurants.restaurants 컬렉션 의 레스토랑 정보가 포함된 JSON 데이터를 반환합니다. 성공적인 하면 명령이 샘플 출력과 유사한 데이터를 반환합니다.

  1. 모든 레스토랑을 조회합니다.

    curl http://localhost:8080/restaurants/
  2. 이름에 "Moon" 이(가) 포함된 퀸즈의 레스토랑을 조회합니다.

    curl http://localhost:8080/restaurants/browse
  3. 요리 유형별로 레스토랑을 조회합니다.

    다음 명령은 cuisine 값이 "Czech"인 레스토랑을 쿼리하지만 이 매개변수를 모든 요리로 바꿀 수 있습니다.

    curl http://localhost:8080/restaurants/cuisine/Czech

Quarkus 퀵 스타트 튜토리얼을 완료한 것을 축하합니다! 이 단계를 완료하면 MongoDB deployment 에 연결하고, 샘플 레스토랑 데이터에 대한 쿼리를 실행하고, curl 명령을 사용하여 테스트할 수 있는 HTTP 엔드포인트를 통해 결과를 노출하는 Java Quarkus REST API 갖게 됩니다.

Quarkus, JNoSQL, MongoDB 에 대해 자세히 학습 다음 리소스를 참조하세요.