YeLogs.com
知識庫

知識庫 / REST RSS 訂閱

使用 MongoDB 和 Quarkus 入門指南

NoSQL,REST
HongKong
6
03:35 AM · Dec 06 ,2025

1. 簡介

Quarkus 是一款流行的 Java 框架，針對創建內存佔用最小、啓動速度快的應用程序進行了優化。

與 MongoDB（一個流行的 NoSQL 數據庫）結合使用時，Quarkus 提供了一個強大的工具包，用於開發高性能、可擴展的應用程序。

在本教程中，我們將探索如何使用 Quarkus 配置 MongoDB、實現基本 CRUD 操作，以及使用 Panache（Quarkus 的對象文檔映射器 ODM）簡化這些操作。

2. 配置

2.1. Maven 依賴

要使用 MongoDB 與 Quarkus 結合，我們需要包含 quarkus-mongodb-client 依賴項：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-mongodb-client</artifactId>
    <version>3.13.0</version>
</dependency>

此依賴項提供必要的工具，用於使用 MongoDB Java 客户端與 MongoDB 數據庫進行交互。

2.2. 運行 MongoDB 數據庫

為了本文，我們將 MongoDB 運行在 Docker 容器中。 這種方式在無需在我們的機器上直接安裝 MongoDB 的情況下，設置 MongoDB 實例非常方便。

我們首先從 Docker Hub 拉取 MongoDB 鏡像：

docker pull mongo:latest

開始一個新的容器：

docker run --name mongodb -d -p 27017:27017 mongo:latest

2.3. 配置 MongoDB 數據庫

要配置的主要屬性是訪問 MongoDB 的 URL。 幾乎所有的配置都可以包含在 連接字符串 中。

我們可以配置 MongoDB 客户端用於多節點副本集，但在我們的示例中，我們將使用本地主機上的單個實例：localhost：

quarkus.mongodb.connection-string = mongodb://localhost:27017

3. 基本 CRUD 操作

現在我們已經準備好數據庫和項目，並已連接，讓我們使用 Quarkus 提供的默認 MongoDB 客户端來實現基本 CRUD（創建、讀取、更新、刪除）操作。

3.1. 定義實體

在本節中，我們將定義 Article 實體，它代表我們在 MongoDB 集合中的文檔：

public class Article {
    @BsonId
    public ObjectId id;
    public String author;
    public String title;
    public String description;
    
    // getters and setters 
}

我們的類包含用於 id、作者、標題和描述的字段。 ObjectId 是 BSON（JSON 的二進制表示）類型，用作 MongoDB 文檔的默認標識符。 “@BsonId” 註解指定一個字段為 MongoDB 文檔的標識符（_id）。

將其應用於字段時，表示該字段應映射到 MongoDB 集合中的 _id 字段。 結合使用這些功能，我們確保每個 Article 文檔都有一個 MongoDB 可以用於索引和高效檢索文檔的唯一標識符。

3.2. 定義倉庫

本節將創建 <em >ArticleRepository</em> 類，使用 <em >MongoClient</em> 在 <em >Article</em> 實體上執行 CRUD 操作。該類將管理與 <em >MongoDB</em> 數據庫的連接，並提供創建、讀取、更新和刪除 <em >Article</em> 文檔的方法。

首先，我們將使用依賴注入獲取 <em >MongoClient</em> 實例：

@Inject
MongoClient mongoClient;

這使得我們能夠與 MongoDB 數據庫進行交互，而無需手動管理連接。

我們定義一個輔助方法 getCollection()，用於從 articles 數據庫獲取 articles 集合：

private MongoCollection<Article> getCollection() {
    return mongoClient.getDatabase("articles").getCollection("articles", Article.class);
}

現在，我們可以使用集合提供程序執行基本 CRUD 操作：

public void create(Article article) {
    getCollection().insertOne(article);
}

create() 方法將一個新的 Article 文檔插入到 MongoDB 集合中。該方法使用 insertOne() 將提供的文章對象添加到其中，確保它作為新的條目存儲在 articles 集合中。

public List<Article> listAll() {
    return getCollection().find().into(new ArrayList<>());
}

listAll() 方法從 MongoDB 集合中檢索所有 Article 文檔。它利用find() 方法來查詢所有文檔並將其收集起來。 還可以指定我們想要返回的集合類型。

public void update(Article article) {
    getCollection().replaceOne(new org.bson.Document("_id", article.id), article);
}

update() 方法用提供的對象替換現有的 Article 文檔。它使用 replaceOne() 查找具有匹配的 _id 的文檔，並使用新數據進行更新。

public void delete(String id) {
    getCollection().deleteOne(new org.bson.Document("_id", new ObjectId(id)));
}

delete() 方法通過其 id 從集合中刪除 Article 文檔。它構造一個過濾器來匹配 _id，並使用 deleteOne 來刪除匹配此過濾器的第一個文檔。

3.3. 定義資源

作為簡短的示例，我們將僅限於定義資源和倉庫，目前不實施服務層。

現在，我們只需要創建我們的資源，注入倉庫，併為每個操作創建一個方法：

