指定 MongoClient 设置

在此页面上

Overview

MongoClient 设置
群集设置
套接字设置
连接池设置
服务器设置
TLS/SSL 设置

Overview

在本指南中，您可以学习控制 MongoClient 行为的几种不同设置。

以下各部分介绍了常用设置：

MongoClient 设置
群集设置
套接字设置
连接池设置
服务器设置
TLS/SSL 设置

MongoClient 设置

您可以通过创建MongoClient MongoClientSettings 对象并将其传递给 MongoClient.create() 方法来控制的行为。

要创建 MongoClientSettings 对象，请使用 MongoClientSettings.builder() 方法和链接方法指定设置。将它们链接起来后，使用 build() 方法创建 MongoClientSettings 对象。

下表描述了可以链式调用以修改连接行为的所有方法：

方法	说明
`addCommandListener()`	为命令事件添加侦听器。
`applicationName()`	使用 `MongoClient` 设置应用程序的逻辑名称。
`applyConnectionString()`	将给定 `ConnectionString` 中的设置应用于构建器。如果省略该方法，该驱动程序将尝试连接到 `localhost`。
`applyToClusterSettings()`	应用 `ClusterSettings.Builder` 块，然后设置集群设置。
`applyToConnectionPoolSettings()`	应用 `ConnectionPoolSettings.Builder` 块，然后设置连接池设置。
`applyToServerSettings()`	应用 `ServerSettings.Builder` 块，然后设置服务器设置。
`applyToSocketSettings()`	应用 `SocketSettings.Builder` 块，然后设置套接字设置。
`applyToSslSettings()`	应用 `SslSettings.Builder` 块，然后设置 TLS/SSL 设置。
`autoEncryptionSettings()`	设置自动加密设置。
`codecRegistry()`	设置编解码器注册表。设置编解码器注册表。
`commandListenerList()`	设置命令侦听器。
`compressorList()`	设置用于压缩发送到服务器的消息的压缩器。
`credential()`	设置档案。
`readConcern()`	设置读关注。
`readPreference()`	设置读取偏好。
`retryReads()`	读取发生网络错误时驱动程序是否应重试。
`retryWrites()`	发生网络错误时驱动程序是否应重试写入。
`serverApi()`	设置向服务器发送命令时使用的服务器 API。
`streamFactoryFactory()`	设置用于创建 `StreamFactory` 的工厂。
`uuidRepresentation()`	设置在编码 UUID 实例和解码子类型为 3 的 BSON 二进制值时使用的 UUID 表示。
`writeConcern()`	设置写关注。

例子

此示例演示如何指定 ConnectionString：

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

提示

每个设置都有一个applyConnectionString()方法。在设置中很少需要它们，因此您应该使用此方法，如前面的示例所示。

注意

连锁订单

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

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

连接字符串指定在 2 SECONDS
套接字设置在 5 SECONDS内指定

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("mongodb+srv:/<db_username>:<db_password>@<hostname>:<port>?connectTimeoutMS(2000)"))
        .applyToSocketSettings{ builder ->
            builder.connectTimeout(5, TimeUnit.SECONDS)
        }
        .build()
)

由于驱动程序最后才读取套接字设置选项，因此驱动程序希望在超时前的 5 SECONDS 内连接到可用的套接字。

提示

记录您的设置

要记录 MongoClient 实例设置，请将名为 logger 的 org.mongodb.driver.client 设置为 INFO 级别。

要了解有关使用 MongoDB Kotlin 驱动程序进行日志记录的更多信息，请参阅日志记录指南。

群集设置

链式调用 applyToClusterSettings() 方法以修改驱动程序与您的 MongoDB 集群交互时的行为。

下表描述了可以链接到设置以修改驱动程序行为的所有方法：

方法

说明

addClusterListener()

为集群相关事件添加侦听器。

applyConnectionString()

使用 ConnectionString 对象中的设置。

applySettings()

使用在 ClusterSettings 对象中指定的集群设置。

hosts()

设置 Mongo 服务器的所有指定位置。

localThreshold()

设置服务器往返可能所需的时间，以及是否仍符合服务器选择条件。

mode()

设置如何连接到 MongoDB Server。

requiredClusterType()

设置集群所需的集群类型。

requiredReplicaSetName()

设置集群所需的副本集名称。

serverSelectionTimeout()

设置在抛出超时异常之前选择主节点的最长时间。

serverSelector()

添加服务器选择器，在选择服务器前应用。

srvHost()

设置用于查找 SRV DNS 记录的主机名，以查找 MongoDB 主机。

设置 srvHost 时，驱动程序不会处理与主机关联的任何 TXT 记录。

如果要启用 TXT 记录处理，必须使用 applyConnectionString() 方法在连接字符串中指定 SRV 主机。

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("mongodb+srv://host1.acme.com"))
        .build()
)

srvMaxHosts()

Sets the maximum number of hosts the driver can connect to when using
the DNS seedlist (SRV) connection protocol, identified by the
mongodb+srv connection string prefix.

Throws an exception if you are not using the SRV connection protocol.

例子

此示例指定驱动程序直接连接到服务器，无论它隶属哪种类型的 MongoDB 集群：

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyToClusterSettings{ builder ->
            builder.mode(ClusterConnectionMode.SINGLE)
        }
        .build()
)

