Comprehensive Rust 课程精讲：用 Enum 密封（Sealing）API —— 以类型列表锁定多态边界

在 OOP 语言中，"子类集合"天然是多态的：任何继承自基类的类型都能被当作基类使用，而这种开放性往往让 API 的合法输入集合变得模糊。Rust 不提供继承，但它提供了另一种收拢多态边界的手段——枚举（enum）。本文基于 Google Android 团队维护的开源 Rust 课程 Comprehensive Rust 中"Sealing with Enums"一课，讲解如何用代数数据类型（ADT）将一个 API 允许的输入类型"封闭"在一个枚举里，让调用方一眼看清合法输入、让编译器替你穷尽检查每一种情况。读完本文，你将掌握"以具体类型列表而非开放 trait 集合"来设计多态 API 的方法，并能结合枚举的不变量（invariant）设计出既安全又易于使用的接口。

本课在课程体系中的位置

本节属于课程中 Idiomatic Rust → Polymorphism → From OOP to Rust 章节。该章节的核心命题是：如何从 Java、C++ 等语言的"基于继承的多态"迁移到 Rust 基于 trait 的多态。课程先用 Inheritance in OOP languages 回顾继承机制，再用 Why no Inheritance in Rust? 说明 Rust 拒绝继承的原因（异构默认、数据真相多源、默认动态分派带来的 vtable 开销），接着讨论 Composition over Inheritance 与 Traits for Polymorphism users can extend、Sealed traits 等多态方案，最后落到本文主角——用枚举实现"不可被下游扩展"的封闭多态。

在动手前，课程 Problem solving: Break Down the Problem 给出了一个非常实用的决策指引：先判断问题是"需要一组特定类型"还是"关心类型的抽象行为"——前者用枚举往往是最干净的方案，后者才值得考虑 trait。本文正是"枚举路线"的深入示范。

核心示例：GetSource 数据源枚举

课程原文给出了一个可直接编辑运行的最小示例，其核心是一个表达"数据来源"的枚举：

use std::collections::BTreeMap;

pub enum GetSource {
    WebUrl(String),
    BytesMap(BTreeMap<String, Vec<u8>>),
}

impl GetSource {
    fn get(&self, url: &str) -> Option<&Vec<u8>> {
        match self {
            Self::WebUrl(source) => unimplemented!(),
            Self::BytesMap(map) => map.get(url),
        }
    }
}

逐行拆解这个例子：

• GetSource 是一个公开枚举，只有两个变体：
  • WebUrl(String)：带元组负载的变体，表示"从 URL 获取"这一数据来源，负载是 String 类型的 URL 字符串；
  • BytesMap(BTreeMap<String, Vec<u8>>)：负载是 BTreeMap<String, Vec<u8>>，即"URL → 字节内容"的映射表，用于提供本地缓存的二进制数据。
• impl GetSource 块为枚举实现了方法 get(&self, url: &str) -> Option<&Vec<u8>>，返回给定 URL 对应的字节内容。
• 方法体用 match self 穷尽两个变体：WebUrl 分支以 unimplemented!() 占位（示意真正实现需要发起网络请求），BytesMap 分支直接委托 map.get(url)。

两个值得注意的实现细节

1. 为何选择 BTreeMap 而非 HashMap？ 这不是随意的选择。与 HashMap 相比，BTreeMap 的 key 有确定的总序（Ord），迭代顺序稳定，在数据量不大时查找性能也足够好。对课程示例而言，使用 BTreeMap 让"字节映射"这一变体天然具备可确定性（deterministic）遍历顺序，这在打印调试、测试断言场景下更友好。

2. 为什么 get 不直接对 url 做匹配？ 注意 match self 匹配的是枚举值本身而非参数，这是枚举多态的关键形态：行为的分派发生在"我是哪种变体"上，而不是参数的运行时类型上。编译器会检查 match 是否穷尽了所有变体，漏掉任何一个都会编译失败。

