Docs 菜单
Docs 主页
/
语言
/
Java
/
Java (Sync) 驱动程序
/
连接

创建 MongoClient

在此页面上

在本指南中，您可以了解如何使用 Java 驱动程序连接到 MongoDB Atlas 部署、MongoDB 实例或副本集。

您可以查看示例代码以连接到 Atlas 集群或继续阅读以了解有关 MongoClient 类和连接 URI 的更多信息。

MongoClient

您可以使用 类连接到MongoDB并与之通信。要创建MongoClient MongoClientSettings对象，请使用 MongoClientSettings.builder()方法和链方法指定您的设置。将它们链接起来后，使用build() 方法创建MongoClientSettings 对象。

要学习；了解可用于控制 MongoClient 行为的不同设置，请参阅指定 MongoClient 设置指南。

例子

此示例演示如何指定 ConnectionString：

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
    .applyConnectionString(new ConnectionString("<your connection string>"))
    .build());

注意

连锁订单

设置中的某些选项映射到连接字符串选项。如果在设置和连接字符串中指定相同的选项，则链接这些选项的顺序将决定驱动程序使用的选项。驱动程序使用其读取的最后一项设置。

例如，此代码段包含驱动程序连接到可用套接字的以下时间的设置：

  • 连接字符串在 2 SECONDS 内指定

  • 套接字设置在 5 SECONDS 内指定

MongoClient mongoClient = MongoClients.create(
   MongoClientSettings.builder().applyConnectionString(new ConnectionString("mongodb+srv://<db_username>:<db_password>@<hostname>:<port>/<auth db>?connectTimeoutMS=2000"))
      .applyToSocketSettings(builder ->
      builder.connectTimeout(5L, SECONDS))
      .build());

由于驾驶员最后读取套接字设置选项，因此驾驶员希望在超时前的 5 SECONDS 内连接到可用的套接字。

重要

客户端重用

由于每个 MongoClient 代表一个具有线程安全性的数据库连接池，因此大多数应用程序只需要一个 MongoClient实例，甚至跨多个线程也是如此。所有资源使用限制（例如最大连接数）应用于单个 MongoClient 实例。

提示

当不再需要实例时，始终调用 MongoClient.close() 清理资源。

连接 URI

连接 URI提供驱动程序用于连接到 MongoDB 部署的指令集。该指令集指示驱动程序应如何连接到 MongoDB，以及在连接时应如何运行。下图解释了示例连接 URI 的各个部分：

An example of a connection string that demonstrates the protocol, credentials, hostname or IP, port, and connection options

在此示例中，您将连接到具有 DNS SRV记录的Atlas MongoDB 部署。有关更多信息，请参阅本指南的DNS 服务发现部分。

注意

如果您的部署是在 MongoDB Atlas 上，请参阅 Atlas 驱动程序连接指南，从语言下拉菜单中选择 Java 以检索连接字符串。

如果您要连接到没有 DNS SRV 地址的实例或副本集，则必须为协议使用 mongodb，该协议指定了标准连接字符串格式。

如果您使用基于密码的身份验证机制，则在协议之后，连接字符串将包含您的凭据。将 user 的值替换为您的用户名，将 pass 替换为您的密码。如果您的身份验证机制不需要凭据，请忽略连接 URI 的这一部分。

连接 URI 的下一部分指定主机名或 IP 地址，后跟 MongoDB 实例的端口。在示例中，sample.host 代表主机名，27017 是端口号。替换这些值以参考您的 MongoDB 实例。

连接 URI 的最后一部分包含作为参数的连接选项。在示例中，您设立了两个连接选项：maxPoolSize=20 和 w=majority。有关连接选项的更多信息，请跳至本指南的“指定连接选项”部分。

DNS 服务发现

要使用 DNS 服务发现来查找要连接的服务的 DNS SRV记录，请在连接字符串中指定 SRV 连接格式。如果指定此格式， Java驾驶员将自动重新扫描新主机。您的部署可以将主机添加到其拓扑结构中，而无需更改客户端配置。

以下代码显示了使用 SRV 连接格式的连接字符串：

String uri = "mongodb+srv://<hostname>/";

要学习；了解有关 SRV 连接格式的更多信息，请参阅MongoDB Server手册中的 SRV 连接格式 条目。

Atlas 连接示例

