8. 模块与包 (Modules and Packages)

文档摘要

模块与包 (Modules and Packages) Lua 模块与包 (Modules and Packages) 详解与代码实践在任何成熟的编程语言中，代码组织和重用都是至关重要的。Lua 作为一种轻量级、高效且灵活的脚本语言，也提供了强大的模块和包机制来帮助开发者构建可维护、可扩展的代码库。模块和包允许我们将代码分割成独立的单元，提高代码的组织性、可重用性和可维护性，并有效地管理命名空间，避免命名冲突。模块 (Modules) 1.1 模块的概念与意义在 Lua 中，模块 (Module) 是一个包含 Lua 代码的独立文件，用于封装一组相关的函数、变量和数据结构。模块的主要目的是：代码组织: 将大型程序分解为更小的、更易于管理的模块，提高代码的可读性和可维护性。

8. 模块与包 (Modules and Packages)

Lua 模块与包 (Modules and Packages) 详解与代码实践

在任何成熟的编程语言中，代码组织和重用都是至关重要的。Lua 作为一种轻量级、高效且灵活的脚本语言，也提供了强大的模块和包机制来帮助开发者构建可维护、可扩展的代码库。模块和包允许我们将代码分割成独立的单元，提高代码的组织性、可重用性和可维护性，并有效地管理命名空间，避免命名冲突。

1. 模块 (Modules)

1.1 模块的概念与意义

在 Lua 中，模块 (Module) 是一个包含 Lua 代码的独立文件，用于封装一组相关的函数、变量和数据结构。 模块的主要目的是：

代码组织: 将大型程序分解为更小的、更易于管理的模块，提高代码的可读性和可维护性。
代码重用: 允许在不同的程序或项目中重用模块中的代码，减少重复开发工作。
命名空间管理: 模块创建独立的命名空间，避免全局命名冲突，提高代码的健壮性。
封装性: 模块可以控制哪些部分对外可见，哪些部分保持内部私有，实现一定程度的封装。

1.2 创建模块

Lua 中创建模块主要有几种常见的方式，最推荐和常用的方式是使用 return 语句返回一个表 (table)。

1.2.1 使用 return 表创建模块 (推荐)

这是最常见和推荐的模块创建方式。我们将模块的代码放在一个单独的文件中，文件末尾使用 return 语句返回一个表，这个表包含了模块需要导出的函数和变量。

示例：创建一个名为 math_utils.lua 的模块


-- math_utils.lua 文件
local M = {}  -- 创建一个空表作为模块
-- 私有函数 (模块内部使用，外部不可直接访问)
local function factorial_internal(n)
    if n == 0 then
        return 1
    else
        return n * factorial_internal(n - 1)
    end
end
-- 公有函数 (模块导出，外部可以访问)
function M.add(a, b)
    return a + b
end
function M.subtract(a, b)
    return a - b
end
function M.multiply(a, b)
    return a * b
end
function M.divide(a, b)
    if b == 0 then
        error("division by zero")
    end
    return a / b
end
function M.factorial(n)
    if n < 0 then
        error("factorial of negative number")
    end
    return factorial_internal(n) -- 调用私有函数
end
M.PI = 3.1415926 -- 导出常量
return M  -- 返回模块表

代码详解：

local M = {}: 首先创建一个名为 M 的局部空表。这个表将作为我们模块的容器，用于存放要导出的函数和变量。使用 local 关键字确保 M 表本身不会成为全局变量，保持模块的封装性。
local function factorial_internal(n): 定义了一个 factorial_internal 函数，并使用 local 关键字使其成为局部函数。这意味着这个函数只能在 math_utils.lua 模块内部访问，外部无法直接调用，实现了模块的私有性。
function M.add(a, b) 等: 定义了一系列公有函数，并将它们添加到 M 表中。通过 M.add 的形式，我们将函数 add 关联到 M 表的 add 字段。这些函数将成为模块导出的功能，可以被外部代码调用。
M.PI = 3.1415926: 定义了一个常量 PI 并将其添加到 M 表中，使其成为模块导出的常量。
return M: 最后，使用 return M 语句返回 M 表。这个表就是我们创建的模块对象，它包含了所有导出的函数和变量。

