Docs 主页 → 开发应用程序 → MongoDB 驱动程序 → Java (Sync) 驱动程序

指定 MongoClient 设置

在此页面上

概述

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

概述

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

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

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

MongoClient 设置

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

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

下表列出了修改连接行为的方法：

方法	说明
`addCommandListener()`	为命令事件添加侦听器。
`applicationName()`	使用 `MongoClient` 设置应用程序的逻辑名称。
`applyConnectionString()`	将给定 `ConnectionString` 中的设置应用于构建器。如果省略该方法，该驱动程序将尝试连接到 `localhost`。
`applyToClusterSettings()`	应用`ClusterSettings.Builder`区块，然后进行集群设置。
`applyToConnectionPoolSettings()`	应用`ConnectionPoolSettings.Builder`区块，然后设置连接池设置。
`applyToLoggerSettings()`	应用`LoggerSettings.Builder`区块，然后设置记录器设置。
`applyToServerSettings()`	应用`ServerSettings.Builder`区块，然后进行服务器设置。
`applyToSocketSettings()`	应用`SocketSettings.Builder`区块，然后进行套接字设置。
`applyToSslSettings()`	应用`SslSettings.Builder`区块，然后进行TLS/SSL 设置。
`autoEncryptionSettings()`	设置自动加密设置。如果您在 `AutoEncryptionSettings` 中省略 `keyVaultClient` 或将 `bypassAutomaticEncryption` 设置为 false，驱动程序将创建一个单独的内部 `MongoClient`。内部 `MongoClient` 配置与父级 `MongoClient` 的不同之处在于将 `minPoolSize` 设置为 0 并省略 `AutoEncryptionSettings`。
`codecRegistry()`	设置编解码器注册表。
`commandListenerList()`	设置命令侦听器。
`compressorList()`	设置用于压缩发送到服务器的消息的压缩器。
`credential()`	设置档案。
`readConcern()`	设置读关注。
`readPreference()`	设置读取偏好。默认：`primary`。
`retryReads()`	如果发生网络错误，驱动程序是否执行重试读取。默认：`true`。
`retryWrites()`	发生网络错误时驱动程序是否执行重试写入。默认：`true`。
`serverApi()`	设置向服务器发送命令时使用的服务器 API。
`transportSettings()`	设置 TransportSettings。
`uuidRepresentation()`	设置在编码 UUID 实例和解码子类型为 3 的 BSON 二进制值时使用的 UUID 表示。
`writeConcern()`	设置写关注。默认值： `WriteConcern#ACKNOWLEDGED` 。有关默认值的更多信息，请参阅隐式默认写关注。

例子

此示例演示如何指定 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://<username>:<password>@<hostname>:<port>/<auth db>?connectTimeoutMS=2000"))
      .applyToSocketSettings(builder ->
      builder.connectTimeout(5L, SECONDS))
      .build());

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

提示

记录您的设置

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

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

群集设置

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

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

方法

说明

addClusterListener()

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

applyConnectionString()

使用 ConnectionString 对象中的设置。

applySettings()

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

hosts()

设置 Mongo 部署的所有指定位置。

localThreshold()

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

默认：15 milliseconds。

mode()

设置如何连接到 MongoDB 部署。

requiredClusterType()

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

requiredReplicaSetName()

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

serverSelectionTimeout()

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

默认：30 seconds。

serverSelector()

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

srvHost()

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

注意

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

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

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

srvMaxHosts()

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

如果不使用 SRV 连接协议，则会引发异常。

例子

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder()
    .applyToClusterSettings(builder ->
        builder.mode(ClusterConnectionMode.SINGLE)
    .build());

提示

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

连接池设置

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

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

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

注意

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

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

例子

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

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToConnectionPoolSettings(builder ->
        builder.maxWaitTime(10, SECONDS)
        .maxSize(200)
    .build());

记录器设置

链接 applyToLoggerSettings() 方法来修改驱动程序的日志记录行为。

下表描述了可以链接到设置以修改日志记录行为的方法：

方法	说明
`maxDocumentLength()`	设置单个日志消息的最大文档长度（以字符为单位）。默认：`1000`。

例子

此示例指定将单个日志消息的最大字符数设置为 5000 个字符。

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

服务器设置

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

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

方法	说明
`addServerListener()`	为服务器相关事件添加侦听器。
`addServerMonitorListener()`	为服务器监视器相关事件添加侦听器。
`applyConnectionString()`	使用 `ConnectionString` 对象中的设置。
`applySettings()`	使用 `ServerSettings` 对象中指定的服务器设置。
`heartbeatFrequency()`	设置集群监视器尝试访问服务器的时间间隔。默认：`10 seconds`。
`minHeartbeatFrequency()`	设置服务器监控检查的最小间隔。默认：`500 milliseconds`。

例子

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

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToServerSettings(builder ->
        builder.minHeartbeatFrequency(700, MILLISECONDS)
        .heartbeatFrequency(15, SECONDS))
    .build());

套接字设置

链接 applyToSocketSettings() 方法，修改驱动程序在与 MongoDB 部署连接并通信时的行为。

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

方法	说明
`applyConnectionString()`	使用 `ConnectionString` 对象中的设置。
`applySettings()`	使用在 `SocketSettings` 对象中指定的套接字设置。
`connectTimeout()`	设置在引发超时异常之前连接到可用套接字的最长时间。默认：`10 seconds`。
`readTimeout()`	设置在引发超时异常之前从可用套接字读取的最长时间。默认：`0`，表示没有超时
`receiveBufferSize()`	设置接收时套接字的缓冲区大小。默认值：操作系统默认值
`sendBufferSize()`	设置发送时套接字的缓冲区大小。默认值：操作系统默认值

例子

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

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

MongoClient mongoClient = MongoClients.create(
    MongoClientSettings.builder().applyConnectionString(new ConnectionString("<your connection string>"))
    .applyToSocketSettings(builder ->
        builder.connectTimeout(10, SECONDS)
        .readTimeout(15, 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：

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

← 连接选项

网络压缩 →