【框架设计】门面模式 Facade：复杂子系统的统一入口

实战应用：用在哪里

发一封系统邮件背后要五步：校验参数、扣邮件配额、写邮件表、推通知、写审计日志。调用方需要知道五步的顺序与细节，每个新调用点都可能漏一步。门面模式在子系统前放一个简化入口 MailFacade.send(playerId, itemId, count, reason)，一行完成全部流程，内部细节对外关闭。

门面的实现

local MailFacade = {}

function MailFacade.sendReward(playerId, itemId, count, reason)
    -- 内部按序调五个子系统，任何一步失败即中断并回滚
    local ok = Quota.use("mail", playerId)
    if not ok then return false, "邮件配额不足" end
    local mailId = MailStore.create(playerId, itemId, count, reason)
    Notify.push(playerId, "您有新的系统邮件")
    Audit.log("MAIL", playerId, mailId, reason)
    return true, mailId
end

return setmetatable(MailFacade, {
    __newindex = function() error("门面只读，禁止外部扩展", 2) end,
})

两条设计纪律

门面不做业务决策。 门面只编排顺序与传递参数，条件分支（该不该发）由调用方判断后传入，否则门面会膨胀成新的上帝对象。异常必须翻译。 子系统抛出的原始错误（表名、SQL 细节）在门面层翻译成业务语言（配额不足、收件人不存在），调用方永远不需要理解子系统内部。

收益的量化视角

改造前发送邮件的调用点有 11 处，其中 3 处漏了通知、2 处漏了审计。门面收敛后调用点 11 处不变，但流程细节只有 1 份实现——漏步骤类 bug 的修复从“逐个调用点补”变成“门面改一行”。门面模式的适用判断：同一子系统被 3 个以上模块调用、调用序列固定，就值得包一层门面。

门面的测试收益可以量化：给门面写一组假件依赖（假配额、假邮件存储），单测里直接断言调用序列与参数，邮件流程的回归测试不再需要真实环境。门面暴露的方法签名就是测试用例的清单，方法数量稳定在十个以内时门面保持健康，超过二十个说明子系统该拆分了。拆分的信号还有调用方开始绕过门面直接访问子系统，出现一次就要检查门面的接口设计是否缺失。

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