【Lua实战】模块化与 require：循环依赖的处理

实战应用：用在哪里

项目的模块多了之后，require 的加载顺序成了暗雷：战斗模块引用行会模块、行会模块又引用战斗模块，循环依赖让其中一个模块拿到半成品。模块化的设计要点是职责的切分、依赖的单向与循环的化解。

循环依赖的现场

---combat.lua 的开头
local Guild = require("guild")
local Combat = {}
function Combat.onKill(actor)
    Guild.addContribution(actor, 10)
end
return Combat

---guild.lua 的开头
local Combat = require("combat")   -- 循环！
local Guild = {}
function Guild.onWarEnd(actor)
    Combat.countWars(actor)
end
return Guild

循环依赖的症状取决于加载的顺序：先加载 combat 时，guild 的 require 返回的是还没填充内容的半成品表，调用 Guild.addContribution 直接报 nil 错误。错误的飘忽让排查痛苦——本地的加载顺序与生产不同，Bug 就时隐时现。

依赖的化解

---化解一：延迟 require（用到时再加载）
local Combat = {}
function Combat.onKill(actor)
    local Guild = require("guild")   -- 函数体内延迟加载
    Guild.addContribution(actor, 10)
end
return Combat

---化解二：事件解耦（互相不引用）
---combat.lua 发事件
local Bus = require("event_bus")
function Combat.onKill(actor)
    Bus.publish("kill", actor)
end
---guild.lua 订阅事件
Bus.subscribe("kill", function(actor)
    Guild.addContribution(actor, 10)
end)

循环的化解两条路：函数体内的延迟 require 把加载挪到调用的时刻（半成品问题消失，代价是每次调用的一次查找），事件的解耦让两个模块互相不引用（发布订阅的中介把依赖切成单向）。依赖的治理有规范：模块的依赖图保持有向无环，新模块的接入画依赖图评审——环在图上出现就当场化解。模块的接口收窄：require 只拿模块的公开表，内部的状态与函数加 local 前缀不导出，模块之间的耦合面降到最小。

验证与监控

加载顺序的自检：启动时按依赖图校验模块的加载，环的检测在启动期报错；模块的接口清单与文档的同源比对，导出了不该导出的内部函数进评审。

踩坑记录

延迟 require 曾经放在热路径，每次调用的查找让性能下降可测，加载结果的 local 缓存（首次延迟后缓存）修复。事件的解耦曾经没有退订，模块的热重载后重复订阅，事件翻倍执行，退订的配对补上。模块的半成品状态曾经被缓存，半成品表的引用被存下后即使加载完成也是旧的，缓存的时机在加载完成后。

上线要点

依赖图的可视化进架构的看板，环的出现当天化解。模块的公开接口进文档，私有前缀的约定全员遵守。启动的加载顺序测试进构建流水线，顺序的回归在合并前暴露。

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