1.2.2 使用 module() 函数 (不推荐，历史遗留)

在 Lua 的早期版本中，曾经推荐使用 module() 函数来创建模块。但现在 module() 函数已经被认为是不推荐使用的方法，因为它会污染全局环境，并可能导致命名冲突。 这里仅做了解，不建议在新的项目中使用。


-- my_module.lua 文件 (不推荐使用 module())
module("my_module") -- 创建模块并设置模块名 (全局变量)
-- 模块代码...
function my_function()
    print("Hello from my_module")
end
MY_CONSTANT = 100

为什么不推荐 module()?

全局变量污染: module("my_module") 会创建一个全局变量 my_module，并把后续定义的函数和变量都放入这个全局表中。这污染了全局命名空间，增加了命名冲突的风险。
难以理解的副作用: module() 函数还会修改 package.loaded 表和 _G 表，引入了一些不必要的副作用，使得模块的行为变得难以预测和理解。

总结： 为了代码的清晰性和可维护性，以及避免全局命名空间污染，强烈推荐使用 return 表的方式来创建 Lua 模块。

1.3 加载模块：`require()` 函数

要使用一个模块，我们需要使用 require() 函数来加载它。require() 函数是 Lua 中加载和执行模块的关键。

示例：在另一个 Lua 文件中使用 math_utils 模块


-- main.lua 文件
local math_utils = require("math_utils") -- 加载 math_utils 模块
print(math_utils.add(5, 3))        -- 调用模块中的函数
print(math_utils.PI)              -- 访问模块中的常量
print(math_utils.factorial(5))     -- 调用模块中的函数
-- print(math_utils.factorial_internal(5)) -- 错误！无法访问私有函数
-- 再次 require 同一个模块
local math_utils_again = require("math_utils")
print(math_utils == math_utils_again) -- 输出 true，说明模块只加载一次

代码详解：

local math_utils = require("math_utils"): 使用 require("math_utils") 加载名为 "math_utils" 的模块。
- require() 函数会查找名为 "math_utils" 的文件（通常是 math_utils.lua），执行文件中的代码，并返回模块返回的值（在我们的例子中是 return M 返回的表）。
- 加载的模块被赋值给局部变量 math_utils。
math_utils.add(5, 3) 等: 通过 math_utils.函数名 或 math_utils.变量名 的方式，访问和调用模块中导出的函数和变量。
print(math_utils == math_utils_again): 再次 require("math_utils")，会发现 math_utils 和 math_utils_again 变量引用的是同一个模块对象。require() 函数具有缓存机制，对于同一个模块，只会加载和执行一次。 后续的 require() 调用会直接返回缓存中已加载的模块对象，避免重复加载和执行，提高效率。

1.4 `require()` 的工作原理和模块查找路径 `package.path`

require() 函数在加载模块时，遵循一定的查找路径和规则：

检查 package.loaded 表: require() 首先会检查 package.loaded 表，看是否已经加载过同名的模块。如果已经加载，则直接返回 package.loaded 表中缓存的模块对象，不再重复加载。
搜索模块文件: 如果 package.loaded 表中没有找到，require() 会根据 package.path 变量定义的路径列表，依次搜索模块文件。
- package.path 是一个字符串，包含一系列用分号 ; 分隔的路径模式。 每个路径模式中可以使用 ? 占位符，require() 会用模块名替换 ?。
- 默认的 package.path 通常包含以下路径：
  - 当前目录 (.)
  - Lua 标准库目录
  - 系统环境变量 LUA_PATH 定义的路径
