개요
이 가이드 에서는 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의 유연한 document model 과 함께 Quarkus의 빠른 스타트업 시간과 효율적인 리소스 사용을 활용할 수 있습니다. 이 조합은 유형 안전성, 확장성 및 빠른 개발 주기가 필요한 애플리케이션을 지원합니다. MongoDB 와 Quarkus를 사용하여 마이크로서비스, 클라우드 네이티브 API 또는 고성능과 낮은 리소스 소비가 필요한 시스템과 같은 실제 애플리케이션을 만들 수 있습니다.
빠른 시작 튜토리얼
이 튜토리얼에서는 MongoDB 와 Quarkus를 사용하는 REST API 빌드 방법을 보여줍니다. 애플리케이션 샘플 레스토랑 데이터에 액세스하고, 데이터를 쿼리하고, RESTful 엔드포인트를 통해 결과를 반환합니다. 이 튜토리얼에는 MongoDB Atlas 에서 호스팅되는 MongoDB 클러스터 에 연결하기 위한 지침도 포함되어 있습니다.
팁
Quarkus 없이 Java 드라이버를 사용하여 MongoDB에 연결하려면 Java 드라이버 시작하기 튜토리얼을 참조하세요.
프로젝트 설정
이 섹션의 단계에 따라 프로젝트 종속성을 설치하고, Atlas 클러스터를 만들고, 애플리케이션 구조를 설정하세요.
전제 조건을 확인합니다.
빠른 시작 애플리케이션 만들려면 개발 환경에 다음 소프트웨어를 설치하세요.
전제 조건 | 참고 사항 |
|---|---|
JDK 버전 21 이상을 설치합니다. | |
버전 3.8.1 이상을 사용하세요. | |
이 명령줄 인터페이스를 사용하였 터미널에서 Quarkus 프로젝트를 생성하고 관리할 수 있습니다. | |
코드 편집기 | 원하는 코드 편집기를 사용하세요. |
터미널 앱 및 shell | MacOS 사용자의 경우 터미널 또는 유사한 앱 사용하세요. Windows 사용자의 경우 PowerShell 또는 명령 프롬프트를 사용하세요. |
MongoDB Atlas 클러스터를 생성합니다.
MongoDB Atlas 는 MongoDB 배포서버를 호스팅하다 완전 관리형 클라우드 데이터베이스 서비스입니다. MongoDB 배포서버 없는 경우, MongoDB 시작하기 튜토리얼을 완료하여 MongoDB 클러스터 무료로 만들 수 있습니다. MongoDB 시작하기 튜토리얼에서는 이 튜토리얼에서 사용되는 sample_restaurants 데이터베이스 포함하여 샘플 데이터 세트를 클러스터 에 로드하는 방법도 보여줍니다.
MongoDB cluster 에 연결하려면 연결 문자열 사용해야 합니다. 연결 문자열 조회 방법을 학습하려면 MongoDB 시작하기 튜토리얼의 연결 문자열 추가하기 섹션을 참조하세요.
중요
연결 string 을 안전한 위치 에 저장합니다.
데이터베이스 연결을 구성합니다.
src/main/resources/application.properties 파일 로 이동하여 다음 구성 속성을 추가합니다.
jnosql.document.database=sample_restaurantsquarkus.mongodb.connection-string=<connection string>이 코드는 MongoDB cluster 의 sample_restaurants 데이터베이스 에 대한 연결을 구성합니다. <connection string> 자리 표시자를 이전 단계에서 저장한 연결 문자열로 바꿉니다.
템플릿 파일을 정리합니다.
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.javadel src/main/java/org/acme/Car.javadel src/main/java/org/acme/Garage.javadel src/test/java/org/acme/GarageTest.javadel src/main/java/org/acme/GreetingResource.javadel src/test/java/org/acme/GreetingResourceIT.javadel src/test/java/org/acme/GreetingResourceTest.java애플리케이션 만들기
프로젝트 구조 및 종속성을 설정한 후 이 섹션의 단계에 따라 데이터 모델, 리포지토리 클래스 및 REST 엔드포인트를 생성합니다.
Restaurant 모델을 만듭니다.
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 속성을 문서 필드에 매핑합니다.
리포지토리 클래스를 만듭니다.
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 인스턴스 사용하여 내장 생성, 읽기, 업데이트 및 삭제 메서드에 액세스 할 수도 있습니다.
REST 리소스 클래스를 만듭니다.
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값을 제공하는 레스토랑을 나타내는 문서를 검색합니다.
테스트 클래스를 만듭니다.
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 실행 하고 엔드포인트를 테스트합니다.
테스트를 실행합니다.
먼저 프로젝트 디렉토리 에서 다음 명령을 실행 테스트 제품군을 실행 .
./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/이름에
"Moon"이(가) 포함된 퀸즈의 레스토랑을 조회합니다.curl http://localhost:8080/restaurants/browse요리 유형별로 레스토랑을 조회합니다.
다음 명령은
cuisine값이"Czech"인 레스토랑을 쿼리하지만 이 매개변수를 모든 요리로 바꿀 수 있습니다.curl http://localhost:8080/restaurants/cuisine/Czech
Quarkus 퀵 스타트 튜토리얼을 완료한 것을 축하합니다! 이 단계를 완료하면 MongoDB deployment 에 연결하고, 샘플 레스토랑 데이터에 대한 쿼리를 실행하고, curl 명령을 사용하여 테스트할 수 있는 HTTP 엔드포인트를 통해 결과를 노출하는 Java Quarkus REST API 갖게 됩니다.
추가 리소스
Quarkus, JNoSQL, MongoDB 에 대해 자세히 학습 다음 리소스를 참조하세요.
Quarkus 문서