连接指南

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

有关使用 MongoDB 实例进行身份验证的信息，请参阅身份验证。要了解有关将驱动程序与 Java 命名和目录接口 (JNDI) 结合使用的更多信息，请参阅 JNDI。要为与 MongoDB 实例的连接配置 TLS/SSL 安全性，请参阅TLS/SSL。

使用该MongoClients.create()方法构造一个 MongoClient. 由于每个都MongoClient代表一个线程安全的数据库连接池，因此大多数应用程序只需要一个 的实例MongoClient，即使跨多个线程也是如此。所有资源使用限制（例如最大连接数）都适用于单个 MongoClient实例。

提示

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

该连接URI提供了一组指令，该驱动程序使用连接到MongoDB的部署。它指示驱动程序应该如何连接到 MongoDB 以及在连接时应该如何表现。以下示例解释了示例连接 URI 的每个部分：

 

在这个例子中，我们使用标准的连接字符串的格式， mongodb为协议。您还可以使用DNS 种子列表连接格式, mongodb+srv，如果您想要更大的部署灵活性以及无需重新配置客户端即可轮换更改服务器的能力。

笔记

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

如果您使用基于密码的身份验证机制，则连接 URI 的下一部分包含您的凭据。user 用您的用户名和pass密码替换 的值。如果您的身份验证机制不需要凭据，请省略连接 URI 的这一部分。

连接 URI 的下一部分指定主机名或 IP 地址，然后是 MongoDB 实例的端口。在示例中，我们使用sample.host主机名和27017端口。替换这些值以引用您的 MongoDB 实例。

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

以下代码显示了如何使用客户端中的示例连接 URI 连接到 MongoDB。

package fundamentals;

import org.bson.BsonDocument;
import org.bson.BsonInt64;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.MongoClientSettings;
import com.mongodb.MongoException;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoDatabase;

public class RunCommand {
    public static void main(String[] args) {
        // Replace the uri string with your MongoDB deployment's connection string
        String uri = "mongodb://user:pass@sample.host:27017/?maxPoolSize=20&w=majority";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("admin");
            try {
                Bson command = new BsonDocument("ping", new BsonInt64(1));
                Document commandResult = database.runCommand(command);
                System.out.println("Connected successfully to server.");
            } catch (MongoException me) {
                System.err.println("An error occurred while attempting to run a command: " + me);
            }
        }
    }
}

 

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

如果您需要在本地机器上运行 MongoDB 服务器用于开发目的而不是使用 Atlas 集群，则需要完成以下操作：

  1. 下载MongoDB 服务器的社区版 或企业版。
  2. 安装和配置 MongoDB 服务器。
  3. 启动服务器。
重要的

始终保护您的 MongoDB 服务器免受恶意攻击。有关安全建议的列表，请参阅我们的 安全检查表。

成功启动 MongoDB 服务器后，请在驱动程序连接代码中指定连接字符串。

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

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

要测试您是否可以连接到您的服务器，请替换Connect to MongoDB Atlas代码示例中的连接字符串并运行它。

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

要连接到副本集部署，请指定一个或多个副本集成员的主机名（或 IP 地址）和端口号，以逗号分隔。默认情况下，指定单个 MongoDB 实例的主机名和端口号仅连接到副本集的指定成员。但是，您可以通过几种不同的方式自动发现并连接到副本集的所有成员。创建副本集连接：

  • 使用replicaSet参数指定副本集的名称
  • directConnection用值指定参数false
  • 指定多个主机，而不是单个主机

这些方法中的每一种都会导致驱动程序发现副本集中任何未指定的主机。

以下连接字符串指定集群中的三个主机和名为“myRs”的副本集。

mongodb://host1:27017,host2:27017,host3:27017

 

以下示例显示如何MongoClient 使用ConnectionString或MongoClientSettings类为实例指定多个主机。选择与您要查看的代码片段对应的选项卡：

 
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);

 

