NoSQL 与搜索 / 系统课时
使用 Retryable Writes 与幂等键
使用 Retryable Writes 与幂等键
网络抖动最棘手的地方不是“写失败”,而是客户端不知道那次写到底有没有成功。本课把驱动级 Retryable Writes 与业务级幂等请求拆开处理,并用唯一索引把重复创建挡在数据库层。
学习目标
- 说明 Retryable Writes 能解决什么、不能解决什么。
- 为业务请求设计稳定的幂等键与唯一约束。
- 识别重复请求、重试写入和外部副作用之间的边界。
先分清两层重试
Retryable Writes 处理的是同一次数据库写入在传输层结果不确定的问题。例如服务端已经完成 insertOne(),但确认响应在网络中断时丢失,驱动可以再次发送该逻辑写入;服务端利用会话标识和事务编号识别重试,避免把同一次可重试写执行两遍。
业务幂等处理的是另一层问题:浏览器超时后重新发起一次 HTTP 请求、消息队列重复投递、调用方主动重试,这些通常已经是新的业务请求,不能依赖驱动会话自动去重。此时必须由业务提供稳定的幂等键,并让数据库唯一约束做最终裁决。

让驱动负责可重试的单文档写
在副本集或分片集群上,兼容驱动通常可通过 retryWrites=true 启用可重试写;还需要可确认的写关注。它适合 insertOne()、updateOne()、deleteOne()、findOneAndUpdate() 这类单文档写入。updateMany()、deleteMany() 以及任意多文档业务流程,不应因为开启 Retryable Writes 就被视为自动幂等。
下面的完整 Node.js 示例同时打开驱动重试,并用 idempotencyKey 唯一索引处理两次独立业务请求。运行前把环境变量 MONGODB_URI 指向支持会话的 MongoDB 副本集或分片集群。
import { createHash } from 'node:crypto';
import { MongoClient } from 'mongodb';
const uri = process.env.MONGODB_URI;
if (!uri) throw new Error('MONGODB_URI is required');
const client = new MongoClient(uri, { retryWrites: true });
function hashRequest(input) {
return createHash('sha256').update(JSON.stringify(input)).digest('hex');
}
async function main() {
await client.connect();
const orders = client.db('shop').collection('orders');
const key = 'checkout-1001';
// 唯一索引是最终防线,避免两个并发请求同时判定“尚未处理”。
await orders.createIndex({ idempotencyKey: 1 }, { unique: true });
await orders.deleteOne({ idempotencyKey: key });
async function createOrder(input, idempotencyKey) {
const requestHash = hashRequest(input);
const doc = { ...input, idempotencyKey, requestHash };
try {
await orders.insertOne(doc);
return { reused: false, orderNo: doc.orderNo };
} catch (error) {
if (error?.code !== 11000) throw error;
// 相同键只有在请求内容也一致时才能复用已有结果。
const existing = await orders.findOne({ idempotencyKey });
if (!existing || existing.requestHash !== requestHash) {
throw new Error('IDEMPOTENCY_KEY_CONFLICT');
}
return { reused: true, orderNo: existing.orderNo };
}
}
const input = { orderNo: 'A-1001', amount: 299 };
console.log(JSON.stringify(await createOrder(input, key)));
console.log(JSON.stringify(await createOrder(input, key)));
}
main()
.catch(console.error)
.finally(() => client.close());预期输出
{"reused":false,"orderNo":"A-1001"}
{"reused":true,"orderNo":"A-1001"}幂等键必须同时约束身份和内容
幂等键应由调用方在一次业务意图的所有重试中保持不变,例如“提交订单”可使用客户端生成的 UUID。只保存键还不够:如果调用方错误地拿同一个键提交另一份金额或商品列表,服务端应返回冲突,而不是悄悄复用旧结果。因此示例同时保存请求摘要 requestHash。
不要采用“先 findOne(),没有再 insertOne()”作为唯一保护。两个并发请求可能同时查到不存在,然后都尝试插入。真正消除竞态的是唯一索引;前置查询最多只是优化提示,不能替代约束。
认清自动重试不会覆盖的边界
MongoDB 的 Retryable Writes 只对符合条件的数据库写负责,不会替你重放完整业务函数,也不会让“扣款后发邮件”“写 MongoDB 后调用第三方 API”自动变成原子操作。外部系统存在副作用时,应让对方也支持幂等键,或采用 Outbox 等可恢复交付模式。
同样,不要在应用层看到任何异常就无限重试。先区分可重试网络错误、唯一键冲突和业务校验失败,并给重试设置次数与截止时间。最稳妥的职责划分是:驱动处理同一次数据库写的瞬时失败,业务幂等键处理跨请求重复,唯一索引负责并发下的最终一致裁决。