对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

从 KMongo 迁移

Overview

本页面对官方MongoDB Kotlin驱动程序和社区开发的 KMongo驱动程序的大多数区别进行了高级比较。您可以使用此页面来确定从已弃用的 KMongo驱动程序迁移到官方MongoDB Kotlin驱动程序需要进行哪些更改。

KMongo 是一个流行的社区开发的库，用于在 Kotlin 应用程序中使用 MongoDB。它是在官方 Kotlin 驱动程序创建之前为满足 Kotlin Community 的需求而创建的 Java 驱动程序的包装器。

重要

自 2023 年 7 月起，KMongo 已被标记为已弃用。

MongoDB Kotlin 驱动程序是官方支持和维护的适用于 Kotlin 的 MongoDB 驱动程序。它由 MongoDB 团队开发。

尽管这两个驱动程序都支持同步和异步操作，但本页上的示例将使用基于异步协程的操作。

Kotlin驱动程序与 KMongo 的差异

Kotlin 驱动程序是 Kotlin 的官方 MongoDB 驱动程序。 它由 MongoDB 团队开发，为 Kotlin 应用程序连接到 MongoDB 并处理数据提供原生 API。 它是通过包装MongoDB Java 驱动程序来实现的。

KMongo 是一个流行的社区开发的库，用于在 Kotlin 应用程序中使用 MongoDB。它是在官方 Kotlin 驱动程序创建之前为满足 Kotlin Community 的需求而创建的 Java 驱动程序的包装器。

重要

自 2023 年 7 月起，KMongo 已被标记为已弃用。

Kotlin 驱动程序是与 KMongo 创建者 Julien Buret 合作开发的，旨在为用户提供官方支持的驱动程序。

官方 Kotlin 驱动程序和 KMongo 通常具有相似的 API。 Kotlin 驱动程序和 KMongo 之间的显着相似之处包括：

  • 支持同步和基于协程的操作

  • 支持使用数据类表示 MongoDB 文档

  • 支持 KotlinX 序列化

  • 支持MongoDB 增删改查 API和聚合API

虽然官方 Kotlin 驱动程序和 KMongo 很相似，但存在一些关键区别：

  • 官方驱动程序没有内置对 reactor、rxjava2、Jackson 或 GSON 的支持。

  • 官方驱动程序不支持 MongoDB Shell 命令。

连接到 MongoDB cluster

这两个驱动程序都允许您从 Kotlin 应用程序连接到 MongoDB 集群并与之通信。

要使用MongoDB Kotlin驱动程序连接到MongoDB 集群：

import com.mongodb.kotlin.client.coroutine.MongoClient
data class Jedi(val name: String, val age: Int)
// Replace the placeholder with your MongoDB deployment's connection stringval uri = CONNECTION_STRING_URI_PLACEHOLDER
val mongoClient = MongoClient.create(uri)
val database = mongoClient.getDatabase("test")// Get a collection of documents of type Jedival collection = database.getCollection<Jedi>("jedi")

有关更多信息，请参阅连接到 MongoDB文档。

CRUD 和聚合

这两个驱动程序都支持所有 MongoDB CRUD API 和聚合操作。

提示

如果您习惯使用 KMongo 中提供的中缀表示法构造查询筛选条件，则还可以使用此表示法通过 mongodb-driver-kotlin-extensions包中的扩展方法在官方Kotlin驱动程序中创建过滤器。选择 Kotlin Driver Extensions标签页，查看在Kotlin驱动程序中使用此查询语法的示例。

MongoDB Kotlin驱动程序还为所有基本增删改查操作提供了函数：

// Insert a documentval jedi = Jedi("Luke Skywalker", 19)collection.insertOne(jedi)
// Find a documentval luke = collection.find(Jedi::name.name, "Luke Skywalker")val jedis = collection.find(lt(Jedi::age.name, 30)).toList()
// Update a documentval filter = Filters.eq(Jedi::name.name, "Luke Skywalker")val update = Updates.set(Jedi::age.name, 20)collection.updateOne(filter, update)
// Delete a documentval filter = Filters.eq(Jedi::name.name, "Luke Skywalker")collection.deleteOne(filter)

您可以使用 aggregate() 方法和 pipeline 函数构建聚合管道：

data class Results(val avgAge: Double)
val resultsFlow = collection.aggregate<Results>(    listOf(      Aggregates.match(Filters.ne(Jedi::name.name, "Luke Skywalker")),      Aggregates.group("\$${Jedi::name.name}",          Accumulators.avg("avgAge", "\$${Jedi::age.name}"))    ))resultsFlow.collect { println(it) }

有关更多信息，请参阅CRUD和聚合文档。

构建查询

这两个驱动程序都支持使用属性引用的类型安全查询。

提示

