【数据存储】批量写入：道具流水的攒批落库

实战应用：用在哪里

道具流水是写入量最大的表：拾取、消耗、交易、分解，一个活跃玩家一天产生上百条流水，千人在线就是每秒几百条 INSERT。单条直写把数据库压垮在高峰，攒批落库把碎写入合并成大事务，IO 的压力按倍数下降。

攒批的缓冲

---流水缓冲：攒满 200 条或每 2 秒落库
local buffer = {}
local FLUSH_N = 200

function Ledger.add(actor, kind, itemName, count)
    buffer[#buffer + 1] = {
        uid = actor:GetUserId(),
        kind = kind,
        item = itemName,
        cnt = count,
        at = os.time(),
    }
    if #buffer >= FLUSH_N then
        Ledger.flush()
    end
end

流水先进内存缓冲，攒满 200 条触发落库。缓冲的写入是纯内存操作，游戏逻辑不等数据库——拾取一把裁决之杖的流水记录耗时从 8 毫秒降到微秒级。缓冲的容量即风险敞口：宕机丢失最多 200 条流水，流水的对账兜底（定期与背包快照核对）让这笔敞口可接受。

落库的合并

---批量落库：单条 INSERT 多 VALUES
setontimerex(51, 2)
function Ledger.flush()
    if #buffer == 0 then return end
    local values = {}
    for i, r in ipairs(buffer) do
        values[i] = string.format(
            "('%s','%s','%s',%d,%d)",
            r.uid, r.kind, r.item, r.cnt, r.at)
    end
    local sql = "INSERT INTO item_log VALUES " .. table.concat(values, ",")
    DB.exec(sql)
    buffer = {}
end

落库用多值 INSERT 合并：200 条流水拼成一条 SQL，一次网络往返、一次事务提交，数据库的写入吞吐提升二十倍以上。定时器每 2 秒兜底刷一次，不满 200 条的尾巴不会滞留太久。写入的下游是风控的对账任务：流水与背包快照的核对按小时跑，异常的差额告警——批量化的写入让对账的粒度保持完整。流水的表按月分表，写入的热表永远只有当月，查询走分表路由。

验证与监控

缓冲水位与落库耗时监控，落库单次超过 500 毫秒即分批拆分；宕机演练的流水丢失条数核验，超过缓冲上限即为缓冲实现缺陷。

踩坑记录

批量 SQL 曾经超长，单条 8 MB 的 SQL 被数据库拒绝，批次按 500 条切割。缓冲曾经无锁并发追加，两条协程同时 flush 丢数据，flush 的互斥锁补上。string.format 的流水拼接曾经没转义物品名，名字带单引号的玩家让 SQL 报错，参数转义统一走工具函数。

上线要点

缓冲的条数与时间双阈值进配置，写入洪峰时条数阈值动态下调。流水的关键字段（玩家、物品、数量、来源）建联合索引，风控的查询模式倒推索引设计。落库失败的退避重试三次后转存本地文件，人工补录的通道永远留着。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。