- 示例 package.path 可能如下：
```
"./?.lua;./?.lc;/usr/local/share/lua/5.4/?.lua;/usr/local/share/lua/5.4/?/init.lua;/usr/local/lib/lua/5.4/?.lua;/usr/local/lib/lua/5.4/?/init.lua;./?.lua;./?.lc;..."
```
- 查找过程：
  
  假设 require("math_utils")，require() 会依次尝试以下文件路径 (根据 package.path 中的路径模式)：
  - ./math_utils.lua
  - ./math_utils.lc (Lua 字节码文件)
  - /usr/local/share/lua/5.4/math_utils.lua
  - /usr/local/share/lua/5.4/math_utils/init.lua (如果模块是目录形式的包，后面会介绍)
  - ... (其他路径模式)
- 找到文件后: 如果找到匹配的文件，require() 会加载并执行该文件。
加载和执行模块代码: require() 会使用 loadfile() 或 load() 函数加载模块文件中的 Lua 代码，并执行这些代码。
缓存模块: 模块代码执行完成后，require() 会将模块返回的值（return 语句返回的表）缓存到 package.loaded 表中，键为模块名，值为模块对象。
返回模块对象: require() 函数最终返回缓存或新加载的模块对象。

修改 package.path：

你可以通过修改 package.path 变量来添加自定义的模块搜索路径。


-- 添加当前目录下的 "mylibs" 目录到 package.path
package.path = package.path .. ";./mylibs/?.lua"
local my_module = require("my_module") -- require 会在 ./mylibs 目录下查找 my_module.lua

最佳实践： 通常情况下，推荐将模块文件放在项目目录下的子目录中，并根据需要修改 package.path 或使用包 (Packages) 来组织模块。

1.5 模块的命名和组织

模块文件名: 模块文件名通常与模块名相同，并以 .lua 扩展名结尾，例如 math_utils.lua。
模块命名: 模块名应该具有描述性，能够清晰地表达模块的功能，例如 string_utils、file_utils、http_client 等。
模块组织: 对于大型项目，可以将模块按照功能划分为不同的子目录，形成包 (Packages)，提高代码的组织性和可维护性。

2. 包 (Packages)

2.1 包的概念与意义

包 (Package) 是一个包含多个模块的目录。 包提供了一种更高级的代码组织方式，可以将相关的模块组织在一起，形成一个逻辑上的整体。

包的主要意义在于：

更好地组织模块: 将相关的模块分组到同一个目录下，形成更清晰的目录结构，方便管理和维护。
避免命名冲突: 即使不同包中存在同名的模块，由于它们位于不同的包目录下，依然可以区分开来，避免命名冲突。
命名空间层级: 包引入了命名空间层级的概念，例如 my_package.module_a 和 my_package.module_b，使得模块的命名更加规范和清晰。

2.2 创建包

创建一个包非常简单，只需要创建一个目录，并将相关的模块文件放在该目录下即可。

示例：创建一个名为 my_package 的包

创建目录 my_package
在 my_package 目录下创建模块文件，例如：
- my_package/module_a.lua
- my_package/module_b.lua

my_package/module_a.lua 内容示例：


-- my_package/module_a.lua
local M = {}
function M.hello_a()
    print("Hello from module_a in my_package")
end
return M

my_package/module_b.lua 内容示例：


-- my_package/module_b.lua
local M = {}
function M.hello_b()
    print("Hello from module_b in my_package")
end
return M

2.3 加载包中的模块

要加载包中的模块，需要使用 点号 . 来分隔包名和模块名。require() 函数会自动处理包的路径。

示例：在 main.lua 中加载 my_package 包中的模块


-- main.lua
local module_a = require("my_package.module_a") -- 加载 my_package.module_a 模块
local module_b = require("my_package.module_b") -- 加载 my_package.module_b 模块
module_a.hello_a()
module_b.hello_b()

require("my_package.module_a") 的工作原理：

当 require() 遇到带有 点号 . 的模块名时，会将点号转换为路径分隔符（在大多数系统中是 /），并根据 package.path 查找模块文件。

例如，对于 require("my_package.module_a")，require() 会查找以下文件路径 (根据 package.path 中的路径模式)：

./my_package/module_a.lua
./my_package/module_a.lc
./my_package/module_a/init.lua (如果存在 init.lua 文件，则加载 init.lua 作为模块)
... (其他路径模式，点号会被替换为路径分隔符)