提示

尽管可以通过仅提供单个主机来连接到副本集部署，但您应该向驱动程序提供完整列表，以确保即使其中一个主机出现故障，它也能够连接。

 

笔记

该replicaSet选项 是没有必要连接到副本集，因为驱动程序会自动检测并连接字符串的副本集控多台主机。

 

您可以压缩在 MongoDB 实例和驱动程序之间传递的消息。MongoDB 驱动程序最多支持三种不同的算法，具体取决于发布版本：

  1. Snappy：在 MongoDB 3.4 及更高版本中可用。
  2. Zlib：在 MongoDB 3.6 及更高版本中可用。
  3. Zstandard：在 MongoDB 4.2 及更高版本中可用。

您可以指定一个或多个压缩算法，但驱动程序使用连接的 MongoDB 实例支持的列表中的第一个压缩器。

笔记

需要 Snappy 或 Zstandard 压缩的应用程序必须 为这些算法添加显式依赖项。

您可以通过两种不同的方式为到 MongoDB 实例的连接启用压缩：通过连接字符串中的参数，或使用MongoClientSettings.Builder类中的方法。

 
要使用ConnectionString启用压缩，请使用compressors 传递给 的连接字符串中 的参数MongoClients.create()。您可以指定一种或多种压缩算法，用逗号分隔多个算法：
 
ConnectionString connectionString = new ConnectionString("mongodb+srv://<user>:<password>@<cluster-url>/?compressors=snappy,zlib,zstd");
MongoClient mongoClient = MongoClients.create(connectionString);

 

要使用ConnectionString启用压缩，请使用compressors 传递给 的连接字符串中 的参数MongoClients.create()。您可以指定一种或多种压缩算法，用逗号分隔多个算法：

MongoClientSettings settings = MongoClientSettings.builder()
     .compressorList(Arrays.asList(MongoCompressor.createSnappyCompressor(),
                                   MongoCompressor.createZlibCompressor(),
                                   MongoCompressor.createZstdCompressor()))
     .build();
MongoClient client = MongoClients.create(settings);

 

使用以下字符串指定压缩算法：

  • “snappy”用于Snappy压缩。
  • “zlib”用于Zlib压缩。
  • “zstd”用于Zstandard压缩。
 

JDK本身支持Zlib压缩，但 Snappy和 Zstandard依赖于开源实现。有关详细信息，请参阅 snappy -java和 zstd-java。

