【框架设计】单例模式实现：配置中心与全局状态统一入口

实战应用：用在哪里

单例适合全局唯一的对象：配置中心、日志器、音效管理器、排行榜管理器。996 服务端的任务系统、公告系统都要求"同一时刻只有一份实例、任何脚本读到同一份数据"，散落在各文件里的全局变量一旦重名就会互相覆盖，单例把这些入口收拢到一个 getInstance() 之后。

标准实现：局部实例 + 私有构造

local ConfigCenter = {}
ConfigCenter.__index = ConfigCenter

local instance = nil            -- 闭包私有，外部拿不到

function ConfigCenter.getInstance()
    if not instance then
        instance = setmetatable({ map = {}, loadTime = os.time() }, ConfigCenter)
        instance:loadAll()
    end
    return instance
end

function ConfigCenter:get(key)
    return self.map[key]
end

function ConfigCenter:reload()
    self.map = {}
    self:loadAll()
end

-- 访问方式（三个文件拿到的是同一份）
local cfg = ConfigCenter.getInstance()

instance 是文件级 local，配合 __index 元表，外部只能通过 getInstance() 拿到对象，构造路径被收窄到一处。热更时调用 :reload()，实例指针不变、数据整体刷新，已持有的引用不会失效。

防污染：禁止二次赋值

单例最常见的破坏来自别处 ConfigCenter.instance = {} 一类的误写。两个防护：构造函数不再暴露 new（删掉或抛错）；模块返回值用只读代理包一层，写入时 error：

local readonly = setmetatable({}, {
    __index = ConfigCenter,
    __newindex = function() error("单例只读，请用 getInstance()", 2) end,
})
return readonly

状态检查清单

上线前核对四项：os.time() 加载时间戳有日志记录（确认加载了几次）；getInstance() 在多协程环境下无副作用（Lua 单线程天然安全）；重载后旧表被 GC（collectgarbage("count") 前后对比）；全项目 grep 确认只有一处 getInstance 初始化路径。这套模式在任务系统、公告系统、邮件系统上可以原样复用，改动只在 loadAll 内部。

与依赖注入的配合

单例与依赖注入并不对立，正确的关系是：组装层只有一个全局可见的单例（或少量几个），其余模块的依赖全部从参数传入。实操写法——业务函数不直接调 ConfigCenter.getInstance()，而是入口处在启动时取一次实例传进模块构造：

-- 入口组装（仅一处出现单例调用）
local RewardService = newRewardService(ConfigCenter.getInstance(), BagService)

-- 业务模块拿到的只是参数，可测试、可替换
function RewardService.grant(playerId, itemId)
    local cfg = cfgCenter:get("item", itemId)
    ...
end

这样单例负责"唯一性"，注入负责"可替换性"，两个职责不再互相污染。测试时传一个假配置中心即可跑通全部业务逻辑，不必触碰真实配置。单例数量控制在个位数（配置、日志、网络三个以内），其余依赖一律走注入，项目的全局复杂度就能长期保持在可读范围。

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