指定 MongoClient 设置

本页内容

概述

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

概述

在本指南中，您可以了解如何控制您的MongoClient行为的各种设置MongoClient.

以下各节描述了常用设置

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

MongoClient 设置

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

要创建一个MongoClientSettings对象，使用MongoClientSettings.builder()方法，并链接方法来指定您的设置。链接完成后，使用build()方法创建MongoClientSettings对象。

下表描述了您可以链接的所有方法来修改您的连接行为

方法	描述
`addCommandListener()`	添加一个命令事件的监听器command events.
`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 秒。
套接字设置指定为 5 秒。

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 秒 内连接到可用套接字。

提示

记录您的设置

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

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

集群设置

将 applyToClusterSettings() 方法链接到修改驱动程序与您的 MongoDB 集群交互行为。

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

方法

描述

addClusterListener()

添加与集群相关事件的监听器。

applyConnectionString()

使用来自 ConnectionString 对象的设置。

applySettings()

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

hosts()

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

localThreshold()

设置服务器往返时间的最大值，并且仍然有资格进行服务器选择。

mode()

设置如何连接到 MongoDB 服务器。

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

设置驱动程序在使用DNS种子列表（SRV）连接协议时可以连接到的最大主机数，由 mongodb+srv 连接字符串前缀标识。

如果您没有使用SRV连接协议，则抛出异常。

示例

此示例指定驱动程序直接连接到服务器，而不管它所属的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 秒内连接到可用套接字
在 15 秒内从可用套接字读取

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 秒 以获取可用连接
池中最多关联 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 服务器中的驱动程序行为

服务器监控检查的最小间隔至少为 700 毫秒
集群监控器每15秒尝试连接到服务器

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() 方法修改驱动程序在应用程序与MongoDB之间使用TLS/SSL加密连接时的行为。

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

方法	描述
`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()
)

连接选项

网络压缩