本节介绍驱动程序支持的 MongoDB 连接和身份验证选项。您可以将连接选项作为连接 URI 的参数传递来指定客户端的行为。

 
选项名称
类型
描述
maxPoolSize
integer
指定连接池的最大大小。
waitQueueTimeoutMS
integer
指定线程可以等待连接变为可用的最长时间（以毫秒为单位）。
serverSelectionTimeoutMS
integer
指定驱动程序在抛出异常之前等待服务器选择成功的最长时间（以毫秒为单位）。
localThresholdMS
integer
当与副本集中的多个MongoDB实例进行通信时，驱动程序只会将请求发送到响应时间小于或等于响应时间最快的服务器加上本地阈值的服务器，以毫秒为单位。
heartbeatFrequencyMS
integer
指定驱动程序在尝试确定集群中每个服务器的当前状态之间等待的频率（以毫秒为单位）。
replicaSet
string
指定 提供的连接字符串包括多个主机。指定后，驱动程序将尝试查找该集合的所有成员。
ssl
boolean
指定与 MongoDB 实例的所有通信都应使用 TLS/SSL。被tls选项取代。
tls
boolean
指定与 MongoDB 实例的所有通信都应使用 TLS。取代ssl选项。
tlsInsecure
boolean
指定驱动程序应允许 TLS 连接使用无效主机名。它和设置同样的效果 tlsAllowInvalidHostnames来true。要以其他方式配置 TLS 安全约束，请使用 自定义 SSLContext。
tlsAllowInvalidHostnames
boolean
指定驱动程序应允许证书中的无效主机名用于 TLS 连接。取代 sslInvalidHostNameAllowed。
connectTimeoutMS
integer
指定 Java 驱动程序在超时前等待连接打开的最长时间（以毫秒为单位）。
socketTimeoutMS
integer
指定 Java 驱动程序在超时前等待发送或接收请求的最长时间（以毫秒为单位）。
maxIdleTimeMS
integer
指定最长时间（以毫秒为单位），Java 驱动程序将允许池连接在关闭连接之前处于空闲状态。
maxLifeTimeMS
integer
指定 Java 驱动程序在关闭连接之前将继续使用池连接的最长时间（以毫秒为单位）。
journal
boolean
指定驱动程序必须等待连接的 MongoDB 实例对所有写入的磁盘上的日志文件进行分组提交。
w
string or integer
指定写关注。有关值的更多信息，请参阅w 选项的服务器文档。
wtimeoutMS
integer
指定写入问题的时间限制（以毫秒为单位）。有关更多信息，请参阅wtimeoutMS 选项的服务器文档 。
readPreference
string
指定读取首选项。有关值的更多信息，请参阅readPreference 选项的服务器文档 。
readPreferenceTags
string
指定读取首选项标签。有关值的更多信息，请参阅readPreferenceTags 选项的服务器文档 。
maxStalenessSeconds
integer
以秒为单位指定驱动程序停止与辅助节点通信之前辅助节点的陈旧程度。不提供参数或将其显式设置为-1表示不应该对辅助节点进行陈旧检查。最小值为 90 秒或心跳频率加 10 秒，以较大者为准。有关更多信息，请参阅maxStalenessSeconds 选项的服务器文档 。
authMechanism
string
指定在提供凭据时驱动程序应使用的身份验证机制。默认情况下，客户端会根据服务器版本选择最安全的可用机制。有关可能的值，请参阅authMechanism 选项的服务器文档 。
authSource
string
指定应根据其验证提供的凭据的数据库。默认为admin.
authMechanismProperties
string
将指定身份验证机制的身份验证属性指定为以冒号分隔的属性和值列表。有关更多信息，请参阅authMechanismProperties 选项的服务器文档。
appName
string
指定在连接握手期间提供给 MongoDB 实例的应用程序的名称。可用于服务器日志和分析。
compressors
string
指定驱动程序将尝试使用的一种或多种压缩算法来压缩发送到连接的 MongoDB 实例的请求。可能的值包括：zlib，snappy，和zstd。
zlibCompressionLevel
integer
指定Zlib 应采用的压缩程度，以减少对连接的 MongoDB 实例的请求大小。级别可以从-1到9，较低的值压缩得更快（但会导致更大的请求），而较大的值则压缩得更慢（但会导致更小的请求）。
retryWrites
boolean
指定如果支持的写操作由于网络错误而失败，驱动程序必须重试。默认为true.
retryReads
boolean
指定如果支持的读取操作由于网络错误而失败，驱动程序必须重试。默认为true.
uuidRepresentation
string
指定用于读取和写入操作的 UUID 表示。有关更多信息，请参阅MongoClientSettings.getUuidRepresentation() 方法的驱动程序文档 。
directConnection
boolean
指定驱动程序必须直接连接到主机。
 
 

有关完整的选项列表，请参阅 ConnectionString API 参考页面。

 

在连接上启用 TLS/SSL 

在本指南中，您可以了解如何 使用 JDK 中的底层 TLS/SSL 支持通过TLS/SSL安全协议连接到 MongoDB 实例 。要将您的连接配置为使用 TLS/SSL，请在ConnectionString 或MongoClientSettings 中启用 TLS/SSL 设置。

笔记
调试 TLS/SSL

如果您在设置 TLS/SSL 连接时遇到问题，您可以使用-Djavax.net.debug=all系统属性查看其他日志语句。有关 更多信息，请参阅调试 TLS/SSL 连接的 Oracle 指南。

