NoSQL 与搜索 / 系统课时
设计多文档事务
设计多文档事务
MongoDB 单文档写本身就是原子的,但余额转移、库存与流水同步等场景可能要求多个文档一起成功或一起失败。本课用会话与 withTransaction() 组织事务,并重点处理重试边界、超时和性能成本。
学习目标
- 判断什么时候确实需要多文档事务,什么时候应先调整数据模型。
- 使用同一会话执行事务,并理解提交与整笔事务的不同重试路径。
- 控制事务时长、冲突范围和外部副作用,降低生产环境成本。
先判断能否通过建模消除事务
事务不是“让 MongoDB 更安全”的通用开关。若一组数据天然属于同一个聚合,例如订单头与少量固定明细,把它们嵌入同一文档通常能直接利用单文档原子性,减少快照维护、冲突和失败重试。
当多个独立聚合必须保持一个业务不变量时,多文档事务才更合适。例如账户 A 减少 100 元、账户 B 增加 100 元,并写入一条转账流水;这三步若任意一步失败,都不能留下部分结果。此时建模无法合理合并对象,事务才是在正确边界上解决问题。
把事务生命周期放进同一个会话
事务中的所有读写都必须携带同一个 ClientSession。便利 API withTransaction() 会围绕事务回调和提交阶段处理 MongoDB 定义的可重试错误:遇到 TransientTransactionError 时可重新执行整笔事务,遇到 UnknownTransactionCommitResult 时重点重试提交确认。

withTransaction() 的回调可能执行多次,所以回调内部应只包含可安全重做的数据库逻辑。发送邮件、调用支付网关、发布不可撤销消息等外部副作用不要直接放进去;应在事务内记录待发送事件,再由事务外的可靠流程投递。
用 withTransaction 编排跨文档转账
下面示例准备两个账户,然后在一次事务内完成扣款、入账和流水写入。运行前把 MONGODB_URI 指向支持事务的 MongoDB 副本集或分片集群,并确保当前用户对 bank 数据库具备读写权限。
import { MongoClient } from 'mongodb';
const uri = process.env.MONGODB_URI;
if (!uri) throw new Error('MONGODB_URI is required');
const client = new MongoClient(uri);
async function main() {
await client.connect();
const db = client.db('bank');
const accounts = db.collection('accounts');
const ledger = db.collection('ledger');
// 仅为演示准备可重复的初始数据,不属于事务主体。
await accounts.replaceOne({ _id: 'A' }, { _id: 'A', balance: 1000 }, { upsert: true });
await accounts.replaceOne({ _id: 'B' }, { _id: 'B', balance: 200 }, { upsert: true });
await ledger.deleteOne({ _id: 'tx-1001' });
const session = client.startSession();
try {
await session.withTransaction(async () => {
const debit = await accounts.updateOne(
{ _id: 'A', balance: { $gte: 100 } },
{ $inc: { balance: -100 } },
{ session }
);
if (debit.modifiedCount !== 1) {
throw new Error('INSUFFICIENT_FUNDS');
}
const credit = await accounts.updateOne(
{ _id: 'B' },
{ $inc: { balance: 100 } },
{ session }
);
if (credit.modifiedCount !== 1) {
throw new Error('DESTINATION_NOT_FOUND');
}
// 流水与余额变化在同一事务中提交,避免只完成其中一部分。
await ledger.insertOne(
{ _id: 'tx-1001', from: 'A', to: 'B', amount: 100 },
{ session }
);
}, {
readConcern: { level: 'snapshot' },
writeConcern: { w: 'majority' },
readPreference: 'primary',
maxCommitTimeMS: 5000
});
const result = await accounts.find({ _id: { $in: ['A', 'B'] } })
.sort({ _id: 1 })
.toArray();
const ledgerCount = await ledger.countDocuments({ _id: 'tx-1001' });
console.log(JSON.stringify({
A: result[0].balance,
B: result[1].balance,
ledgerCount
}));
} finally {
await session.endSession();
}
}
main()
.catch(console.error)
.finally(() => client.close());预期输出
{"A":900,"B":300,"ledgerCount":1}balance: { $gte: 100 } 把“余额足够”与扣款合并进同一次条件更新,避免先读取余额再无条件写入造成并发窗口。若目标账户不存在或余额不足,回调抛错,事务不会留下部分提交。
区分整笔事务重试和提交重试
执行阶段出现可恢复冲突时,整笔事务可能重新开始,因此回调必须允许重复执行。提交阶段若客户端无法判断提交结果,正确动作通常是再次确认提交,而不是直接再跑一遍业务逻辑。便利 API 已封装这类协议;若改用 startTransaction()、commitTransaction() 等 Core API,就需要应用自己按错误标签实现对应重试。
此外,业务级重复请求仍要单独考虑幂等性。事务解决的是“一次执行中的多文档原子性”,并不自动阻止调用方把同一转账请求重新提交一次。生产系统通常还会给转账流水建立业务唯一键。
控制时长、冲突和资源成本
事务应尽量短,只包含维护不变量所需的数据库操作。不要在事务中等待用户输入、做长时间计算或调用慢速外部服务;这些操作会延长快照与资源占用,并提高写冲突和回滚概率。
为事务查询建立合适索引,避免在事务内扫描大量文档。maxCommitTimeMS 只限制提交命令的等待时间,不等于整笔事务的总超时;应用还应设置自己的请求截止时间。MongoDB 也有可配置的事务生命周期限制,因此不应把长事务当成批处理机制。
当一个流程频繁因为写冲突重试、触碰大量文档或跨越很长时间,优先重新审视数据模型和业务边界。多文档事务最适合保护少量、短时、强相关的状态变更;能通过单文档聚合完成的原子更新,通常仍是 MongoDB 中成本更低的选择。