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

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_restaurants
quarkus.mongodb.connection-string=<connection string>

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

5

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 엔드포인트를 생성합니다.

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.
*
*/
@Repository
public 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.
*/
@QuarkusTest
public 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/
    [{"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"},
    ...]
  2. 이름에 "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"}]
  3. 요리 유형별로 레스토랑을 조회합니다.

    다음 명령은 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 에 대해 자세히 학습 다음 리소스를 참조하세요.