【框架设计】邮件附件的异步发放：大批量奖励的队列投递

实战应用：用在哪里

全服补偿（万人规模）、活动结算奖励（按排名发放）、 GM 群发——大批量邮件如果同步逐封写入，数据库会被写爆。批量邮件的投递需要队列化：任务拆批、限速写入、失败重试、进度可查。适用于一切万级规模的邮件发放场景。

批量投递的实现

local function dispatchBatch(list, batchId)
    local batch = loadBatchState(batchId) or { cursor = 1 }
    local batchList = list
    for i = batch.cursor, #batchList do
        local ok, err = writeMail(batchList[i])
        if not ok then
            saveBatchState(batchId, i)          -- 记录游标，下次从断点继续
            return false, err
        end
    end
    saveBatchState(batchId, #batchList + 1)
    return true
end

游标持久化让中断后可以从断点续投，不重不漏。写入限速（每秒 200 封）保护数据库，批间隔 sleep 控制节奏。

附件的托管与领取

批量邮件的附件多为补偿道具：附件在邮件创建时入托管库（不进玩家背包），玩家领取时校验托管记录后入包。托管记录带唯一领取键（batchId + 玩家 id），重复领取被唯一键拦截——万人规模的补偿不会因为重复点击而多发。

对账与撤回

批量投递完成后输出对账单：应收件人数、实际投递数、失败清单（失败原因分类）。运营撤回场景（发错内容）支持按 batchId 整批撤回未领取的邮件（已领取的不追回，走单独补偿流程）。某项目万人补偿的投递从逐封同步的 40 分钟缩短到 3 分钟，投递期间服务负载曲线平稳。批量邮件框架建好后，运营的补偿、结算、通知三类需求都走同一通道，运维成本从每次特批变成后台配置。

批量邮件的正文变量白名单：模板里允许的变量只有玩家名、角色名、金额、道具清单四类，白名单外的占位符在预检阶段报错。变量值全部来自服务端数据，不接受运营在模板里引用任意玩家字段，防止模板被改造成信息泄露的通道。

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