Lua 模块：require() 与 module()

Lua 模块化系统是组织代码、避免全局命名空间污染的核心机制。在 Lua 的不同版本演进中，定义和加载模块的方式发生了显著变化。理解 require() 的加载机制以及 module() 的历史遗留问题，对于编写健壮、可维护的 Lua 代码至关重要。

理解 require() 的加载机制

require() 是 Lua 中加载模块的标准函数。它不同于简单的 dofile()，因为它会处理模块的搜索路径、缓存已加载的模块以及防止重复加载。

当调用 require("my_module") 时，Lua 会按照既定逻辑执行搜索和加载。这个过程的核心在于 package.loaded 表，它充当了模块缓存的角色。

注意：如果模块文件中没有显式 return 一个值（通常是表格），require() 默认会将 true 存入缓存。这意味着第二次调用 require() 时，即使模块内部逻辑期望返回一个表，也可能拿到 true，导致报错。

认识 module() 函数及其问题

在 Lua 5.1 及早期版本中，module() 函数被广泛用于创建模块。它提供了一种快速定义模块命名空间的方式，通常结合 package.seeall 使用。

然而，module() 在现代 Lua 开发（Lua 5.2+ 及 LuaJIT 2.1+）中已被废弃，主要因为它会导致以下严重问题：

1. 全局污染：module("my_mod") 会创建一个全局变量 my_mod，这违背了模块化封装的初衷。
2. 环境变更：它会改变函数的环境（ _ENV 或 setfenv），导致模块内部难以访问外部全局变量（如 print），除非配合 package.seeall。
3. 安全隐患：package.seeall 将模块的环境设置为全局环境（_G），使得模块可以随意访问全局数据，同时也容易被外部恶意修改。

采用现代模块定义模式

为了保证代码的兼容性和安全性，抛弃 module()，转而使用显式返回局部表格的模式。这是目前业界公认的最佳实践。

按照以下步骤编写一个标准的 Lua 模块：

1. 声明 一个局部表格用于存储模块的公共接口。
2. 定义 局部函数或变量作为内部实现细节（私有成员）。
3. 将 需要暴露的函数或变量挂载到第一步声明的表格中。
4. 返回 该表格。

以下是一个标准的模块编写模板：

-- 文件名: my_complex_calc.lua

-- 1. 声明局部命名空间
local M = {}

-- 2. 定义局部私有变量（外部无法直接访问）
local private_constant = 42

-- 3. 定义私有辅助函数
local function helper(x)
    return x * private_constant
end

-- 4. 导出公共函数
function M.calculate(input)
    -- 调用私有辅助函数
    local result = helper(input)
    return result
end

-- 5. 导出公共常量
M.version = "1.0.0"

-- 6. 返回模块表
return M

在另一个文件中使用该模块：

-- 文件名: main.lua
local calc = require("my_complex_calc")

-- 通过模块表调用公共接口
print(calc.calculate(2)) -- 输出: 84
print(calc.version)     -- 输出: 1.0.0

-- 尝试访问私有成员会返回 nil
print(calc.private_constant) -- 输出: nil
print(calc.helper)           -- 输出: nil

旧模式与新模式的对比

为了更清晰地展示为何推荐新模式，以下对比 module() 写法与现代写法的区别：

处理模块加载路径

当 require() 找不到文件时，通常是因为 package.path 配置不正确。package.path 是一个模板字符串，用于指定搜索位置。

检查当前的搜索路径：

print(package.path)

输出示例可能如下：

./?.lua;/usr/local/share/lua/5.4/?.lua;/usr/local/share/lua/5.4/?/init.lua

这里的 ? 会被替换为 require() 中传入的模块名。例如，require("foo.bar") 会尝试查找 ./foo/bar.lua。

临时修改搜索路径（通常用于测试）：

-- 将当前目录添加到搜索路径的最前面
package.path = "./?.lua;" .. package.path

-- 现在可以加载当前目录下的模块了
local my_mod = require("my_mod")

处理循环引用

在实际工程中，偶尔会出现模块 A 需要加载模块 B，而模块 B 又需要加载模块 A 的情况。直接处理会导致死循环或加载到未初始化的空表。

解决循环引用的步骤：

1. 在模块 A 中，先 require 模块 B。
2. 在模块 B 中，如果在初始化时需要调用模块 A 的函数，将 require 语句延迟到函数内部执行。

示例代码：

-- 文件名: a.lua
local M = {}

local b = require("b") -- 加载 B

function M.do_something()
    print("A is doing something")
    b.help_a() -- 调用 B
end

return M

-- 文件名: b.lua
local M = {}

-- 注意：这里不能直接 require("a")，否则会死循环或导致 a 为 nil

function M.help_a()
    -- 将 require 放在函数内部
    -- 此时 A 已经初始化完成并缓存
    local a = require("a") 
    print("B is helping A")
end

return M