NoSQL 与搜索 / 系统课时

使用 Retryable Writes 与幂等键

使用 Retryable Writes 与幂等键

网络抖动最棘手的地方不是“写失败”,而是客户端不知道那次写到底有没有成功。本课把驱动级 Retryable Writes 与业务级幂等请求拆开处理,并用唯一索引把重复创建挡在数据库层。

学习目标

  • 说明 Retryable Writes 能解决什么、不能解决什么。
  • 为业务请求设计稳定的幂等键与唯一约束。
  • 识别重复请求、重试写入和外部副作用之间的边界。

先分清两层重试

Retryable Writes 处理的是同一次数据库写入在传输层结果不确定的问题。例如服务端已经完成 insertOne(),但确认响应在网络中断时丢失,驱动可以再次发送该逻辑写入;服务端利用会话标识和事务编号识别重试,避免把同一次可重试写执行两遍。

业务幂等处理的是另一层问题:浏览器超时后重新发起一次 HTTP 请求、消息队列重复投递、调用方主动重试,这些通常已经是新的业务请求,不能依赖驱动会话自动去重。此时必须由业务提供稳定的幂等键,并让数据库唯一约束做最终裁决。

Retryable Writes 与业务幂等键分层关系

让驱动负责可重试的单文档写

在副本集或分片集群上,兼容驱动通常可通过 retryWrites=true 启用可重试写;还需要可确认的写关注。它适合 insertOne()、updateOne()、deleteOne()、findOneAndUpdate() 这类单文档写入。updateMany()、deleteMany() 以及任意多文档业务流程,不应因为开启 Retryable Writes 就被视为自动幂等。

下面的完整 Node.js 示例同时打开驱动重试,并用 idempotencyKey 唯一索引处理两次独立业务请求。运行前把环境变量 MONGODB_URI 指向支持会话的 MongoDB 副本集或分片集群。

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

预期输出

text
{"reused":false,"orderNo":"A-1001"}
{"reused":true,"orderNo":"A-1001"}

幂等键必须同时约束身份和内容

幂等键应由调用方在一次业务意图的所有重试中保持不变,例如“提交订单”可使用客户端生成的 UUID。只保存键还不够:如果调用方错误地拿同一个键提交另一份金额或商品列表,服务端应返回冲突,而不是悄悄复用旧结果。因此示例同时保存请求摘要 requestHash。

不要采用“先 findOne(),没有再 insertOne()”作为唯一保护。两个并发请求可能同时查到不存在,然后都尝试插入。真正消除竞态的是唯一索引;前置查询最多只是优化提示,不能替代约束。

认清自动重试不会覆盖的边界

MongoDB 的 Retryable Writes 只对符合条件的数据库写负责,不会替你重放完整业务函数,也不会让“扣款后发邮件”“写 MongoDB 后调用第三方 API”自动变成原子操作。外部系统存在副作用时,应让对方也支持幂等键,或采用 Outbox 等可恢复交付模式。

同样,不要在应用层看到任何异常就无限重试。先区分可重试网络错误、唯一键冲突和业务校验失败,并给重试设置次数与截止时间。最稳妥的职责划分是:驱动处理同一次数据库写的瞬时失败,业务幂等键处理跨请求重复,唯一索引负责并发下的最终一致裁决。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Retryable Writes 与幂等键

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通