개요
이 가이드 에서는 Quarkus를 웹 프레임워크 로 사용하고 Eclipse JNoSQL을 사용하여 MongoDB 에 액세스 Java REST API 만드는 방법을 학습 수 있습니다. Quarkus는 클라우드 네이티브 마이크로서비스 및 서버리스 개발을 위해 설계된 오픈 소스 Java 프레임워크 입니다. Eclipse JNOSQL은 자카르타 NoSQL 및 자카르타 데이터 사양을 구현하여 Java 애플리케이션과 NoSQL 데이터베이스의 통합을 간소화합니다.
이 튜토리얼의 애플리케이션 다음과 같은 계층으로 구성되어 있습니다.
데이터베이스 계층: MongoDB 데이터 저장 및 검색을 제공합니다.
애플리케이션 계층: Quarkus는 HTTP 요청, 라우팅 및 종속성 주입을 처리합니다.
데이터 액세스 계층: JNoSQL은 MongoDB 문서 매핑 및 리포지토리 패턴을 제공합니다.
Quarkus와 함께 MongoDB 사용하는 이유
이 튜토리얼에서는 Quarkus JNoSQL Extension을 사용하여 NoSQL 데이터베이스를 위한 통합 API 제공하고 친숙한 Java 패턴과 주석을 사용하여 MongoDB 로 작업할 수 있는 MongoDB 에 액세스 . 따라서 MongoDB 와 Quarkus를 사용하여 최소한의 구성으로 경량 애플리케이션을 개발할 수 있습니다.
MongoDB Quarkus와 통합하면 MongoDB의 유연한 문서 모델 과 함께 Quarkus의 빠른 스타트업 시간과 효율적인 리소스 사용을 활용할 수 있습니다. 이 조합은 유형 안전성, 확장성 및 빠른 개발 주기가 필요한 애플리케이션을 지원합니다. MongoDB 와 Quarkus를 사용하여 마이크로서비스, 클라우드 네이티브 API 또는 고성능과 낮은 리소스 소비가 필요한 시스템과 같은 실제 애플리케이션을 만들 수 있습니다.
빠른 시작 튜토리얼
이 튜토리얼에서는 MongoDB 와 Quarkus를 사용하는 REST API 빌드 방법을 보여줍니다. 애플리케이션 샘플 레스토랑 데이터에 액세스하고, 데이터를 쿼리하고, RESTful 엔드포인트를 통해 결과를 반환합니다. 이 튜토리얼에는 MongoDB Atlas 에서 호스팅되는 MongoDB cluster 에 연결하기 위한 지침도 포함되어 있습니다.
팁
Quarkus 없이 Java 운전자 사용하여 MongoDB 에 연결하려는 경우 Java 드라이버 시작하기 튜토리얼을 참조하세요.
프로젝트 설정
이 섹션의 단계에 따라 프로젝트 종속성을 설치하고, Atlas 클러스터를 만들고, 애플리케이션 구조를 설정하세요.
전제 조건을 확인합니다.
빠른 시작 애플리케이션 만들려면 개발 환경에 다음 소프트웨어를 설치하세요.
전제 조건 | 참고 사항 |
|---|---|
JDK 버전 21 이상을 설치합니다. | |
버전 3.8.1 이상을 사용하세요. | |
This command-line interface allows you to create and manage Quarkus
projects from your terminal. Important: This tutorial uses version 3.30.6, and later versions
might cause errors. Follow the installation instructions
corresponding to your operating system to install the specific version. | |
코드 편집기 | 원하는 코드 편집기를 사용하세요. |
터미널 앱 및 shell | MacOS 사용자의 경우 터미널 또는 유사한 앱 사용하세요. Windows 사용자의 경우 PowerShell 또는 명령 프롬프트를 사용하세요. |
MongoDB Atlas cluster 만듭니다.
MongoDB Atlas 는 MongoDB 배포를 호스팅하는 완전 관리형 클라우드 데이터베이스 서비스입니다. MongoDB deployment 없는 경우,MongoDB 시작하기 튜토리얼을 완료하여 MongoDB cluster 무료로 만들 수 있습니다. MongoDB 시작하기 튜토리얼에서는 sample_restaurants 이 튜토리얼에서 사용되는 데이터베이스 포함하여 샘플 데이터 세트를 클러스터 에 로드하는 방법도 보여줍니다.
MongoDB cluster 에 연결하려면 연결 문자열 사용해야 합니다. 연결 문자열 조회 방법을 학습 MongoDB 시작하기 튜토리얼의 연결 문자열 추가하기 섹션을 참조하세요.
중요
연결 string 을 안전한 위치 에 저장합니다.
데이터베이스 연결을 구성합니다.
src/main/resources/application.properties 파일 로 이동하여 다음 구성 속성을 추가합니다.
jnosql.document.database=sample_restaurants quarkus.mongodb.connection-string=<connection string>
이 코드는 MongoDB cluster 의 데이터베이스 에 대한 연결을 sample_restaurants 구성합니다. 자리 표시자를 <connection string> 이전 단계에서저장한 연결 문자열 로 바꿉니다.
템플릿 파일을 정리합니다.
Quarkus 프로젝트 템플릿에는 이 튜토리얼에서 제거 할 수 있는 몇 가지 샘플 파일이 포함되어 있습니다. 이러한 불필요한 파일을 삭제 하려면 운영 체제에 해당하는 탭 선택하고 quarkus-quickstart 디렉토리 에서 다음 명령을 실행 .
rm src/main/java/org/acme/Car.java rm src/main/java/org/acme/Garage.java rm src/test/java/org/acme/GarageTest.java rm src/main/java/org/acme/GreetingResource.java rm src/test/java/org/acme/GreetingResourceIT.java rm src/test/java/org/acme/GreetingResourceTest.java
del src/main/java/org/acme/Car.java del src/main/java/org/acme/Garage.java del src/test/java/org/acme/GarageTest.java del src/main/java/org/acme/GreetingResource.java del src/test/java/org/acme/GreetingResourceIT.java del src/test/java/org/acme/GreetingResourceTest.java
애플리케이션 만들기
프로젝트 구조 및 종속성을 설정한 후 이 섹션의 단계에 따라 데이터 모델, 리포지토리 클래스 및 REST 엔드포인트를 생성합니다.
Restaurant 모델을 만듭니다.
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. */ public class Restaurant { private String id; private String name; private String borough; 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 속성을 문서 필드에 매핑합니다.
리포지토리 클래스를 만듭니다.
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. * */ public interface RestaurantRepository extends NoSQLRepository<Restaurant, String> { List<Restaurant> findByBorough(String borough); List<Restaurant> findByCuisine(String cuisine); }
이 리포지토리 클래스는 MongoDB 에서 레스토랑 데이터에 액세스하기 위한 메서드를 제공합니다. 사용자 지정 findByBorough() 및 findByCuisine() 쿼리 메서드를 정의하며 RestaurantRepository 인스턴스 사용하여 내장 생성, 읽기, 업데이트 및 삭제 메서드에 액세스 할 수도 있습니다.
REST 리소스 클래스를 만듭니다.
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. */ public class RestaurantResource { RestaurantRepository restaurantRepository; /** * Retrieves all restaurants from the database. * * @return List of all restaurants */ 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 */ 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 */ public Response getRestaurantsByCuisine( 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값을 제공하는 레스토랑을 나타내는 문서를 검색합니다.
테스트 클래스를 만듭니다.
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. */ public class RestaurantRepositoryTest { RestaurantRepository restaurantRepository; public void testRetrieveRestaurants() { // Test repository injection and MongoDB connection assertThat(restaurantRepository).isNotNull(); } 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 실행 하고 엔드포인트를 테스트합니다.
테스트를 실행합니다.
먼저 프로젝트 디렉토리 에서 다음 명령을 실행 테스트 제품군을 실행 .
./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] ------------------------------------------------------------------------
REST 엔드포인트를 수동으로 테스트합니다.
별도의 터미널 창 에서 다음 curl 명령을 실행 REST 엔드포인트를 테스트합니다. 각 엔드포인트는 sample_restaurants.restaurants 컬렉션 의 레스토랑 정보가 포함된 JSON 데이터를 반환합니다. 성공적인 하면 명령이 샘플 출력과 유사한 데이터를 반환합니다.
모든 레스토랑을 조회합니다.
curl http://localhost:8080/restaurants/ [{"id":"...","name":"Morris Park Bake Shop","borough":"Bronx","cuisine":"Bakery"}, {"id":"...","name":"Wilken'S Fine Food","borough":"Brooklyn","cuisine":"Delicatessen"}, {"id":"...","name":"Taste The Tropics Ice Cream","borough":"Brooklyn","cuisine":"Ice Cream, Gelato, Yogurt, Ices"}, {"id":"...","name":"Carvel Ice Cream","borough":"Queens","cuisine":"Ice Cream, Gelato, Yogurt, Ices"}, ...] 이름에
"Moon"이(가) 포함된 퀸즈의 레스토랑을 조회합니다.curl http://localhost:8080/restaurants/browse [{"id":"...","name":"Somoon","borough":"Queens","cuisine":"Asian"}, {"id":"...","name":"New Moon Star Restaurant","borough":"Queens","cuisine":"Chinese"}, {"id":"...","name":"Moon Tikka Grill","borough":"Queens","cuisine":"Indian"}, {"id":"...","name":"Silver Moon Diner","borough":"Queens","cuisine":"American"}, {"id":"...","name":"Mooney'S Public House","borough":"Queens","cuisine":"Irish"}, {"id":"...","name":"Moon Light Crill Rest.","borough":"Queens","cuisine":"Indian"}, {"id":"...","name":"Full Moon Cafe","borough":"Queens","cuisine":"Café/Coffee/Tea"}, {"id":"...","name":"Pacific Moon","borough":"Queens","cuisine":"Chinese"}, {"id":"...","name":"Moon Palace Kitchen","borough":"Queens","cuisine":"Chinese"}, {"id":"...","name":"Honey Moon Coffee Shop 1766096115682","borough":"Queens","cuisine":"Café/Coffee/Tea"}, {"id":"...","name":"Honey Moon Coffee Shop","borough":"Queens","cuisine":"Café/Coffee/Tea"}] 요리 유형별로 레스토랑을 조회합니다.
다음 명령은
cuisine값이"Czech"인 레스토랑을 쿼리하지만 이 매개변수를 모든 요리로 바꿀 수 있습니다.curl http://localhost:8080/restaurants/cuisine/Czech [{"id":"...","name":"Koliba Restaurant","borough":"Queens","cuisine":"Czech"}, {"id":"...","name":"Milan'S Restaurant","borough":"Brooklyn","cuisine":"Czech"}, {"id":"...","name":"Bohemian Beer Garden","borough":"Queens","cuisine":"Czech"}, {"id":"...","name":"Hospoda","borough":"Manhattan","cuisine":"Czech"}, {"id":"...","name":"Olde Prague Tavern","borough":"Queens","cuisine":"Czech"}, {"id":"...","name":"Brooklyn Beet Company","borough":"Brooklyn","cuisine":"Czech"}]
Quarkus 퀵 스타트 튜토리얼을 완료한 것을 축하합니다! 이 단계를 완료하면 MongoDB deployment 에 연결하고, 샘플 레스토랑 데이터에 대한 쿼리를 실행하고, curl 명령을 사용하여 테스트할 수 있는 HTTP 엔드포인트를 통해 결과를 노출하는 Java Quarkus REST API 갖게 됩니다.
추가 리소스
Quarkus, JNoSQL, MongoDB 에 대해 자세히 학습 다음 리소스를 참조하세요.
Quarkus 문서