您可以通过两种不同的方式为与 MongoDB 实例的连接启用 TLS/SSL：通过连接字符串中的参数，或使用MongoClientSettings.Builder类中的方法。

 
要在具有ConnectionString的连接上启用 TLS/SSL tls，请true在传递 给的连接字符串中为连接字符串参数分配一个值MongoClients.create()：
MongoClient mongoClient = MongoClients.create("mongodb+srv://<user>:<password>@<cluster-url>?tls=true");

 

要MongoClient使用MongoClientSettings.Builder该类配置您的 TLS/SSL 连接选项 ，请调用 applyToSslSettings() 方法。在 块中设置enabled属性以启用 TLS/SSL：trueSslSettings.Builder

MongoClientSettings settings = MongoClientSettings.builder()
       .applyToSslSettings(builder ->
           builder.enabled(true))
       .build();
MongoClient client = MongoClients.create(settings);

 

发起 TLS/SSL 请求的 Java 应用程序需要访问加密证书，以证明应用程序本身以及与应用程序交互的其他应用程序的身份。您可以使用以下机制在应用程序中配置对这些证书的访问：

  • JVM 信任存储和 JVM 密钥存储
  • 客户端特定的信任存储和密钥存储
笔记

我们基于 Oracle JDK 的文档编写了以下部分，因此某些部分可能不适用于您的 JDK 或您使用的自定义 TLS/SSL 实现。

笔记

默认情况下，JRE 包含许多来自Let's Encrypt等签名机构的常用公共证书。因此，您可以使用 TLS/SSL连接到MongoDB Atlas 的实例（或任何其他服务器，其证书由 JRE 的默认证书存储中的权威签名），而无需配置信任存储。

JVM 信任存储保存证书，这些证书可以安全地识别与您的 Java 应用程序交互的其他应用程序。使用这些证书，您的应用程序可以证明与另一个应用程序的连接是真实且安全的，不会被第三方篡改。

如果您的 MongoDB 实例使用由 JRE 的默认证书存储中不存在的机构签署的证书，则您的应用程序必须配置两个系统属性以启动 SSL/TLS 请求。这些属性确保您的应用程序能够验证连接的 MongoDB 实例提供的 TLS/SSL 证书。

  • javax.net.ssl.trustStore：包含签名机构证书的信任库的路径
  • javax.net.ssl.trustStorePassword：访问定义的信任库的密码 javax.net.ssl.trustStore

您可以使用 作为 JDK 一部分提供的keytool命令行工具创建信任存储：

keytool -importcert -trustcacerts -file <path to certificate authority file>
         -keystore <path to trust store> -storepass <password>

 

笔记

默认情况下，MongoDB 实例不执行客户端证书验证。如果您显式配置 MongoDB 实例以验证客户端证书，则只需配置密钥库。

JVM 密钥库保存证书，这些证书可以安全地向其他应用程序标识您的 Java 应用程序。使用这些证书，其他应用程序可以证明与您的应用程序的连接是真实且安全的，不会被第三方篡改。

发起 TLS/SSL 请求的应用程序需要设置两个 JVM 系统属性，以确保客户端向 MongoDB 服务器提供 TLS/SSL 证书：

  • javax.net.ssl.keyStore：包含客户端 TLS/SSL 证书的密钥库的路径
  • javax.net.ssl.keyStorePassword：访问定义的密钥库的密码 javax.net.ssl.keyStore

您可以使用keytool 或openssl命令行工具创建密钥库。

有关配置 Java 应用程序以使用 TLS/SSL 的更多信息，请参阅JSSE 参考指南。

您可以使用类的init()方法配置特定于客户端的信任库和密钥库 SSLContext。

您可以SSLContext 在本指南的使用 SSLContext 自定义 TLS/SSL 配置部分中找到展示如何使用实例配置客户端的示例 。

