前两篇已经用到了
Option、Result和match。它们背后有一组基础能力:用枚举定义“值可能是哪一种情况”,再用模式匹配处理每一种情况。本篇回到走读笔记提到的模块图节点,围绕issuer只讲两个知识点:enum怎样把状态与数据放在一起,match怎样在编译时检查分支是否遗漏。
一、源码入口:模块来源为什么有三种状态
module_graph/module.rs 中,ModuleGraphModule 有一个字段:
issuer: ModuleIssuer,
new 创建节点时将它设为 ModuleIssuer::Unset。对应类型定义在 normal_module.rs:
#[cacheable]
#[derive(Debug, Clone)]
pub enum ModuleIssuer {
Unset,
None,
Some(ModuleIdentifier),
}
本篇先不展开这些属性宏,只读枚举本身:
| 变体 | 携带的数据 | 在这里表达的区别 |
|---|---|---|
ModuleIssuer::Unset | 无 | 来源尚未设置 |
ModuleIssuer::None | 无 | 已确定没有来源模块 |
ModuleIssuer::Some(id) | 一个 ModuleIdentifier | 已确定来源模块标识符 |
“还没设置”和“已经确认没有”不是同一个事实。模块图需要保留这个区别;一个简单的 Option<ModuleIdentifier> 只能直接表达有或没有,无法同时区分这三种情况。
二、知识点一:enum 定义的是互斥的可能情况
1. 定义类型与构造值
把源码里的模块标识符暂时简化成字符串,可以定义下面这个教学模型:
enum Issuer {
Unset,
None,
Some(String),
}
Issuer 是类型名称,花括号里列出三个变体。一个 Issuer 值在某个时刻只属于其中一种情况。构造方式是:
let pending: Issuer = Issuer::Unset;
let entry: Issuer = Issuer::None;
let child: Issuer = Issuer::Some(String::from("entry.js"));
Issuer::Some(...) 中的括号用于传入这个变体携带的数据,定义要求它是 String。传整数不能通过类型检查;无数据的 Issuer::Unset 则不需要括号。
这和“给状态分配几个数字”的枚举不同:变体可以携带不同形态的数据,而整个值仍是同一个 Issuer 类型。想取出字符串时,必须先确认值处于 Some 变体,不能直接把所有 Issuer 当成字符串使用。
2. 为什么要把状态和数据放在一起
如果用两个独立字段表示同一件事:
struct LooseIssuer {
initialized: bool,
identifier: Option<String>,
}
就可能构造出 initialized: false、identifier: Some(...) 的组合。按照“未初始化时还没有确定来源”的业务约定,这个组合不应该存在,但类型本身允许它。
Issuer 只列出三种允许的情况,让“已知来源必须同时带着一个标识符”直接成为类型结构。这样能减少调用方反复维护多个字段之间约定的负担。
适用边界也很清楚:多个状态如果确实互斥,并且状态决定需要携带什么数据,枚举很合适。如果两个布尔条件本来就彼此独立,不需要为了使用枚举而强行合并。
枚举约束的是值的形态,并不自动限制状态转换。Rspack 的 set_issuer_if_unset 另外规定:只有当前为 Unset 才更新;源码也提供了直接赋值的 set_issuer。不能因为用了枚举,就认为编译器已经保证“来源设置一次后永远不能改变”。
3. 自定义 Some 与标准库 Some 怎样区分
Rspack 的转换方法是:
pub fn from_identifier(identifier: Option<ModuleIdentifier>) -> Self {
match identifier {
Some(id) => Self::Some(id),
None => Self::None,
}
}
左侧匹配的 Some、None 属于输入类型 Option<ModuleIdentifier>。右侧 Self 在这个 impl ModuleIssuer 中指 ModuleIssuer,所以 Self::Some、Self::None 是自定义枚举的变体。
它们名字一样,类型却不同。可以把两行的含义展开为:
Option::Some(id) → ModuleIssuer::Some(id)
Option::None → ModuleIssuer::None
这个方法表示来源信息已经给出,因此不会生成 Unset。定义三态和从二态输入转换是两层不同的工作。
三、知识点二:match 检查状态,同时提取数据
1. 从分支语法读到返回值
先看一个针对教学模型的函数:
fn describe(issuer: &Issuer) -> String {
match issuer {
Issuer::Unset => String::from("来源尚未设置"),
Issuer::None => String::from("已确定没有来源模块"),
Issuer::Some(id) => format!("来源模块:{id}"),
}
}
match issuer 表示检查这个值。每个分支按“模式 => 要执行的表达式”书写:
Issuer::Unset只匹配未设置状态。Issuer::None只匹配明确无来源的状态。Issuer::Some(id)匹配有来源的状态,并把内部数据绑定到名称id。
模式中的 id 是新绑定的局部变量,不是事先准备好、等待比较的变量。这个分支只在相应变体上成立,因此使用内部字符串是安全的。
match 本身也是表达式。这里三个分支都产生 String,整个 match 得到一个 String;没有结尾分号,它成为 describe 的返回值。不能让其中一个正常返回的分支产生整数,其他分支产生字符串,再期望 Rust 自动把它们装进一个任意类型的返回值里。
2. 匹配引用时,内部数据也可以借用
注意参数是 &Issuer,而不是 Issuer。对于这个引用输入,Rust 的匹配规则让 Issuer::Some(id) 中的 id 绑定为 &String,不会把原来的 String 移走。
所以可以借用同一个状态调用 describe 两次。这不是 match 自动克隆了字符串,而是整个检查过程中只借用了它。
对应的源码方法也这样使用借用:
pub fn identifier(&self) -> Option<&ModuleIdentifier> {
match self {
ModuleIssuer::Some(id) => Some(id),
_ => None,
}
}
Some(id) 返回对现有标识符的引用。调用方得到的是 Option<&ModuleIdentifier>,无需为一次查询复制或取得标识符的所有权。
3. 穷尽性:不能漏掉一个可能的状态
如果类型允许三种状态,match 就要覆盖三种。下面这个完整程序故意遗漏 Unset:
enum Issuer {
Unset,
None,
Some(String),
}
fn describe(issuer: &Issuer) -> &'static str {
match issuer {
Issuer::None => "无来源",
Issuer::Some(_) => "有来源",
}
}
fn main() {
println!("{}", describe(&Issuer::Unset));
}
使用 rustc +stable --edition=2021 编译,编译器拒绝这个程序,关键诊断为:
error[E0004]: non-exhaustive patterns: `&Issuer::Unset` not covered
即使某个调用点只打算传入已设置状态,函数参数仍允许所有 Issuer 值,编译器就要求完整处理。可以增加 Issuer::Unset 分支,也可以用通配模式覆盖剩余情况,但必须明确决定这种状态应该得到什么行为。
4. _ 很方便,但会合并状态差异
ModuleIssuer::identifier 用 _ => None 将 Unset 和 None 都转换成标准库的 Option::None。它回答的是“现在能否取得来源标识符”,不再保留“为什么没有”的区别。
这种写法适合不关心缺失原因的查询;如果处理逻辑需要区分三态,就应该逐项匹配。还有一个维护差异:以后给枚举添加新变体时,逐项匹配的代码会因为遗漏而编译失败,带 _ 的代码则可能继续编译,把新状态交给兜底分支。
同一个 _ 也出现在 Issuer::Some(_) 中:这里表示“确定是 Some,但忽略内部值”,并不表示覆盖所有枚举变体。要看清它所在的模式层级。
四、最小可运行示例:用三次输入观察状态差异
下面是完整的教学程序,与 Rspack 的区别是使用 String 代替 ModuleIdentifier,不依赖 Rspack 的 crate 或宏:
enum Issuer {
Unset,
None,
Some(String),
}
fn describe(issuer: &Issuer) -> String {
match issuer {
Issuer::Unset => String::from("来源尚未设置"),
Issuer::None => String::from("已确定没有来源模块"),
Issuer::Some(id) => format!("来源模块:{id}"),
}
}
fn main() {
let pending = Issuer::Unset;
let entry = Issuer::None;
let child = Issuer::Some(String::from("entry.js"));
println!("{}", describe(&pending));
println!("{}", describe(&entry));
println!("{}", describe(&child));
println!("再次读取:{}", describe(&child));
}
保存为 issuer.rs 后执行:
rustc +stable --edition=2021 issuer.rs -o issuer
./issuer
已在本次写作中使用 rustc 1.95.0 实际编译运行,输出为:
来源尚未设置
已确定没有来源模块
来源模块:entry.js
再次读取:来源模块:entry.js
输入是代码中构造的三种枚举值。最后一行再次读取 child,验证 describe(&child) 没有消耗原来的状态;第三个分支根据携带的字符串生成结果。
五、回到 Rspack:为什么业务处理不能只查 identifier
module_tracker.rs 的 finish_module 会完整匹配 mgm.issuer(),而不是只判断 identifier() 有没有值。
三条分支承担不同职责:
| 状态 | finish_module 中的处理 |
|---|---|
Unset | panic,报告不应访问尚未设置的来源状态 |
None | 按入口模块处理,从入边关联的 entry_finish_tasks 取出任务 |
Some(mid) | 查找来源模块的未完成计数,递减;归零时将其加入后续处理队列 |
这里如果只调用 identifier(),前两种状态都会得到 None,无法区分“构建状态不符合预期”和“这是一个没有来源模块的入口”。显式匹配三个变体,正是为了把这种业务差异保留下来。
源码中的 panic! 分支不会正常返回;其余分支主要更新任务和计数。因此这段业务匹配与前面返回 String 的示例用途不同,但共享同一套变体检查与数据绑定规则。
六、总结
enum 让互斥的状态和相应数据由一个类型表达;match 则让调用者在检查变体后使用数据,并通过穷尽性检查发现遗漏。
读 Rspack 时,可以先问“这个类型列出了哪些可能情况”,再问“当前函数需不需要区分所有情况”。ModuleIssuer::identifier 可以合并无标识符的状态,finish_module 则必须保留区别;它们并不矛盾,而是在回答不同的问题。