要连接到 Atlas 上的 MongoDB 部署，请创建一个客户端。通过将 MongoClientSettings 对象传递给 MongoClients.create() 构造函数，可以创建一个使用连接字符串和其他客户端选项的客户端。

要实例化 MongoClientSettings 对象，使用构建器方法指定您的连接字符串和任何其他客户端选项，然后调用 build() 方法。将 applyConnectionString() 方法链接到构建器以指定您的连接 URI。

您可以设置 Stable API 版本客户端选项，避免在升级到新版本的 MongoDB Server 时发生重大更改。要了解有关 Stable API 功能的更多信息，请参阅 Stable API 页面。

以下代码展示了在连接到 Atlas 上的 MongoDB 部署时，如何指定连接字符串和 Stable API 客户端选项，并检查连接是否成功：

package fundamentals;
import com.mongodb.*;
import org.bson.BsonDocument;
import org.bson.BsonInt64;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoDatabase;
public class MongoClientConnectionExample {
    public static void main(String[] args) {
        // Replace the placeholder with your Atlas connection string
        String uri = "<connection string>";
        // Construct a ServerApi instance using the ServerApi.builder() method
        ServerApi serverApi = ServerApi.builder()
                .version(ServerApiVersion.V1)
                .build();
        MongoClientSettings settings = MongoClientSettings.builder()
                .applyConnectionString(new ConnectionString(uri))
                .serverApi(serverApi)
                .build();
        // Create a new client and connect to the server
        try (MongoClient mongoClient = MongoClients.create(settings)) {
            MongoDatabase database = mongoClient.getDatabase("admin");
            try {
                // Send a ping to confirm a successful connection
                Bson command = new BsonDocument("ping", new BsonInt64(1));
                Document commandResult = database.runCommand(command);
                System.out.println("Pinged your deployment. You successfully connected to MongoDB!");
            } catch (MongoException me) {
                System.err.println(me);
            }
        }
    }
}

连接 MongoDB 的其他方式

如果要连接到未托管在 Atlas 上的单个 MongoDB 部署或副本集，请参阅以下部分了解如何连接。

连接到本地计算机上的 MongoDB 部署

如果出于开发目的需要在本地计算机上运行 MongoDB 部署，而不是使用 Atlas 集群，则需要完成以下步骤：

  1. 下载 MongoDB Server Community 或 Enterprise 版本。

  2. 安装并配置 MongoDB Server。

  3. 开始部署。

重要

始终防止您的 MongoDB 部署遭到恶意攻击。请参阅我们的安全检查清单，获取安全建议清单。

成功启动 MongoDB 部署后，在驱动程序连接代码中指定连接字符串。

如果 MongoDB 部署在本地运行，您可以使用连接字符串 "mongodb://localhost:<port>"，<port> 是您配置服务器以侦听传入连接的端口号。

如果您需要指定不同的主机名或 IP 地址，请参阅 Server 手册中有关连接字符串的条目。

要测试是否能够连接到部署，请替换连接到 MongoDB Atlas 示例代码中的连接字符串，并运行此代码。

连接到副本集

MongoDB 副本集部署是一组用于存储相同数据集的连接实例。这种实例配置提供了数据冗余和高数据可用性。

要连接到副本集部署，请指定副本集节点主机名（或 IP 地址）和端口号。

如果您无法提供副本集中主机的完整列表，则可以在该副本中指定单个主机或主机子集，并指示驱动程序通过以下方式执行自动发现：

  • 将副本集名称指定为 replicaSet 参数的值

  • 将 false 指定为 directConnection 参数的值

  • 在副本集中指定多个主机

提示

尽管您可以指定副本集中主机的子集，但要包含副本集中的所有主机，以确保驱动程序能够在其中一台主机无法访问时建立连接。

以下示例展示了如何使用 ConnectionString 或 MongoClientSettings 类为 MongoClient 实例指定多个主机。选择与您首选课程相对应的标签页。

ConnectionString connectionString = new ConnectionString("mongodb://host1:27017,host2:27017,host3:27017");
MongoClient mongoClient = MongoClients.create(connectionString);
ServerAddress seed1 = new ServerAddress("host1", 27017);
ServerAddress seed2 = new ServerAddress("host2", 27017);
ServerAddress seed3 = new ServerAddress("host3", 27017);
MongoClientSettings settings = MongoClientSettings.builder()
        .applyToClusterSettings(builder ->
               builder.hosts(Arrays.asList(seed1, seed2, seed3)))
        .build();
