模块系统
导入形态、公开面、内置命名空间、标准库组织——CN 的代码组织单位。
导入形态
主.cnCN
导入 数学::平方根;
导入 数学::双倍;
函数 主() -> 整32 {
浮64 根 = 数学::平方根(4.0);
整32 倍 = 数学::双倍(21);
打印(根);
打印行(倍);
返回 0;
}输出:4.000000 42
主.cnCN
导入 文件::打开文件;
导入 文件::关闭文件;
函数 主() -> 整32 {
结果<空类型*, 整32> 打开 = 打开文件("target/e2e_122_不存在的文件.cn", 1);
如果 (打开.正常) {
关闭文件(打开.值);
返回 1;
}
打印("文件模块独立导入编译运行通过");
返回 0;
}输出:文件模块独立导入编译运行通过
导入 模块::符号后纯名直用(公开符号合并机制);多符号导入 模块::{a, b, c},项内可重命名导入 模块::{a 作为 b};模块级别名导入 路径 作为 别名(绑定模块路径本身,供别名::符号限定访问)。- 通配
导入 路径::*:把模块的公开 API 批量引入纯名(引入层级=最低级,见「内置命名空间」的冲突矩阵——本模块显式定义或显式导入同名项可合法遮蔽它,通配×通配同名=使用点歧义错误)。整模块导入导入 模块;同属此层。 - 再导出
公开 导入 网络::连接:与普通导入同语法,加公开前缀=把该符号继续对外导出,调用方导入包根路径即直达(见下例与「包与 crate」)——库 crate 的包.cn 用「模块聚合 + 公开 导入」组装公开 API 面。 - 限定名直调形态始终可用:
数学::平方根(2.0)(无需导入)。 - 顶层
模块 名;只在包根成员聚合/父模块挂子模块两种位置合法(见下节「模块声明与加载」);文件顶层公开:标签控制导出面(v2.0 默认私有、显式公开:导出)。
再导出断面(库 crate 包根聚合·E2E 370 实测)CN
// —— 图形库/包.cn(库 crate 根:模块聚合 + 公开 导入 再导出)——
模块 图形库;
公开 导入 图形库::绘制; // 再导出:绘制 成为包根公开 API
// —— 图形库/图形库.cn(crate 内部模块)——
公开:
函数 绘制() -> 整32 {
返回 7;
}
// —— 主.cn(消费方:导入包根路径即可用再导出符号,无关内部布局)——
导入 图形库::绘制;
函数 主() -> 整32 {
打印("绘制: ", 绘制()); // 7
返回 0;
}模块声明与加载
模块路径由文件名 + 目录层级唯一决定;模块 声明只出现在两个树结构位置,声明 = 自动加载(Rust mod 对齐)。
- 定位收紧:①包根成员聚合(
包.cn内模块 网络;,声明包的组成、不引入名字);②父模块挂子模块(网络.cn内模块 传输控制;,建立网络::传输控制完整路径)。普通源文件使用模块声明=编译诊断「模块声明 'X' 非当前模块 'Y' 的子模块(模块 声明仅限 包根成员聚合/父模块挂子模块)」。 - 自动加载强语义:被
模块声明引用的模块文件恒被加载编译——哪怕无人导入它,其内错误也在自身编译期暴露(fail fast,库完整性保证);触发源 = 声明本身,非目录扫描(未声明的同目录杂散文件不参与编译,封闭树)。 - 循环导入拒绝:模块导入图出现环(直接互引或经中间模块的间接互引)=编译错误——诊断「模块循环依赖」并打印环路径(如 循环乙 → 循环甲 → 循环乙);加载按依赖拓扑序(被依赖者先编译),不设豁免通道。
定位收紧断面(声明仅限两位置)CN
// —— 网络库.cn(普通依赖文件:非包根、非父模块)——
模块 兄弟件; // ✗ 编译诊断:兄弟件.cn 是同目录文件而非 网络库/ 子目录成员
// 挂载只允许「父挂子」(网络库/兄弟件.cn)
// —— 合法位置①:父模块挂子模块 ——
// 网络.cn 内写:模块 传输控制; → 建立 网络::传输控制(网络/传输控制.cn)
// —— 合法位置②:包根成员聚合(包.cn 内)——
// 模块 图形库; → 声明包的组成(不引入名字)自动加载强语义断面CN
// —— 主.cn ——
模块 工具件; // 声明即自动加载(哪怕无人导入)
函数 主() -> 整32 {
返回 0;
}
// —— 工具件.cn(被声明自动加载的子模块)——
公开:
函数 坏函数() -> 整32 {
返回 未声明名; // 其错误必暴露:编译失败 rc=1(对照:删声明即不加载)
}可见性交集(取最严)
符号最终可见性 = 各层级可见性的交集(取最严格)——模块级私有一票否决类内 公开:。
| 类层级 | 成员层级 | 同文件 | 同包跨文件 | 跨包 |
|---|---|---|---|---|
| 模块公开 | 类内公开 | 可 | 可 | 可 |
| 模块公开 | 类内私有 | 可 | 不可 | 不可 |
| 模块私有 | 类内公开 | 可 | 不可 | 不可 |
| 模块私有 | 类内私有 | 可 | 不可 | 不可 |
- 模块公开 × 类内私有:类可跨模块实例化,但私有方法跨文件调用拒(诊断「私有成员」)。
- 模块私有 × 类内公开:整个类跨文件不可见(「未声明的标识符」)——模块私有一票否决,类内
公开:不突破模块边界。 - 文件顶层
公开:标签显式放行导出;无标签=默认私有(v2.0)。
内置命名空间与名称解析
运行时内置按域分组(IO:: 数学:: 文件:: 时间:: 系统:: 线程:: 解析:: 内存:: 字符串构建器::);标准库模块把它们包装成结果 风格公开函数。纯名引用按作用域链唯一绑定——冲突绝不静默。
| 优先级 | 名字来源 | 说明 |
|---|---|---|
| 1 | 本地作用域 | 局部变量/参数(遮蔽一切同名) |
| 2 | 本模块显式项 | 本文件顶层定义(函数/结构体/常量/静态) |
| 3 | 显式导入 | 导入 m::符号 / 导入 m::{a, b} / 导入 m::符号 作为 别名(具名绑定) |
| 4 | 通配引入 | 导入 m;(模块整体导入=公开 API 批量引入) / 导入 m::* |
| 5 | 内置函数/构造器 | 打印/字符串长度/分配…与 正常/错误/某些/转移/复制 等 |
- 冲突判定矩阵(同为纯名):本模块项 × 显式导入同名=编译错误「导入与本地定义同名(E0255)」(改名或删其一);显式导入 × 显式导入同名=「多次显式导入同名」;通配 × 通配同名=使用点歧义「符号歧义:来自 模块A/模块B(E0659)」(仅当该名字被实际引用时报);本模块项/显式导入 遮蔽 通配=合法(唯一允许的遮蔽)。
- 限定调用恒明确:
模块::符号(...)(含多级a::b::c)直接决议到指定模块的公开符号——不参与遮蔽、永无歧义、无须先导入;未导入的模块路径引用=「未声明的标识符」(核心包 prelude 内置例外)。 - 决议失败绝不静默:歧义/未命中一律编译诊断,禁止「先收集文件赢」式静默绑定(静默吞=错误绑定)。
三级解析实测(本模块项遮蔽通配)CN
// —— 工具库.cn ——
公开:
函数 版本() -> 整64 {
返回 200;
}
函数 双倍(整64 数值) -> 整64 {
返回 数值 * 10;
}
// —— 主.cn ——(只写整体导入=③ 通配层;不得再写 导入 工具库::版本)
导入 工具库;
函数 版本() -> 整64 {
返回 100;
}
函数 主() -> 整32 {
打印("主 版本(): ", 版本()); // 100(①遮蔽③)
打印("工具库::版本(): ", 工具库::版本()); // 200(限定调用恒明确)
打印("工具库 双倍(5): ", 双倍(5)); // 50(③glob 纯名直调)
返回 0;
}读取行()(返回 结果)与内置 IO::读取行()(返回裸串)以限定名区分。业务代码用 stdlib 包装版(显式错误处理),内置为底层。工程组织:货舱.toml
- 多文件工程由
货舱.toml声明模块依赖;编译器默认按入口文件同目录自动发现(--货舱 路径显式指定)。 - 标准库随编译器分发(
--stdlib 路径可指定);stdlib/*.cn本身就是「模块=文件」的活样板。 - 跨模块链接符号冲突(同名公开函数)在导入解析期诊断。
特性声明制([特性])
宏名的受控来源:[特性] 节声明启用名单,每个启用特性即一个条件编译旗标(与 -D 同通道)——声明制=宏名有单一事实来源(对齐 Cargo features)。
货舱.toml(片段)TOML
[货舱]
名称 = "特性示例包"
[特性]
启用 = ["网络", "压缩"]主.cnCN
函数 主() -> 整32 {
#如果定义(网络)
打印行("特性-网络: 命中");
#结束如果
#如果定义 压缩
打印行("特性-压缩: 命中");
#结束如果
#如果定义(图形)
打印行("特性-图形: 命中");
#结束如果
打印行("主程序运行");
返回 0;
}
// 注:本用例宿主-only(239-a 宿主 preprocessor 实装)——双编译对照面待 v2 [特性] 货舱通道轮上架(D12 主面=546·注入通道后置)。输出:特性-网络: 命中特性-压缩: 命中主程序运行
- 上例按本页默认构建(未启用任何特性)只剩「主程序运行」一行;同目录放入
[特性] 启用 = ["网络"]的 货舱.toml 后,同一源码输出「网络: 命中」「主程序运行」两行(-D 网络等效)。 启用 = []空数组合法(无旗标命中);值不是字符串数组=货舱.toml 解析错误拒绝。
包与 crate:多包工程
包(crate)= 一个 货舱.toml 描述的编译单元,也是命名空间边界——跨包同名符号互不冲突(链接符号带 包名$ 前缀)。包根 包.cn 聚合包内模块并再导出公共 API。
| 概念 | 形态 | 要点 |
|---|---|---|
| 包 / crate | 货舱.toml + 依赖/ 子目录 | 一个编译单元、一个命名空间边界;本地依赖放 依赖/包名/ |
| 包根 | 包.cn | 模块 包名; 聚合 + 公开 导入 再导出 |
| 跨包导入 | 导入 网络库::连接 | 包名作路径首段——消费方不感知包内文件划分 |
| 同名隔离 | 链接符号 包名$ 前缀 | 甲库::双倍 与 乙库::双倍 各自独立 |
| 核心包 prelude | 默认可见 | 打印/字符串 API/数学:: 限定名等基础项无需导入 |
包根与再导出:工程断面
实测断面:主程序经 货舱.toml 依赖本地包 图形库;包根 包.cn 再导出内部模块的 绘制——消费方只导入 图形库::绘制 即可用(输出 绘制: 7)。
货舱.toml(主程序)TOML
[货舱]
名称 = "主程序"
版本 = "0.1.0"
[依赖]
图形库 = "本地"
核心 = "内置"依赖/图形库/包.cn(包根)CN
// 图形库 crate 根:聚合模块 + 公开 导入 再导出
模块 图形库;
公开 导入 图形库::绘制;依赖/图形库/图形库.cn(包内模块)CN
// 图形库 模块(crate 内部模块)
公开:
函数 绘制() -> 整32 {
返回 7;
}主.cn(消费方)CN
导入 图形库::绘制;
函数 主() -> 整32 {
打印("绘制: ", 绘制());
返回 0;
}跨包同名:命名空间隔离
两个库包各自定义同名公开函数 双倍——符号加 包名$ 前缀隔离,互不冲突;消费方以「花括号 + 作为」重命名导入同时使用(实测输出 12 18)。
依赖/甲库/甲库.cn 与 依赖/乙库/乙库.cnCN
// —— 依赖/甲库/甲库.cn ——
公开:
函数 双倍(整32 x) -> 整32 {
返回 2 * x;
}
// —— 依赖/乙库/乙库.cn(同名·独立命名空间)——
公开:
函数 双倍(整32 x) -> 整32 {
返回 3 * x;
}主.cn(重命名导入双包)CN
导入 甲库::{双倍 作为 甲库双倍};
导入 乙库::{双倍 作为 乙库双倍};
函数 主() -> 整32 {
打印(甲库双倍(6), " ", 乙库双倍(6)); // 12 18
返回 0;
}核心包 prelude
核心包基础项默认可见(等价隐式 导入 核心::*)——以下程序无任何导入语句:
主.cnCN
函数 主() -> 整32 {
打印("===== 核心包 prelude(第 7 层)=====");
// ---- ① 打印(println):prelude 基础函数 ----
打印("prelude 打印 可用");
// ---- ② 格式化:%d/%f/%s 占位符 ----
字符串 格1 = 格式化("值%d 浮点%f", 42, 3.14);
打印("格式化: ", 格1); // 格式化: 值42 浮点3.140000
// ---- ③ 整数转字符串:字符串 API 族 ----
字符串 数字串 = 整数转字符串(42);
打印("整数转字符串: ", 数字串); // 整数转字符串: 42
// ---- ④ 数学::平方根:内置限定名 prelude(无需导入)----
浮64 根 = 数学::平方根(9.0);
打印("数学::平方根(9.0): ", 根); // 3.000000
// ---- ⑤ 字符串长度 / 字符串比较:字符串 API 族 ----
整64 长度 = 字符串长度("abcd");
打印("字符串长度: ", 长度); // 4
布尔 相等 = 字符串比较("ab", "ab");
打印("字符串比较相等: ", 相等); // 1(多参数直接传转 1/0)
// ---- ⑥ 布尔转字符串:拼接输出中文文本 ----
字符串 布尔串 = 布尔转字符串(相等);
打印("布尔转字符串: ", 布尔串); // 真
打印("===== 核心包 prelude 测试完成 =====");
返回 0;
}输出:===== 核心包 prelude(第 7 层)===== prelude 打印 可用 格式化: 值42 浮点3.140000 整数转字符串: 42 数学::平方根(9.0): 3.000000 字符串长度: 4 字符串比较相等: 真 布尔转字符串: 真 ===== 核心包 prelude 测试完成 =====
缺失依赖=编译拒绝
引用未声明的包(货舱.toml [依赖] 无此包)=编译期拒绝(诊断「未声明的标识符」),不会拖到链接期才暴露:
跨包缺失依赖.cn(负例·编译拒绝)CN
函数 主() -> 整32 {
整32 甲 = 幽灵包::取值();
返回 0;
}