【框架设计】任务队列串行化：异步步骤的顺序执行与失败中断

实战应用：用在哪里

跨服迁移、批量发放、数据迁移这类“多步骤强顺序”的业务，步骤之间有硬依赖：上一步失败下一步必须停止。通用串行队列把步骤组织成数组，逐个执行、失败中断、可从失败步骤重试。

队列实现：步骤数组 + 索引推进

local function runQueue(queue)
    while queue.idx <= #queue.steps do
        local step = queue.steps[queue.idx]
        local ok, err = pcall(step.fn, queue.ctx)
        if not ok then
            queue.failedAt = queue.idx
            queue.err = err
            return false
        end
        queue.idx = queue.idx + 1
    end
    return true
end

-- 从失败步骤重试
local function retry(queue)
    return runQueue(queue)                    -- idx 停留在失败步骤
end

每个步骤是一个函数，接收共享上下文 ctx（前序步骤的产出放 ctx 里传递）。失败时 idx 停留在失败步骤，修复问题后 retry 从该步骤继续，已完成的步骤不重复执行。

持久化：断电恢复

跨服迁移这类长流程把队列状态（ctx 与 idx）序列化落盘，进程重启后从落盘状态恢复执行。落盘时机：每完成一步落一次（步骤粒度足够细，单步损失可接受）。步骤函数要求幂等——重启后从当前步骤重跑一遍，已生效的部分因幂等而不产生副作用。

使用边界

串行队列适合“步骤少于 20、依赖明确、失败需要人工介入”的流程；大数量的批量任务用分帧调度（性能调优篇）或专业队列系统。判据是失败后的行为：需要人工修复后继续的走串行队列，可以自动放弃的用事件总线广播即可。两套机制并存、按业务选择，异步代码的结构就清晰了。

步骤的幂等要求写在每个步骤的注释里：该步骤重复执行是否安全、不安全时的保护机制是什么。幂等的手法有三类：状态机推进（重复请求返回首次结果）、唯一键去重（数据库唯一索引挡重复写入）、乐观锁（版本号比对后更新）。三类手法覆盖九成场景，步骤作者按业务语义选择即可。

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