关于枚举是"一个类型下收集一组值"这一点，课程更早的 Enums 一课有基础讲解：每个变体可以有不同类型的负载，Rust 会在值中存储判别值（discriminant）以在运行时区分当前是哪个变体，并利用 niche 优化用最小的空间编码判别值（例如 Option<&u8> 中 None 直接用空指针表示，size_of::<Option<T>>() 与 size_of::<T>() 相等）。这些基础决定了枚举方案的内存表现：当变体数量有限、负载类型已知时，枚举的布局是紧凑且确定的。

动机：何时应该用枚举"密封" API

课程在讲解笔记（<details> 块）中明确给出了本课的核心动机：

Motivation: API is designed around a specific list of types that are valid for it, users of the API are not expected to extend it.

翻译过来就是两条判定标准：

1. API 围绕一组"特定的、明确列举的"合法类型设计——也就是这个 API 的世界观里只存在这几种输入；
2. API 的调用方不被期望（也不需要）扩展这组类型——开放扩展反而有害。

满足这两条时，枚举是最自然的表达方式：你把自己支持的每一种输入类型写成一个变体，API 的"合法输入集合"就从隐式的文档约定变成了编译器可验证的类型事实。

这与同章节的 Sealed traits 形成对照：sealed trait 用"私有 supertrait 模块"阻止下游实现 trait，但其动机通常是"trait 目前对下游实现不稳定"或"领域高风险（如密码学）"；而枚举方案的动机更朴素——根本没有"更多类型"可言。两者的取舍在后续小节详述。

为什么在 Rust 中这"足够"多态？

课程强调了一个常被 OOP 背景开发者低估的事实：

Enums in Rust are algebraic data types, we can define different structures for each variant. For some domains, this might be enough polymorphism for the problem.

Rust 的枚举是代数数据类型（ADT）：每个变体可以携带完全不同的结构——元组负载（如 WebUrl(String)）、结构体负载、甚至嵌套其他枚举。这意味着你完全可以在一个枚举内"拼装"出形态各异的数据结构，而不需要让它们共享某个公共基类。

"为每个变体定义不同结构"的能力，让枚举在不少领域（例如协议的输入格式、命令分派、状态机、解析器的 AST 节点）提供了足够的多样性，足以满足该问题的全部多态需求。课程的建议是务实而实验性的：

Experiment and see what works, what solutions seem to make more sense.

——先尝试，看看哪种方案更贴合你的问题，而不是条件反射式地引入 trait 或动态分派。

枚举方案的直接收益：输入类型一目了然

课程用两条并列的要点总结了枚举方案的 API 设计价值：

By having the user-facing part of the API refer to an enum, users know what types are valid inputs and can construct those types using the available methods to do so.

收益一：合法输入集合对调用方完全透明。 当面向用户的部分（函数签名、字段类型）引用的是 GetSource 这样的枚举时，调用方不需要阅读文档来猜测"这个函数接受哪些类型"——答案就写在类型里。IDE 的自动补全会列出全部变体，编译器会拒绝任何不在枚举中的类型。

这与"接受一个 trait 对象或泛型参数"的 API 形成对比：trait 方案告诉调用方"实现某 trait 的任何类型都可以"，但合法集合是开放的、需要调用方自行探索的。

变体构造方式决定 API 安全性：不变量（Invariant）视角

这是本课最有深度的部分。课程指出，枚举中承载的类型的构造方式直接决定了 API 能否保证安全：

情况一：变体类型只能通过"维护不变量"的构造器创建

If the types that make up the enum have invariants that the API internally upholds, and the only way users can construct those types is through constructors that build and maintain those invariants, then you can be sure that inputs to a generic method uphold their invariants.

设想一个场景：你的 API 内部对 BytesMap 变体中的映射有隐含要求——例如"每个 value 必须是合法的 UTF-8 文本"或"key 必须是小写规范化后的 URL"。如果：

