【后端接口】setontimerex：全局定时器与活动调度的引擎实现

实战应用：用在哪里

全局定时器 setontimerex 是服务器的闹钟：世界 BOSS 的 6 小时刷新、活动的整点开启、跨天数据的零点重算，全靠它按秒调度。与个人定时器 setontimer 的区别在于归属：个人定时器跟着玩家走，全局定时器属于整个服务器。

接口签名与调度

---添加全局定时器 id:定时器ID tick:间隔秒
function setontimerex(id, tick) end

-- 世界 BOSS 重置：6 小时后触发一次回调
setontimerex(7700, 21600)

id 是全局定时器的身份，tick 是间隔秒数，回调按 id 路由到对应的处理函数。全局定时器的数量要节制：每一个都是常驻的调度任务，服务器的定时器总表建议控制在百个以内，超出时用合并调度（一个定时器轮询多任务）替代。

回调路由与幂等

-- 全局定时器回调的统一路由
function ontimerex(id)
    local handler = EX_TIMER_HANDLERS[id]
    if handler then pcall(handler) end
end

EX_TIMER_HANDLERS = {
    [7700] = WorldBoss.refresh,
    [7701] = Activity.openEvening,
    [7702] = Rank.flushDaily,
}

回调按 id 查处理函数表，pcall 保护单个任务的异常不传染。幂等设计：活动开启类回调要自带状态检查（已开启则跳过），定时器的重复触发不产生重复效果。定时器的移除（setofftimerex）在任务完成时调用，一次性的倒计时任务触发后即注销，常驻任务保持注册。

验证与监控

全局定时器的触发时刻与预期偏差监控，偏差超过 2 秒说明调度线程拥挤。

踩坑记录

两个定时器用了同一个 id，互相覆盖导致活动没开，id 的分配表按业务段管理后绝迹。回调里做重活（排行榜全量重算）曾经阻塞调度线程，后续的定时器全部延后，重任务改为投递给工作队列。

上线要点

全局定时器的 id 分配表进文档管理，新增定时器先申请号段。定时器回调的耗时打点上报告警，超过 100 毫秒的回调要求拆分或异步化。服务器重启后的定时器重建依赖启动触发（startup）里的注册逻辑，重建的完整性用启动自检清单核对。

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