提示

此操作类似于在连接 URI 中指定的 directConnection 参数。有关更多信息，请参阅“连接选项”。

套接字设置

链接 applyToSocketSettings() 方法，修改驱动程序在与 MongoDB 服务器连接和通信时的行为。

下表描述了可以链接到设置以修改驱动程序行为的所有方法：

方法	说明
`applyConnectionString()`	使用 `ConnectionString` 对象中的设置。
`applySettings()`	使用在 `SocketSettings` 对象中指定的套接字设置。
`applyToProxySettings()`	应用`ProxySettings.Builder`区块，然后设置`proxySettings`字段。
`connectTimeout()`	设置在引发超时异常之前连接到可用套接字的最长时间。
`readTimeout()`	设置在抛出超时异常之前读取可用套接字的最长时间。
`receiveBufferSize()`	设置接收时套接字的缓冲区大小。
`sendBufferSize()`	设置发送时套接字的缓冲区大小。

例子

本示例在 MongoDB 套接字中指定了以下驱动程序行为：

连接到可用套接字 10 SECONDS
从可用套接字读取，在 15 SECONDS

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToSocketSettings{ builder ->
            builder
                .connectTimeout(10, TimeUnit.SECONDS)
                .readTimeout(15, TimeUnit.SECONDS)
        }
        .build()
)

连接池设置

链接 applyToConnectionPoolSettings () 方法，以修改驱动程序管理其连接池的方式。

下表描述了可以链接到设置以修改驱动程序行为的所有方法：

方法	说明
`addConnectionPoolListener()`	添加监听器，用于监听与连接池相关的事件。
`applyConnectionString()`	使用 `ConnectionString` 对象中的设置。
`applySettings()`	使用在 `ConnectionPoolSettings` 对象中指定的连接池设置。
`maintenanceFrequency()`	设置运行维护作业的频率。
`maintenanceInitialDelay()`	设置运行第一个维护作业之前的等待时间。
`maxConnectionIdleTime()`	设置连接在关闭之前可以空闲的最长时间。
`maxConnectionLifeTime()`	设置池式连接在关闭之前可以存活的最长时间。
`maxWaitTime()`	设置等待可用连接的最长时间。
`maxSize()`	设置与连接池关联的最大连接数。
`minSize()`	设置与连接池关联的最小连接数。

注意

此maxSize和minSize设置适用于驱动程序连接到的集群中的每台服务器。

例如，假设您将驱动程序连接到一个有三台 mongos 服务器的集群。这意味着每台mongos服务器最多可以有maxSize个连接，至少有minSize个连接。

例子

此示例在 Connection 类型池中指定以下驱动程序行为：

线程最多等待可用连接 10 SECONDS
最多有 200 个与池关联的连接

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToConnectionPoolSettings{ builder ->
            builder
                .maxWaitTime(10, TimeUnit.SECONDS)
                .maxSize(200)
        }
        .build()
)

服务器设置

链接 applyToServerSettings() 方法修改驱动程序在监控每个 MongoDB 服务器时的行为。

下表描述了可以链接到设置以修改驱动程序行为的所有方法：

方法	说明
`addServerListener()`	为服务器相关事件添加侦听器。
`addServerMonitorListener()`	为服务器监视器相关事件添加侦听器。
`applyConnectionString()`	使用 `ConnectionString` 对象中的设置。
`applySettings()`	使用 `ServerSettings` 对象中指定的服务器设置。
`heartbeatFrequency()`	设置集群监视器尝试访问服务器的时间间隔。
`minHeartbeatFrequency()`	设置服务器监控检查的最小间隔。
`serverMonitoringMode()`	指定驱动程序使用的服务器监控协议。

例子

此示例在 MongoDB Server 中指定以下驱动程序行为：

服务器监控检查的最小间隔至少为 700 MILLISECONDS
集群监视器尝试访问服务器的时间间隔为 15 SECONDS

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToServerSettings{ builder ->
            builder
                .minHeartbeatFrequency(700, TimeUnit.MILLISECONDS)
                .heartbeatFrequency(15, TimeUnit.SECONDS)
        }
        .build()
)

TLS/SSL 设置

链接 applyToSslSettings() 方法，以修改驱动程序在使用 TLS/SSL 保护应用程序和 MongoDB 之间的连接时的行为。

下表描述了可以链接到设置以修改驱动程序行为的所有方法：

方法	说明
`applyConnectionString()`	使用 `ConnectionString` 对象中的设置。
`applySettings()`	使用在 `SslSettings` 对象中指定的 TLS/SSL 设置。
`context()`	设置启用 TLS/SSL 时使用的 `SSLContext`。
`enabled()`	是否启用 TLS/SSL。(必须为 Atlas 集群启用此选项）。
`invalidHostNameAllowed()`	是否允许服务器主机名与 TLS 证书指定的主机名不匹配。

例子

此示例规定了驱动程序要在连接 MongoDB 时启用 TLS/SSL：

val mongoClient = MongoClient.create(
    MongoClientSettings.builder()
        .applyConnectionString(ConnectionString("<your connection string>"))
        .applyToSslSettings{ builder ->
            builder.enabled(true)
        }
        .build()
)

后退

连接选项

来年

网络压缩