• 这些不变量由 API 内部维护；
• 调用方只能通过你提供的构造器（例如 GetSource::from_bytes(...)，内部完成规范化）来创建 BytesMap 变体；

那么，任何进入通用方法（如 get）的输入都必然满足这些不变量。你可以省略输入校验，把校验成本从"每次调用都检查"降低为"构造时检查一次"，代码更简洁且不可能出现不变量被破坏的输入。这其实就是"parse, don't validate"（解析而非校验）思想在类型设计层面的体现。

情况二：变体类型可由用户自由构造

If the types that make up the enum instead are types the user can freely construct, then sanitisation and interpretation may need to be taken into consideration.

反过来，如果变体里的类型是 String、Vec<u8> 这类用户随手就能构造的公共类型（正如示例中的 WebUrl(String) 和 BytesMap(BTreeMap<...>)），那么 API 就不能假设输入满足任何额外约束。此时必须把**清洗（sanitisation）与解释（interpretation）**纳入设计：

• 清洗：对输入做校验与规范化，例如把 " https://example.com " 两端去空格、把相对路径解析为绝对 URL、拒绝非法的 scheme 等；
• 解释：明确每个字段的业务语义，例如 String 里到底是"编码后的 URL"还是"人类可读的地址"。

这直接呼应了本课开头 WebUrl 分支 unimplemented!() 的留白：真实实现里，从 URL 拉取数据前必须处理 URL 的合法性、重定向、超时等"解释与清洗"问题。课程提醒：公开类型负载（public types as payloads）会把不变量维护的责任推给实现者，这也是后续"是否需要为变体类型建立私有包装类型"这一设计决策的由来。

拓展：与 Sealed Trait 对比 —— 何时用枚举、何时用 sealed trait

本节在课程体系中与 Sealed traits for Polymorphism users cannot extend 直接相邻，课程在 sealed trait 一课的笔记中反过来列出了"为什么不用枚举"，正好构成一组互文对比。整理如下：

维度	用枚举密封	用 sealed trait 密封
表达内容	"API 就支持这些类型"	"API 支持实现某行为的所有类型（但仅限本 crate 实现的）"
实现细节暴露	暴露：变体列表就是实现清单，调用方知道内部有哪几种类型	隐藏：trait 背后可以任意扩展实现类型
调用方式	用户必须通过枚举变体构造器使用 API	用户针对具体类型实现 trait，编译器按类型做单态化（monomorphization）
演进代价	枚举新增变体是 breaking change，调用方所有 match 都要更新	trait 新增方法同样是 breaking change，但类型集合的增删对调用方透明
分派方式	运行时 match 分支（在枚举值上）	编译期单态化，为每个类型生成专用函数，无 vtable 查找

Sealed trait 课的笔记中明确列出枚举方案的四个局限，恰好反衬出本文示例的取舍：

1. 枚举暴露实现细节——"这个 API 就是为这几种类型工作的"；
2. 用户必须使用变体构造器才能使用 API；
3. 枚举是公开类型，用户会在自己的代码里引用它，一旦枚举变更（增删变体），用户的代码必须跟着改（非穷尽 match 直接编译失败）；
4. 枚举需要运行时分支，而 sealed trait 让编译器为每个具体类型单态化出专用函数，无分支、无间接调用。

而本文示例的 GetSource 恰好展示了枚举方案的适用前提：数据来源就两种、且 API 作者不打算频繁演进变体集合。当变体集合稳定、类型数量少时，枚举的"穷尽匹配 + 类型即文档"优势远远盖过其演进代价。

拓展：枚举负载中的组合思想

回顾同章节的 Composition over Inheritance：Rust 用"字段组合"替代继承。本文示例把这一思想延伸到了枚举内部——BytesMap(BTreeMap<String, Vec<u8>>) 这个变体本身就是组合的产物：BTreeMap、String、Vec<u8> 都是标准库的既有类型，通过组合它们，你得到了一个"URL → 字节内容"的新语义类型，而无须定义任何继承层级。这也是 Inheritance from Rust's Perspective 一课强调的：类型是"具体数据 + 关联行为"，trait 是"必须由类型实现的抽象行为"，两者界限清晰，而枚举正位于两者之间的灰色地带——它是一组具体类型的分派器，行为（get）集中实现在 impl 块里。

