monSQLize

    findOneAndDelete() - 原子查找并删除

    📑 目录

    原子地查找并删除单个文档，返回被删除的文档。这是一个原子操作，适合需要获取旧值同时删除的场景。

    语法

    collection(collectionName).findOneAndDelete(filter, options)

    参数

    filter (Object, 必需)

    筛选条件。

    options (Object, 可选)

    选项类型默认值说明
    projectionObject-字段投影
    sortObject-排序条件
    maxTimeMSNumber-最大执行时间
    commentString-操作注释
    collationObject-排序规则
    hintString/Object-索引提示
    includeResultMetadataBooleanfalse是否包含完整元数据

    返回值

    默认返回被删除的文档对象或 null（未找到）。

    如果 includeResultMetadata: true，返回：

    {
  value: <文档或null>,
  ok: 1,
  lastErrorObject: { n: 1 }
}

    ⚠️ 重要提示 - MongoDB 驱动 6.x 兼容性

    monSQLize 使用 MongoDB Node.js 驱动 6.x，该版本对 findOneAndDelete 的返回值格式进行了重要变更：

    驱动 6.x (当前版本):

    • 默认直接返回文档对象
    • 需要显式设置 includeResultMetadata: true 才返回完整元数据

    驱动 5.x 及更早版本:

    • 默认返回完整元数据 { value, ok, lastErrorObject }

    ✅ monSQLize 的处理:

    • 已在内部自动处理此差异，用户无需关心驱动版本
    • API 行为保持一致，向后兼容
    • 详见技术分析报告: analysis-reports/2025-11-17-mongodb-driver-6x-compatibility.md

    核心特性

    原子性保证

    // ✅ 原子操作 - 查找和删除在同一事务中
const deletedTask = await collection("tasks").findOneAndDelete({
  status: "pending",
  assignedTo: null
});

if (deletedTask) {
  console.log("获取到任务:", deletedTask.taskId);
  // 处理任务...
}

// ❌ 非原子 - 有竞态条件风险
const task = await collection("tasks").findOne({ status: "pending" });
if (task) {
  await collection("tasks").deleteOne({ _id: task._id });
  // 在这期间其他进程可能已经获取了同一个任务！
}

    常见场景

    场景 1: 任务队列消费

    // 从队列中获取并删除一个任务（原子操作）
async function getNextTask() {
  const task = await collection("taskQueue").findOneAndDelete(
    { 
      status: "pending",
      scheduledAt: { $lte: new Date() }
    },
    { 
      sort: { priority: -1, scheduledAt: 1 }
    }
  );

  return task;
}

// 多个 Worker 并发调用也安全
const task = await getNextTask();
if (task) {
  await processTask(task);
}

    场景 2: 会话清理

    // 删除过期会话并记录
async function cleanupExpiredSession(sessionId) {
  const deletedSession = await collection("sessions").findOneAndDelete({
    sessionId,
    expiresAt: { $lt: new Date() }
  });

  if (deletedSession) {
    console.log(`已清理会话: ${sessionId}`);
    // 记录到审计日志
    await collection("auditLogs").insertOne({
      action: "SESSION_EXPIRED",
      userId: deletedSession.userId,
      timestamp: new Date()
    });
  }

  return deletedSession;
}

    场景 3: 分布式锁释放

    // 获取锁信息并删除
async function releaseLock(lockKey, ownerId) {
  const lock = await collection("locks").findOneAndDelete({
    lockKey,
    ownerId,
    expiresAt: { $gt: new Date() }
  });

  if (!lock) {
    throw new Error("锁不存在或已被其他进程持有");
  }

  console.log(`锁已释放: ${lockKey}`);
  return lock;
}

    与其他方法的区别

    特性findOneAndDeletedeleteOnedeleteMany
    返回值被删除的文档删除统计删除统计
    原子性✅ 原子操作✅ 原子操作✅ 原子操作
    获取旧值✅ 支持❌ 不支持❌ 不支持
    删除数量最多 1 个最多 1 个多个

    相关方法