如果您习惯使用 KMongo 中提供的中缀表示法构造查询筛选条件，则还可以使用此表示法通过 mongodb-driver-kotlin-extensions包中的扩展方法在官方Kotlin驱动程序中创建过滤器。选择 Kotlin Driver Extensions标签页，查看在Kotlin驱动程序中使用此查询语法的示例。

MongoDB Kotlin驱动程序使用 Builders API来构造查询。 或者，您可以使用 Document 类。

data class Person(val name: String, val email: String, val gender: String, val age: Int)data class Results(val email: String)
val collection = database.getCollection<Person>("people")
// Using Buildersval filter = and(eq("gender", "female"), gt("age", 29))val projection = fields(excludeId(), include("email"))val results = collection.find<Results>(filter).projection(projection)
// Using Document classval filter = Document().append("gender", "female").append("age", Document().append("\$gt", 29))val projection = Document().append("_id", 0).append("email", 1)val results = collection.find<Results>(filter).projection(projection)

要将 KMongo 字符串查询映射到 Kotlin 驱动程序，您可以使用JsonObject类。

val query = JsonObject("{\"name\": \"Gabriel Garc\\u00eda M\\u00e1rquez\"}")val jsonResult = collection.find(query).firstOrNull()

有关更多信息，请参阅以下 Kotlin 驱动程序文档：

数据类型

这两个驱动程序都支持使用Kotlin数据类和 Document 类对存储在MongoDB集合中的数据进行建模。 Document 类允许您以灵活的格式对MongoDB集合中表示的数据进行建模。

您可以使用数据类和 Document 类，通过MongoDB Kotlin驱动程序对数据进行建模：

// With data classdata class Movie(val title: String, val year: Int, val rating: Float)
val dataClassCollection = database.getCollection<Movie>("movies")val movieDataClass = dataClassCollection.findOneOrNull()val movieNameDataClass = movieDataClass.title
// With Document classval documentCollection = database.getCollection<Movie>("movies")val movieDocument = documentCollection.findOneOrNull()val movieTitleDocument = movieDocument.getString("title")

数据序列化

这两个驱动程序都支持在 Kotlin 中将数据对象与 BSON 进行序列化和反序列化。

您可以使用自动数据类编解码器和 kotlinx.serialization 库在Kotlin驱动程序中序列化数据类。该驱动程序提供了一个高效的 Bson 序列化器，用于处理Kotlin对象到BSON数据的序列化。

@Serializabledata class LightSaber(    @SerialName("_id") // Use instead of @BsonId    @Contextual val id: ObjectId?,    val color: String,    val qty: Int,    @SerialName("brand")    val manufacturer: String = "Acme" // Use instead of @BsonProperty)

要了解更多信息，请参阅Kotlin 序列化文档。

如果使用Document类表示collection，则可以使用.toJson()方法将其序列化为 JSON 和 EJSON：

val document = Document("_id", 1).append("color", "blue")
// Serialize to JSONdocument.toJson()
// Serialize to EJSONval settings = JsonWriterSettings.builder().outputMode(JsonMode.STRICT).build()val json = doc.toJson(settings)

要了解有关使用Document类序列化数据的更多信息，请参阅文档数据格式 - 扩展 JSON文档。

同步和异步支持

这两个驱动程序都支持同步和异步操作。

MongoDB Kotlin驱动程序还具有用于同步和异步操作的单独库。但是，Kotlin驱动程序仅内置支持将协程作为异步范例。MongoDB Kotlin驱动程序目前不支持其他异步范例，例如响应式流、Reactor 或 RxJava2。

驱动
安装包

同步

com.mongodb.kotlin.client

协程

com.mongodb.kotlin.client.coroutine

与 KMongo 不同，如果要编写异步代码，只需导入相关包即可。

要编写同步代码：

import com.mongodb.kotlin.client.MongoClient
// Instantiate your collectiondata class Jedi(val name: String, val age: Int)val uri = "<your-connection-string">val mongoClient = MongoClient.create(uri)val database = mongoClient.getDatabase("test")val collection = database.getCollection<Jedi>("jedi")
// Synchronous operationsval jedi = Jedi("Luke Skywalker", 19)collection.insertOne(jedi)

要编写异步协程代码，请执行以下操作：

import com.mongodb.kotlin.client.coroutine.MongoClient
// Instantiate your collectiondata class Jedi(val name: String, val age: Int)val uri = "<your-connection-string">val mongoClient = MongoClient.create(uri)val database = mongoClient.getDatabase("test")val collection = database.getCollection<Jedi>("jedi")
runBlocking {
  // Async operations  val jedi = Jedi("Luke Skywalker", 19)  collection.insertOne(jedi)}

下一步

现在您已经了解了 KMongo 和 MongoDB Kotlin 驱动程序之间的区别，请参阅快速入门以开始使用 KMongo Kotlin 驱动程序。

后退
版本说明
来年
升级
给本页内容打分

在此页面上