Kotlin 驱动程序快速入门

在此页面上

简介

设立您的项目
Install Kotlin
创建项目
添加 MongoDB 作为依赖项
添加序列化库依赖项
创建 MongoDB 集群
连接到集群
从应用程序查询 MongoDB 集群
使用 Document 类（备选）
后续步骤

简介

本指南向您展示如何创建使用Kotlin驾驶员连接到MongoDB Atlas 群集的应用程序程序。如果您希望使用不同的驾驶员或编程语言连接MongoDB ，请参阅官方 MongoDB 驱动程序的MongoDB。

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

MongoDB Atlas 是完全托管的云数据库服务，可在 MongoDB 集群托管数据。通过本指南，您可以了解如何开始使用自己的免费集群。

提示

要查看其他示例来了解如何在 Kotlin 中构建连接到 MongoDB Atlas 的应用程序，请参阅 MongoDB Kotlin Driver 开发者入门教程。

设立您的项目

Install Kotlin

确保您的系统已安装Kotlin并在 JDK 1.8或更高版本上运行。有关Kotlin/ Java虚拟机（JVM）开发入门的更多信息，请参阅 Kotlin/ Java虚拟机（JVM）入门在Kotlin语言文档中。

创建项目

本指南向您介绍如何使用 Gradle 或 Maven 添加 MongoDB Kotlin 驱动程序依赖项。我们建议您使用 IntelliJ IDEA 或 Eclipse IDE 等集成开发环境配置 Gradle 或 Maven，以构建和运行项目。

如果您未使用 IDE，请参阅创建新的 Gradle 版本指南或构建 Maven 指南，详细了解如何设置项目。

添加 MongoDB 作为依赖项

如果您使用 Gradle 要管理您的软件包，请将以下条目添加到您的build.gradle.kts 依赖项列表中：

build.gradle.kts

dependencies {
    implementation("org.mongodb:mongodb-driver-kotlin-coroutine:5.2.0")
}

如果您使用的是 Maven 要管理您的软件包，请将以下条目添加到您的pom.xml 依赖项列表中：

pom.xml

<dependencies>
    <dependency>
        <groupId>org.mongodb</groupId>
        <artifactId>mongodb-driver-kotlin-coroutine</artifactId>
        <version>5.2.0</version>
    </dependency>
</dependencies>

配置依赖项后，运行依赖项管理器并在 IDE 中刷新项目，确保它们可用于您的项目。

添加序列化库依赖项

要使驱动程序能够在 Kotlin 对象和 BSON（MongoDB 中文档的数据格式）之间进行转换，您还必须将以下一个或两个序列化包添加到您的应用程序中：

bson-kotlinx （推荐）
bson-kotlin

如果使用 Gradle 管理您的包，请将以下条目之一添加到您的 build.gradle.kts 依赖项列表中：

build.gradle.kts

implementation("org.mongodb:bson-kotlinx:5.2.0")
// OR
implementation("org.mongodb:bson-kotlin:5.2.0")

如果使用 Maven 管理您的包，请将以下条目之一添加到您的 pom.xml 依赖项列表中：

pom.xml

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlinx</artifactId>
    <version>5.2.0</version>
</dependency>
<!--OR-->
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>bson-kotlin</artifactId>
    <version>5.2.0</version>
</dependency>

配置依赖项后，运行依赖项管理器并在 IDE 中刷新项目，确保它们可用于您的项目。

要学习；了解有关这些包的详情，请参阅 Kotlin序列化。

创建 MongoDB 集群

设置 Kotlin 项目依赖项后，创建 MongoDB 集群，用于存储和管理数据。完成 Atlas 入门教程，以设置新的 Atlas 帐户、创建和启动免费层 MongoDB 集群以及加载示例数据集。

完成“Atlas 入门”教程中的步骤后，您应当在 Atlas 中部署了一个新的 MongoDB 集群、一个新的数据库用户，并且有示例数据加载到集群中。

连接到集群

此步骤说明如何创建并运行一个应用程序，该应用程序使用 Kotlin 驱动程序连接到 MongoDB 集群并对样本数据运行查询。

首先，您必须通过在代码中包含连接字符串 来指定驱动程序如何连接到 MongoDB 集群。此字符串包含有关集群的主机名或 IP 地址和端口、身份验证机制、用户凭证以及其他连接选项的信息。

如果您要连接到不在 Atlas 上托管的实例或集群，请参阅连接指南的连接到 MongoDB 的其他方式部分，了解如何格式化连接字符串。

要检索您在上一步中创建的集群和用户的连接字符串，请登录您的 Atlas 帐户并导航到部署下的 Database（数据库）页面，然后单击集群的 Connect（连接）按钮，如下图所示：