MongoClient mongoClient = MongoClients.create(settings);

常见问题解答

本部分回答连接到MongoDB时可能出现的问题。

为什么 Java 驱动程序中有两种类型的MongoClient ？

MongoClient 有两种类型，因为我们希望为新用户提供更简洁的API ，以免因包含多个增删改查常用 AsAPI 而感到困惑。我们希望确保新的增删改查 API在Java包结构中可用，该结构可以与Java 9 中引入的Java模块支持良好配合。

我应该使用哪种类型的MongoClient ？

新应用程序通常使用 com.mongodb.client.MongoClient 接口，该接口支持以下功能：

  • 包含 MongoClientSettings 和 ConnectionString 的配置。您可以使用 com.mongodb.client.MongoClients 类中定义的工厂方法创建此接口的实例。

  • 使用 MongoDatabase 访问增删改查 API ，然后使用 MongoCollection。

如果您需要支持旧版API，请使用 com.mongodb.MongoClient 类，该类支持以下功能：

  • 使用 MongoClientOptions 和 MongoClientURI 进行配置。

  • 使用 DB 访问增删改查 API ，然后使用 DBCollection。您可以使用 getDB() 方法访问权限此API 。

对于需要混合使用新旧 API 的应用程序，com.mongodb.MongoClient 还支持以下功能：

  • 使用 MongoClientSettings 和 ConnectionString 进行配置，唯一的区别是您通过构造函数而不是工厂类创建实例。

  • 使用 MongoDatabase 访问增删改查 API ，然后使用 MongoCollection。您可以使用 getDatabase() 方法访问权限此API 。

如何防止“java.lang.NoClassDefFoundError: com/mongodb/MongoClient”错误？

当 Java 运行时环境在运行时找不到类文件时，可能会遇到java.lang.NoClassDefFoundError异常。 当您尝试运行使用 MongoDB Java 驱动程序的应用程序代码时，必须在类路径中包含相应的驱动程序 JAR 文件。

如果在将 Java 驱动程序 JAR 文件添加到类路径后收到此错误，请检查环境中的以下项目：

  • JAR 文件存在于类路径指定的位置。

  • 类路径语法是正确的。

  • 如果在环境变量中定义类路径，Java 运行时环境将使用该变量。

  • 如果您使用依赖项经理，它不会报告任何无法解决的冲突。

提示

此错误包含包名称和类名称，可帮助您确定类路径中可能缺少哪个驱动程序 JAR。 要找到错误引用的驱动程序 JAR，请检查API 文档中的每个条目。

如何防止“com.mongodb.MongoSecurityException”错误？

如果您在连接到 MongoDB 部署时指定了无效或格式不正确的档案，您的应用程序可能会抛出此异常。

如果在尝试连接到 MongoDB 部署时收到此错误，请检查代码中的以下项目：

  • 连接 URI 对应于正确的 MongoDB 部署。要学习；了解有关设置连接 URI 的更多信息，请参阅连接 URI。

  • 您指定的身份验证机制的凭证是正确的。要学习；了解如何指定凭证，请参阅身份验证机制指南。

  • 您指定的身份验证数据库名称正确。 要了解如何为MongoDB 部署设置用户和角色，请参阅 MongoDB Server文档中的 管理用户和角色 。

如何防止出现“IllegalStateException: state should be: open”（IllegalStateException: state should be: open）错误？

如果您对MongoClient实例调用关闭与 MongoDB 连接的操作，则可能会遇到此异常。 在MongoClient上调用close()方法后，对该实例的任何进一步操作调用都会抛出此异常。

要避免此异常，请不要在对 MongoClient 实例调用close()的任何代码之后调用对实例的操作。

提示

在某些情况下，可能很难找到关闭MongoClient实例的代码。 要查找此异常的潜在来源，请搜索以下案例：

  • 在MongoClient实例上调用close()

  • 对MongoClient实例的操作调用超出了声明MongoClient的 try-with-resources 语句的范围

如果您的应用程序使用框架来托管MongoClient （例如 Spring Boot），请查看该框架的文档，找到托管连接行为的最佳实践。

要了解有关从 Spring Boot 访问 MongoDB 的更多信息，请参阅Spring Boot 和 MongoDB。

后退

连接

来年

指定连接选项