配置客户端级增删改查设置

Overview

在本指南中，您可以学习如何使用 Java 驱动程序为 MongoClient 实例配置 CRUD 操作。

读取偏好、读关注和写关注可控制驱动程序如何路由读操作，以及在连接 MongoDB 副本集时如何等待读写操作的确认。读取偏好和读关注适用于所有读操作；写关注适用于所有写操作。

MongoDatabase MongoCollection 实例从访问它们的 MongoClient 继承其偏好和关注点。但是，您可以对数据库和集合应用自定义设置。有关详细信息，请参阅“配置自定义 CRUD 设置”页面。

您可以使用连接字符串或将 MongoClientSettings对象传递给MongoClients 构造函数来指定客户端级增删改查设置。选择 Connection String 或 MongoClientSettings标签页，查看可用选项：

在连接字符串中包含以下参数以修改驱动程序的读取或写入行为：

选项名称	类型	说明
`journal`	布尔	指定驱动程序必须等待已连接的 MongoDB 实例为所有写入操作将提交分组到磁盘上的日志文件。默认值：`false`
`w`	字符串或整数	指定写关注（write concern）。有关值的更多信息，请参阅MongoDB Server文档中的 w 选项。默认值：`1`
`wtimeoutMS`	整型	指定写关注（write concern）的时间限制（以毫秒为单位）。有关更多信息，请参阅MongoDB Server文档中的 wtimeoutMS 选项。值为 `0` 指示驱动程序写入操作永不超时。默认值：`0`
`readPreference`	字符串	指定读取偏好（read preference）。有关值的更多信息，请参阅MongoDB Server文档中的readPreference 选项。默认值：`primary`
`readPreferenceTags`	字符串	指定读取偏好（read preference）标签。有关值的更多信息，请参阅MongoDB Server文档中的 readPreferenceTags 选项。默认值：`null`
`maxStalenessSeconds`	整型	指定在驱动程序停止与从节点通信之前从节点的陈旧度（以秒为单位）。最小值为 90 秒或 heartbeat 频率加 10 秒，以较大者为准。有关详情，请参阅 maxStalenessSeconds 选项的 MongoDB Server 文档。不提供参数或明确指定 `-1`，表示从节点不能进行陈旧度检查。默认值：`-1`
`uuidRepresentation`	字符串	指定用于读取和写入操作的 UUID 表示形式。有关更多信息，请参阅 MongoClientSettings.getUuidRepresentation() 方法的驱动程序文档。默认值：`unspecified`
`retryWrites`	布尔	指定驱动程序在由于网络错误而无法完成支持的写入操作时必须重试这些操作。默认值：`true`
`retryReads`	布尔	指定驱动程序在由于网络错误而无法完成支持的读取操作时必须重试这些操作。默认值：`true`
`maxAdaptiveRetries`	整型	设置驱动程序在命令因可重试的过载错误（即同时带有 `SystemOverloadedError` 和 `RetryableError` 标签的错误）而失败时重试该命令的最大次数。此选项仅在 `retryWrites` 设置为 `true` 时应用于写入命令，仅在 `retryReads` 设置为 `true` 时应用于读取命令。将该值设置为 `0` 将禁用可重试过载错误的重试尝试。默认：`null`。如果未设置此选项，驱动程序通常会应用值 `2`。
`enableOverloadRetargeting`	布尔	设置驱动程序在后续重试尝试进行服务器选择时，是否可以降低之前返回过载错误的服务器的优先级。此选项适用于 `retryReads` 设置为 `true` 时的读取，以及 `retryWrites` 设置为 `true` 时的写入。此选项不适用于分片集群。默认值：`false`

以下示例将读取偏好（read preference）设置为从最近的副本集成员读取：

ConnectionString connectionString = "mongodb://<host>:<port>/?readPreference=nearest"MongoClient mongoClient = MongoClients.create(connectionString)

有关这些参数的更多信息，请参阅 ConnectionString API文档。

将以下方法链接到 MongoClientSettings 构造函数以修改驱动程序的读/写入行为：

`enableOverloadRetargeting()`	设置驱动程序在后续重试尝试进行服务器选择时，如果服务器之前返回过载错误，是否可以降低其优先级。适用于 `retryReads()` 设置为 `true` 时的读取，以及 `retryWrites()` 设置为 `true` 时的写入。不适用于分片集群。默认值：`false`
`maxAdaptiveRetries()`	设置驱动程序在因可重试过载错误（即带有 `SystemOverloadedError` 和 `RetryableError` 标签的错误）而失败时重试命令的最大次数。仅当 `retryWrites()` 设置为 `true` 时应用于写入命令，仅当 `retryReads()` 设置为 `true` 时应用于读取命令。将该值设置为 `0` 将禁用可重试过载错误的重试尝试。默认：`null`。如果未设置此选项，驱动程序通常会应用值 `2`。
`readConcern()`	设置读关注（read concern）。服务器手册页 API文档
`readPreference()`	设置读取偏好（read preference）默认值：`primary`
`retryReads()`	如果发生网络错误，驱动程序是否执行重试读取。默认值：`true`
`retryWrites()`	如果出现网络错误，驱动程序是否执行重试写入。默认值：`true`
`uuidRepresentation()`	设置在编码 UUID 实例和解码子类型为 3 的 BSON 二进制值时使用的 UUID 表示。
`writeConcern()`	设置写关注。默认值：`WriteConcern#ACKNOWLEDGED`。\| 有关默认值的更多信息，请参阅隐式默认写关注。

以下示例将读取偏好（read preference）设置为从最近的副本集成员读取：

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

有关这些方法的更多信息，请参阅 MongoClientSettings.Builder API文档。

注意

智能工作负载管理 (IWM) 中的负载削减

如果带有 SystemOverloadedError 或 RetryableError 标签的错误导致您的应用程序出现故障或出现在您的应用程序日志中，则说明您的集群上可能已启用负载削减 (Load Shedding)，并且您的驱动程序可能未升级到支持该功能的版本。我们建议将您的 MongoDB Java 驱动程序升级到 5.8 或更高版本。如果您在升级后仍然看到这些错误，可以通过服务器端更改（例如查看您的负载削减配置）或通过应用程序端更改（例如实现自定义错误处理或客户端请求限制）来解决这些错误。根据您的情况，应用程序端更改可能是更可取或必要的。

负载削减 (Load Shedding) 是 IWM 的一项功能，有助于在持续过载期间通过拒绝多余的操作来管理服务器负载。此功能适用于 MongoDB 9.0 及更高版本。

有关 IWM 或处理超载错误的更多信息，请参阅智能工作负载管理页面或超载错误页面中的 Atlas 文档。