init.lua 文件 (可选)

在一个包目录下，可以创建一个名为 init.lua 的文件。当 require() 加载包名时，如果找到了包目录，并且目录下存在 init.lua 文件，则 require() 会加载并执行 init.lua 文件，并将 init.lua 返回的值作为包模块对象。

示例：在 my_package 包中添加 init.lua


-- my_package/init.lua
local M = {}
M.package_name = "my_package"
function M.package_info()
    print("This is package: " .. M.package_name)
end
return M

main.lua 中加载包本身：


-- main.lua
local my_package = require("my_package") -- 加载 my_package 包 (实际上加载的是 init.lua)
my_package.package_info()
print(my_package.package_name)

总结：

包通过目录结构来组织模块，使用点号 . 来表示包的层级关系。
require("包名.模块名") 可以加载包中的特定模块。
包目录下可选的 init.lua 文件可以作为包的入口模块，当 require("包名") 时加载。

2.4 包的组织和命名空间

包的组织结构: 包可以嵌套，形成更深层次的目录结构，例如 my_company/my_project/utils。
命名空间管理: 包有效地管理了模块的命名空间，避免了全局命名冲突。即使不同公司或项目存在同名的模块，只要它们位于不同的包目录下，就可以通过不同的包名前缀来区分。例如 company_a.utils.string_utils 和 company_b.utils.string_utils 可以共存。
清晰的模块路径: 使用包后，模块的路径更加清晰，易于理解模块之间的关系和依赖。

3. 模块和包的最佳实践

清晰的模块划分: 根据功能和职责，合理地划分模块，保持模块的单一职责原则，提高代码的可重用性和可维护性。
模块命名规范: 使用具有描述性的模块名，遵循一致的命名规范，例如使用下划线分隔单词 (string_utils) 或驼峰命名法 (StringUtils)。
导出必要的接口: 只导出模块需要对外提供的函数和变量，将内部实现细节隐藏起来，实现封装性。
避免全局变量: 尽量避免在模块中使用全局变量，使用 local 关键字声明模块内部的变量和函数，防止污染全局命名空间。
使用包组织模块: 对于大型项目，使用包来组织模块，形成清晰的目录结构，提高代码的可管理性。
良好的文档: 为模块和包编写清晰的文档，说明模块的功能、接口和使用方法，方便其他开发者使用。
版本控制: 对于发布的模块和包，应该进行版本控制，方便管理和维护不同版本的模块。

4. 总结

Lua 的模块和包机制是构建可维护、可扩展的 Lua 代码库的关键。通过合理地使用模块和包，我们可以有效地组织代码，提高代码的重用性、可读性和可维护性，并避免命名冲突。

核心要点回顾：

模块 (Module): 封装一组相关代码的独立文件，通常使用 return 表的方式导出接口。
require() 函数: 加载和执行模块，具有缓存机制，通过 package.path 查找模块文件。
包 (Package): 包含多个模块的目录，通过目录结构组织模块，使用点号 . 分隔包名和模块名。
package.path: 模块查找路径，可以自定义添加路径。
init.lua: 包目录下可选的入口模块文件，require("包名") 时加载。
最佳实践: 清晰划分模块，规范命名，导出必要接口，避免全局变量，使用包组织模块，编写文档。

掌握 Lua 的模块和包机制，将使你能够更好地组织和管理 Lua 代码，构建更复杂、更健壮的 Lua 应用程序。希望本文的详细讲解和代码实践示例能够帮助你深入理解和应用 Lua 模块和包。

作者与出处

原作者：灏天文库

来源：灏天文库

原文： https://aiknowledge.cn/collection/159-lua%E8%84%9A%E6%9C%AC%E8%AF%AD%E8%A8%80%E7%BC%96%E7%A8%8B%E5%85%A5%E9%97%A8%E6%95%99%E7%A8%8B

整理：灏天文库整理

由灏天文库平台收录，内容或由平台用户上传，仅供学习交流

8. 模块与包 (Modules and Packages)

文档摘要