@Path("/articles")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ArticleResource {
    @Inject
    ArticleRepository articleRepository;

    @POST
    public Response create(Article article) {
        articleRepository.create(article);
        return Response.status(Response.Status.CREATED).build();
    }

    @GET
    public List<Article> listAll() {
        return articleRepository.listAll();
    }

    @PUT
    public Response update(Article updatedArticle) {
        articleRepository.update(updatedArticle);
        return Response.noContent().build();
    }

    @DELETE
    @Path("/{id}")
    public Response delete(@PathParam("id") String id) {
        articleRepository.delete(id);
        return Response.noContent().build();
    }
}

3.4. 測試我們的API

為了確保我們的API正常工作，我們可以使用 curl，這是一種用於通過各種網絡協議傳輸數據的強大命令行工具。

我們將向數據庫添加一篇新文章。我們使用HTTP POST方法將表示文章的JSON負載發送到/articles端點：

curl -X POST http://localhost:8080/articles \
-H "Content-Type: application/json" \
-d '{"author":"John Doe","title":"Introduction to Quarkus","description":"A comprehensive guide to the Quarkus framework."}'

為了驗證我們的文章是否已成功存儲，我們可以使用 HTTP GET 方法從數據庫中檢索所有文章：

curl -X GET http://localhost:8080/articles

通過運行此操作，我們將會得到一個包含數據庫中所有當前存儲的文章的 JSON 數組：

[
  {
    "id": "66a8c65e8bd3a01e0a509f0a",
    "author": "John Doe",
    "title": "Introduction to Quarkus",
    "description": "A comprehensive guide to Quarkus framework."
  }
]

4. 使用 Panache 與 MongoDB

Quarkus 提供了一個額外的抽象層，稱為 Panache，它簡化了數據庫操作並減少了樣板代碼。藉助 Panache，我們可以更專注於業務邏輯，而不是數據訪問代碼。 讓我們看看如何使用 Panache 實現相同的 CRUD 操作。

4.1. Maven 依賴

要使用 Panache 與 MongoDB 集成，我們需要添加 quarkus-mongodb-panache 依賴項：

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-mongodb-panache</artifactId>
    <version>3.13.0</version>
</dependency>

4.2. 定義實體

當使用 Panache 時，我們的實體類將繼承 PanacheMongoEntity，它提供內置的方法，用於常見的數據庫操作。我們還將使用 @MongoEntity 註解來定義我們的 MongoDB 集合：

@MongoEntity(collection = "articles", database = "articles")
public class Article extends PanacheMongoEntityBase {
    private ObjectId id;
    private String author;
    private String title;
    private String description;

    // getters and setters
}

4.3. 定義倉庫

使用 Panache，我們通過擴展 PanacheMongoRepository 創建倉庫。這使我們能夠獲得 CRUD 操作，而無需編寫樣板代碼：

@ApplicationScoped
public class ArticleRepository implements PanacheMongoRepository<Article> {}

當擴展 PanacheMongoRepository 類時，可以利用多種常用方法執行 CRUD 操作和管理 MongoDB 實體。

現在，可以使用諸如 persist()、listAll() 或 findById 等方法直接使用。

4.4. 定義資源

現在，我們只需要創建我們的新資源，該資源將使用新的倉庫，而無需所有冗餘的代碼：

@Path("/v2/articles")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ArticleResource 
    @Inject
    ArticleRepository articleRepository;

    @POST
    public Response create(Article article) {
        articleRepository.persist(article);
        return Response.status(Response.Status.CREATED).build();
    }

    @GET
    public List<Article> listAll() {
        return articleRepository.listAll();
    }

    @PUT
    public Response update(Article updatedArticle) {
        articleRepository.update(updatedArticle);
        return Response.noContent().build();
    }

    @DELETE
    @Path("/{id}")
    public Response delete(@PathParam("id") String id) {
        articleRepository.delete(id);
        return Response.noContent().build();
    }
}

4.5. 測試 API

我們可以使用與其它示例相同的 <em >curl</em> 命令來測試新的 API。唯一更改的是調用的 endpoint，這次調用的是 <em >/v2/articles</em> API。我們將創建新的文章：

curl -X POST http://localhost:8080/v2/articles \
-H "Content-Type: application/json" \
-d '{"author":"John Doe","title":"Introduction to MongoDB","description":"A comprehensive guide to MongoDB."}'

我們將會檢索現有的文章：

curl -X GET http://localhost:8080/v2/articles

5. 結論

在本文中，我們探討了如何將 MongoDB 集成到 Quarkus 中。我們配置了 MongoDB 並將其在 Docker 容器中運行，從而為我們的應用程序設置了一個健壯且可擴展的環境。我們演示了使用默認的 Mongo 客户端實施 CRUD 運算的方法。

此外，我們介紹了 Panache，Quarkus 的對象文檔映射器 (ODM)，它通過減少樣板代碼，極大地簡化了數據訪問。

user avatar
0 位用戶收藏了這個故事！
收藏

發佈 評論

Some HTML is okay.