选择 Drivers 选项进行连接，然后从驱动程序列表中选择 Kotlin，从版本下拉列表中选择 4.10 or later。

接下来，单击下图中突出显示的 Copy（复制）图标，将连接字符串 复制到剪贴板：

将您的 Atlas 连接字符串保存在安全的位置，以便您在下一步操作时能访问到。

从应用程序查询 MongoDB 集群

接下来，在您的项目中创建名为 QuickStartDataClassExample.kt 的文件。

将以下样本代码复制到该文件中，并将 uri 变量的值替换为前面步骤中保存的 MongoDB Atlas 连接字符串。将连接字符串的 "<password>" 占位符替换为您为具有 atlasAdmin 权限的用户设置的密码：

QuickStartDataClassExample.kt

import com.mongodb.client.model.Filters.eq
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.github.cdimascio.dotenv.dotenv
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
// Create data class to represent a MongoDB document
data class Movie(val title: String, val year: Int, val cast: List<String>)
fun main() {
    // Replace the placeholder with your MongoDB deployment's connection string
    val uri = CONNECTION_STRING_URI_PLACEHOLDER
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    // Get a collection of documents of type Movie
    val collection = database.getCollection<Movie>("movies")
    runBlocking {
        val doc = collection.find(eq("title", "Back to the Future")).firstOrNull()
        if (doc != null) {
            println(doc)
        } else {
            println("No matching documents found.")
        }
    }
    mongoClient.close()
}

注意

此示例使用 Kotlin 数据类对 MongoDB 数据建模。

当您运行 main 函数时，应用程序会输出与查询匹配的电影文档的详细信息，如以下输出所示：

Movie(
   title=Back to the Future,
   year=1985,
   cast=[Michael J. Fox, Christopher Lloyd, Lea Thompson, Crispin Glover]
)

提示

数据类

要了解使用数据类存储和检索数据的更多信息，请参阅文档数据格式：数据类指南。

如果未看到任何输出或收到错误，请检查应用程序中是否包含正确的连接字符串。另外，确认您已成功将示例数据集加载到 MongoDB Atlas 集群中。

重要

使用 TLS v1.3 时的已知连接问题

如果在连接 MongoDB 实例时遇到以下错误，则必须将 JDK 更新到最新的补丁版本：

javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request

此异常是在特定版本的 JDK 中使用 TLS 1.3 协议时出现的已知问题，但已在以下 JDK 版本中修复：

JDK 11.0.7
JDK 13.0.3
JDK 14.0.2

要解决此报错，请将您的 JDK 更新到上述补丁版本之一，或者更高版本。

完成此步骤后，您应该有一个正常运行的应用程序，它使用 Kotlin 驱动程序连接到 MongoDB 集群、对示例数据运行查询并输出结果。

使用 Document 类（备选）

上一节演示了如何使用 Kotlin 数据类对示例集合运行查询以检索数据。本节介绍如何使用 Document 类存储和检索来自 MongoDB 的数据。

在名为 QuickStartDocumentExample.kt 的新文件中，粘贴以下示例代码，对 MongoDB Atlas 中的示例数据集运行查询。将 uri 变量的值替换为 MongoDB Atlas 连接字符串：

QuickStartDocumentExample.kt

import com.mongodb.client.model.Filters.eq
import com.mongodb.kotlin.client.coroutine.MongoClient
import io.github.cdimascio.dotenv.dotenv
import kotlinx.coroutines.flow.firstOrNull
import kotlinx.coroutines.runBlocking
import org.bson.Document
fun main() {
    // Replace the placeholder with your MongoDB deployment's connection string
    val uri = CONNECTION_STRING_URI_PLACEHOLDER
    val mongoClient = MongoClient.create(uri)
    val database = mongoClient.getDatabase("sample_mflix")
    val collection = database.getCollection<Document>("movies")
    runBlocking {
        val doc = collection.find(eq("title", "Back to the Future")).firstOrNull()
        if (doc != null) {
            println(doc.toJson())
        } else {
            println("No matching documents found.")
        }
    }
    mongoClient.close()
}

当您运行 main 函数时，应用程序会输出与查询匹配的电影文档的详细信息，如以下输出所示：

{
  _id: ...,
  plot: 'A young man is accidentally sent 30 years into the past...',
  genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ],
  ...
  title: 'Back to the Future',
  ...
}

如果未看到任何输出或收到错误，请检查应用程序中是否包含正确的连接字符串。另外，确认您已成功将示例数据集加载到 MongoDB Atlas 集群中。

后续步骤

要了解有关 Kotlin 驱动程序的更多信息，请参阅基础知识指南，详细了解相关概念以及执行不同任务的代码示例。

后退

MongoDB Kotlin 驱动程序

来年

快速参考