TrinityCore 角色数据持久化实战:事务、异步提交与奖励发放的幂等设计 原创
角色保存真正难的是“一致性”
一个角色同时有背包物品、金币、任务进度、技能、声望和位置等状态。自定义拍卖行、跨服功能、离线奖励或 VIP 系统时,如果只执行几条独立 SQL,就可能出现“物品已扣除、货币未到账”或“任务状态已更新、角色记录仍停在旧位置”的问题。
TrinityCore 已经把数据库访问封装为连接池、Prepared Statement 和 Transaction。开发者的任务不是绕过这套机制,而是明确:哪些写入必须成为同一个原子操作,哪些后续动作必须等数据库成功后再执行。
Transaction 的执行模型
核心的 DatabaseWorkerPool 提供三种事务提交方式:
| 接口 | 用途 | 开发时的注意点 |
|---|---|---|
CommitTransaction |
将一组单向 SQL 放入数据库工作队列 | 调用方没有事务结果,不能把它当作“已落盘” |
AsyncCommitTransaction |
异步提交并返回 TransactionCallback |
可在完成后处理成功或失败 |
DirectCommitTransaction |
在当前上下文直接执行事务 | 会等待数据库;不要在敏感主循环中滥用 |
事务可以追加普通 SQL 或 Prepared Statement。ExecuteOrAppend 的意义是:调用方传入有效事务时加入事务,否则独立执行。这使同一函数既能参与一个更大的保存流程,也能单独使用。
SQLTransaction<CharacterDatabaseConnection> trans =
CharacterDatabase.BeginTransaction();
CharacterDatabase.ExecuteOrAppend(trans,
CharacterDatabase.GetPreparedStatement(CHAR_UPD_CHAR_GOLD));
CharacterDatabase.ExecuteOrAppend(trans,
CharacterDatabase.GetPreparedStatement(CHAR_REP_ITEM_CUSTOM_STATE));
CharacterDatabase.CommitTransaction(std::move(trans));
这段代码是结构示意,具体 Statement 名称、绑定参数和枚举应按你使用的 TrinityCore 分支定义添加。不要把示例中不存在的 Statement 直接复制到生产代码。
失败回滚与死锁重试
从 MySQLConnection::ExecuteTransaction 可以看到:事务先执行 Begin,然后逐条运行语句;任意语句执行失败,会记录警告、调用 Rollback 并返回错误码,全部成功后才 Commit。
TransactionTask::Execute 对 ER_LOCK_DEADLOCK 做有限时间的重试,并保证同一时刻只有一个异步线程进入死锁重试区。超过限制仍失败时,记录错误、清理事务并返回失败。
Begin
→ Statement 1
→ Statement 2
→ ...
→ 任一失败:Rollback
→ 全部成功:Commit
死锁:有限重试,不是无限重试
这里有两个重要边界:
- 回滚保护的是同一个数据库事务内的写入,不会自动撤销已经发出的聊天消息、游戏内物品或外部 HTTP 请求。
- 死锁可重试不等于业务一定成功。库存不足、唯一键冲突、数据格式错误等仍需按业务处理。
玩家保存:不要顺手复制一个 SaveToDB
角色、物品、任务和社交数据各有自己的保存时机与脏标记。频繁调用完整角色保存,既可能扩大写入量,也会让问题定位变得困难。正确的做法通常是:
- 复用现有子系统提供的保存函数与脏标记;
- 把同一业务必须一起变化的记录放进一个事务;
- 只在真正修改数据时标记保存需求;
- 退出、断线、定时保存和主动保存之间避免无意义地重复写。
例如一个自定义兑换功能,应把“扣除兑换货币”和“记录已领取奖励”放进同一事务;而发放可见物品、广播全服消息等动作,需要根据结果决定何时执行。
需要结果时,使用 AsyncCommitTransaction
普通 CommitTransaction 更像“排队提交”。如果下一步依赖事务是否成功,就应使用 AsyncCommitTransaction 获取 TransactionCallback,注册 AfterComplete 回调,并在合适的回调处理位置调用 InvokeIfReady。
回调中收到 true 才表示该事务已提交成功。收到 false 后,需要恢复业务状态、通知玩家或安排重试。
TransactionCallback callback =
CharacterDatabase.AsyncCommitTransaction(std::move(trans));
callback.AfterComplete([playerGuid, requestId](bool success) {
if (!success) {
// 记录失败;按业务设计恢复预留状态或允许重试。
return;
}
// 只有成功后才推进依赖数据库结果的业务状态。
});
示例省略了项目特定的回调调度器。真正落地时,还需要回答:回调在哪个线程执行?玩家可能已经下线,指针是否仍有效? 推荐保存 ObjectGuid、请求 ID 等稳定标识,不要轻率捕获裸 Player 指针。
一个自定义奖励发放的可靠流程
可以按下面的职责拆分奖励发放:
1. 验证请求:权限、冷却、参数、当前角色状态
2. 生成唯一 request_id:用于防重复提交和审计
3. 建立事务:
- 写入奖励请求(pending)
- 扣除货币 / 设置领取标记
4. 异步提交并检查结果
5. 成功后推进游戏内可见状态,记录 completed
6. 失败后明确结束 pending,并按设计恢复预留状态
如果“发物品”本身依赖多个核心系统,就必须进一步设计幂等性:同一个 request_id 重试时不能再次发奖。数据库唯一约束、状态机和审计日志比“玩家别连续点按钮”可靠得多。
Prepared Statement 不是可选项
角色名、外部订单号、聊天输入等都可能进入 SQL。不要用字符串拼接构造查询,即使输入看起来只来自管理员。应在 CharacterDatabase 的准备语句定义中注册 Statement,并绑定明确类型的参数。
这不仅降低 SQL 注入风险,也让查询结构集中、参数数量可检查。每次修改字段和绑定参数时,都要同步检查定义、Prepare 和调用点。
上线前的验证清单
| 验证项 | 应观察到的结果 |
|---|---|
| 第二条语句故意失败 | 第一条语句也被回滚 |
| 快速重复提交相同请求 | 不会重复扣费或重复发奖 |
| 提交后立即退出角色 | 回调不会访问失效的 Player 对象 |
| 模拟死锁或锁等待 | 日志可追踪;重试有上限 |
| 异步提交尚未完成时查询状态 | 业务不会把排队误认为已保存 |
| 备份恢复后重放外部请求 | 幂等键能够阻止重复发放 |
数据库事务解决的是原子写入,不能自动解决业务幂等、对象生命周期和跨系统一致性。把这三件事分开设计,才是 TrinityCore 自定义系统稳定运行的基础。
参考源码:TrinityCore Database 模块。本文依据 2026 年 11 月查看的 master 分支,具体接口以所用分支为准。