如何用Module组织Jai项目代码？The Way to Jai 模块系统完全指南

**Module（模块）**是 Jai 项目组织代码的核心机制。通过 The Way to Jai 这本书的官方示例，你只需掌握#import、#load和module_parameters三个要点，就能把项目代码拆分成结构清晰、易于维护的多个文件。本文将带你快速搞懂 Jai 模块系统，从入门到项目实战。

一、先搞懂：Jai 的 Module 是什么？

Module 是 Jai 提供可复用代码的基本单元，相当于其他语言的"标准库/库文件"。比如使用print函数，就需要导入 Basic 模块：

#import "Basic";

模块统一存放在 Jai 安装目录的modules文件夹中，全局共享。模块有两种形态：

• 单文件模块：一个.jai文件即可，例如 my_modules/Linked_List.jai，用#import "Linked_List";直接导入；
• 文件夹模块：一个与模块同名的文件夹，里面必须有入口文件module.jai，可包含多个源码文件。官方 Basic 模块就是这样组织的：module.jai通过一系列#load指令把Print.jai、String_Builder.jai等文件拼装起来。

💡 查找顺序：编译器找不到TestScope模块时，会先搜索同名的TestScope.jai文件，再搜索含module.jai的TestScope文件夹。

二、#load 与 #import：两大加载指令的区别

这是新手最容易混淆的地方，一句话总结：

来看官方示例 8.1_main.jai 的分文件组织方式：

#import "Basic"; #load "part1.jai"; #load "subfolder/part2.jai"; // 路径相对于当前文件 #load "part3.jai"; main :: () { print("a_part1 is: %", a_part1); // 直接访问 part1 里的全局变量 }

可以看到 part1.jai 中定义的全局变量a_part1可以被main()直接访问——这正是#load的威力：代码按功能拆分到不同文件，main.jai只作为"总览"文件，还可以层层嵌套继续拆分。

三、命名导入：优雅解决名称冲突

当两个模块定义了同名函数时（比如 Lib1 和 Lib2 都有proc1），命名导入（Named Import）可以精准区分来源：

Lib1 :: #import "Lib1"; Lib2 :: #import "Lib2"; a := Lib1.proc1(); b := Lib2.proc1();

给导入起别名后，就像为函数加上了"命名空间"，代码可读性更强。如果名字不冲突，还可以配合using指令继续直接使用短名称：

using,except(proc1) Lib1; // 排除冲突的 proc1，其余直接用

四、-import_dir：管理你自己写的模块

全局modules文件夹里的模块在 Jai 升级时可能被删除，所以自己写的模块应放在独立目录，通过编译参数-import_dir告诉编译器去哪里找：

jai 8.2_main.jai -import_dir "./my_modules"

本书仓库就提供了现成的自定义模块示范，位于my_modules/目录，例如参数化模块 my_modules/TestModule_Params/module.jai 和构建模块 my_modules/Build/module.jai，可以作为你创建第一个模块的参考模板。

五、推荐的项目文件夹结构

中小规模 Jai 项目通用的目录布局如下：

project_name run/ data/ # 字体、图片、音频等数据文件 project_name.exe src/ main.jai # 唯一入口，含 main() 过程 其他 .jai 文件 build.jai # 用 Jai 描述编译过程

约定俗成的源码组织习惯（详见 book/08A_Modules_-_Structuring_the_code_of_a_project.md）：

1. 文件顶部先写#import，再写#load，多时可按字母排序；
2. 接着是全局常量、变量、类型声明；
3. 然后是各功能过程代码；
4. main()过程永远放在文件最底部，方便快速定位程序入口。

六、进阶：用模块参数控制模块行为

Jai 的#module_parameters允许模块暴露可配置开关。Basic 模块用它定义ENABLE_ASSERT等参数，导入时可以改写：

#import "Basic"()(ENABLE_ASSERT=false); // 生产环境关闭断言

官方示例 examples/08/8.2_main.jai 演示了完整用法：模块内部定义VERBOSE := false参数，导入时传入(VERBOSE=true)即可切换模块行为。

七、总结：Module 系统的核心价值 ✅

• #import导入封闭作用域的模块，代码复用更安全；
• #load共享全局作用域，适合把大项目拆成小文件；
• -import_dir让项目自有模块目录化、不随 Jai 升级丢失；
• 命名导入与模块参数分别是解决冲突和定制行为的利器。

按这套模式组织代码，你的 Jai 项目会像官方 Basic 模块一样——入口清晰、职责分明、随规模平滑扩展。🚀