有关SSLContext该类的更多信息，请参阅SSL Context的 API 文档。

默认情况下，驱动程序确保服务器的 TLS/SSL 证书中包含的主机名与构建MongoClient. 如果您需要为您的应用程序禁用主机名验证，您可以通过在 builder lambdainvalidHostNameAllowed中将构建器的属性设置为来显式禁用它 ：trueapplytoSslSettings()

MongoClientSettings settings = MongoClientSettings.builder()
     .applyToSslSettings(builder -> {
                 builder.enabled(true);
                 builder.invalidHostNameAllowed(true);
             })
     .build();

 

警告

禁用主机名验证会使您的配置 不安全。您应该仅出于测试目的或在没有其他选择时禁用主机名验证。

要将您的应用程序限制为仅使用 TLS 1.2 协议，请将jdk.tls.client.protocols系统属性设置 为“TLSv1.2”。

 

笔记

Java 8 之前的 Java 运行时环境 (JRE) 仅在更新版本中启用 TLS 1.2 协议。如果您的 JRE 尚未启用 TLS 1.2 协议，您可能需要升级到更高版本才能使用 TLS 1.2 进行连接。

如果您的 TLS/SSL 配置需要额外的自定义，您可以通过将SSLContext 对象传递给lambda 中的构建器来设置您的sslContext属性：MongoClientapplyToSslSettings()

SSLContext sslContext = ...
MongoClientSettings settings = MongoClientSettings.builder()
     .applyToSslSettings(builder -> {
                 builder.enabled(true);
                 builder.context(sslContext);
             })
     .build();
MongoClient client = MongoClients.create(settings);

 

在线证书状态协议 (OCSP) 

OCSP 是用于检查 X.509 证书是否已被撤销的标准。证书颁发机构可以在到期时间之前将 X.509 证书添加到证书吊销列表 (CRL) 以使证书无效。当客户端在 TLS 握手期间发送 X.509 证书时，CA 的吊销服务器会检查 CRL 并返回“良好”、“已撤销”或“未知”状态。

该驱动程序支持以下 OCSP 变体：

  • 客户端驱动的 OCSP
  • OCSP 装订

以下部分描述了它们之间的区别以及如何为您的应用程序启用它们。

笔记

Java 驱动程序使用为应用程序配置的 JVM 参数，并且不能被特定MongoClient实例覆盖。

在客户端驱动的 OCSP 中，客户端在收到服务器的证书后，将证书在 OCSP 请求中发送给 OCSP 响应者。OCSP 响应器通过证书颁发机构 (CA) 检查证书的状态，并在发送给客户端的响应中报告它是否有效。

要为您的应用程序启用客户端驱动的 OCSP，请设置以下 JVM 系统属性：

 
 
Property
Value
com.sun.net.ssl.checkRevocation
将此属性设置true为启用吊销检查。
ocsp.enable
将此属性设置true为启用客户端驱动的 OCSP。
警告

如果 OCSP 响应程序不可用，则 JDK 提供的 TLS 支持会报告“硬故障”。这与 MongoDB Shell 和其他一些驱动程序的“软失败”行为不同。

OCSP 装订是一种机制，在该机制中，服务器必须从证书颁发机构 (CA) 获取签名证书，并将其包含在给客户端的带有时间戳的 OCSP 响应中。

要为您的应用程序启用 OCSP 装订，请设置以下 JVM 系统属性：

 
 
Property
Description
com.sun.net.ssl.checkRevocation
将此属性设置true为启用吊销检查。
jdk.tls.client.enableStatusRequestExtension
将此属性设置true为启用 OCSP 装订。
 
如果未设置或设置为false，则无论证书吊销响应是否存在或状态如何，连接都可以继续。

有关 OCSP 的其他信息，请查看以下资源：

 

官网地址：https://docs.mongodb.com/drivers/java/sync/current/fundamentals/connection/