通过 Rspack 源码学 Rust(六):用 enum 表达状态,用 match 完整处理分支

0 阅读8分钟

前两篇已经用到了 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 中的处理
Unsetpanic,报告不应访问尚未设置的来源状态
None按入口模块处理,从入边关联的 entry_finish_tasks 取出任务
Some(mid)查找来源模块的未完成计数,递减;归零时将其加入后续处理队列

这里如果只调用 identifier(),前两种状态都会得到 None,无法区分“构建状态不符合预期”和“这是一个没有来源模块的入口”。显式匹配三个变体,正是为了把这种业务差异保留下来。

源码中的 panic! 分支不会正常返回;其余分支主要更新任务和计数。因此这段业务匹配与前面返回 String 的示例用途不同,但共享同一套变体检查与数据绑定规则。

六、总结

enum 让互斥的状态和相应数据由一个类型表达;match 则让调用者在检查变体后使用数据,并通过穷尽性检查发现遗漏。

读 Rspack 时,可以先问“这个类型列出了哪些可能情况”,再问“当前函数需不需要区分所有情况”。ModuleIssuer::identifier 可以合并无标识符的状态,finish_module 则必须保留区别;它们并不矛盾,而是在回答不同的问题。