实战演练：把它改造成可编译、可测试的完整示例

为了让读者能真正跑起来，下面给出一个基于课程示例的完整实现：补齐 WebUrl 分支（用课程早期介绍的 std 集合类型 思路模拟一个内存 URL 缓存）、添加测试并演示错误处理。它可以直接放入仓库中的课程练习模板（例如任意一个带 Cargo.toml 的练习目录）运行：

use std::collections::BTreeMap;

pub enum GetSource {
    WebUrl(String),
    BytesMap(BTreeMap<String, Vec<u8>>),
}

impl GetSource {
    /// 从数据源中取出 url 对应的字节内容。
    ///
    /// 注意：当变体是用户可自由构造的公共类型（String / BTreeMap）时，
    /// 清洗与解释必须由实现者承担——这里的 WebUrl 分支仅做占位。
    fn get(&self, url: &str) -> Option<&[u8]> {
        match self {
            Self::WebUrl(_source) => {
                // 真实实现：发起 HTTP 请求、处理重定向与超时。
                // 此处用标准库语法占位（本示例不可达分支），演示 match 穷尽性。
                unimplemented!("network fetch not implemented in this example")
            }
            Self::BytesMap(map) => map.get(url).map(|v| v.as_slice()),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn bytes_map_lookup_works() {
        let mut map = BTreeMap::new();
        map.insert("/index.html".to_string(), b"<h1>hi</h1>".to_vec());

        let source = GetSource::BytesMap(map);
        assert_eq!(source.get("/index.html"), Some(&b"<h1>hi</h1>"[..]));
        assert_eq!(source.get("/missing"), None);
    }
}

测试验证了课程强调的要点：BytesMap 变体走 map.get(url)，命中返回 Some(&[u8])，未命中返回 None；而 WebUrl 分支的存在保证了 match 的穷尽性——即使现在不实现它，编译器也会要求你处理这个变体。

如果想进一步体验"枚举密封"的工程价值，可以尝试以下三个方向的改造（均可在本地练习目录中自行完成，无需修改仓库）：

1. 新增变体：例如 LocalFile(std::path::PathBuf)，然后观察编译器如何"逼"你更新 get 的 match——这正是枚举方案演进代价的直观体验；
2. 不变量包装：为 BytesMap 建立私有构造器 GetSource::from_normalized_bytes(...)，在构造时完成 URL 规范化，让 get 的实现可以省略校验；
3. 与 sealed trait 对照：把同样的 API 用 Sealed traits 一课中的 mod sealed 模式重写，比较两者的调用方式与演进感受。

小结

从 OOP 到 Rust 的迁移中，"继承给出开放多态"的惯性思维是最需要克服的一点。本课给出的答案简洁有力：当你的 API 只认一组固定的、不期望被扩展的类型时，用枚举把它封闭起来。枚举作为代数数据类型：

• 为每个变体定义了独立的结构，本身就是一种"封闭的多态"；
• 让合法输入集合对调用方完全可见，构造即文档；
• 借助 match 的穷尽性检查，把"漏掉某种情况"从运行时错误变成编译期错误；
• 通过控制变体类型的构造方式，可以把不变量维护的责任收拢到构造器，让通用方法免于反复校验。

当然，它也有明确的代价：暴露实现细节、用户必须走变体构造器、变体变更会波及所有调用方、运行时分支而非编译期单态化。正因如此，课程把它与 Sticking with traits（开放 trait）和 Sealed traits（封闭 trait）并列呈现，供读者在实际问题中按"类型集合是否固定、用户是否需要扩展"这两个问题做出选择。掌握了这三种形态，你就拥有了从继承思维迁移到 Rust 多态思维的最完整工具箱。