在设计Rust库时，一个常被忽视却至关重要的问题是API的未来可扩展性。我们来设想一个典型的场景。
我们设计了一个枚举类型，用于描述网络请求状态：
pub enum Status {
Ok,
NotFound,
Unauthorized,
}
使用这个枚举的用户可能会写出如下代码：
match status {
Status::Ok => println!("success"),
Status::NotFound => println!("not found"),
Status::Unauthorized => println!("no permission"),
}
这段代码看起来完全没有问题，逻辑清晰。但如果未来你想为这个库增加一个新功能，需要新增一个Timeout状态，该怎么办？
pub enum Status {
Ok,
NotFound,
Unauthorized,
Timeout, // 新增变体
}
此时，所有下游用户之前编写的match语句都会立刻编译失败。因为Rust的穷尽性匹配要求必须处理所有可能的变体。这意味着，仅仅是一个简单的功能扩展，就可能导致大量的用户代码被迫修改，形成一次破坏性更新。
为了解决这类因API演进而引发的兼容性问题，Rust专门提供了一个属性宏：#[non_exhaustive]。
#[non_exhaustive] 是什么？
简单来说，#[non_exhaustive]是一个标记，它向编译器和其他开发者声明：这个类型（枚举、结构体或枚举变体）在未来版本中可能会增加新的成员。它会阻止外部代码对其进行穷尽匹配或直接构造。
它主要应用于三种对象：
用于枚举
给枚举加上这个标记：
#[non_exhaustive]
pub enum Status {
Ok,
NotFound,
Unauthorized,
}
此时，当其他crate使用这个Status枚举时，编译器会强制要求他们在match表达式中必须包含一个通配符分支：
match status {
Status::Ok => println!("success"),
Status::NotFound => println!("not found"),
Status::Unauthorized => println!("no permission"),
_ => println!("unknown status"), // 必须添加的通配分支
}
这样一来，即便当前版本只有三个变体，用户也必须为“未知”情况预留处理逻辑。这为库作者在未来添加Timeout或其他新状态码留出了安全的扩展空间，而不会破坏现有用户代码的编译。
用于结构体
#[non_exhaustive]同样可以应用于结构体：
#[non_exhaustive]
pub struct Config {
pub timeout: u64,
}
这个标记会产生一个关键影响：外部crate将无法使用结构体字面量语法直接构造Config的实例。
// ❌ 错误！外部crate现在不能这样写
let c = Config { timeout: 30 };
因为未来库作者可能会为Config增加新的字段（例如retries: u32）。为了保持向前兼容，用户必须通过库提供的构造函数来创建实例：
// ✅ 正确，通过库提供的工厂方法创建
let c = Config::new();
// 或者
let c = Config::with_timeout(30);
这种方式将结构体内部字段的布局完全封装起来，赋予了库作者极大的未来灵活性。
什么时候应该使用 #[non_exhaustive]？
1. 公共库的API设计
这是#[non_exhaustive]最重要的应用场景。当你设计一个会被其他开发者使用的库时，对于未来可能扩展的类型，都应考虑使用它。一个经典的例子是错误枚举：
#[non_exhaustive]
pub enum Error {
Io(std::io::Error),
Parse(String),
}
现在，未来你可以安全地添加Error::Timeout或Error::PermissionDenied等新变体，而不会导致下游用户代码编译失败，这避免了破坏性版本升级。事实上，Rust标准库自身就广泛使用了这一属性，例如std::io::ErrorKind，为操作系统可能新增的错误类型预留了空间。
2. 表示“开放集合”的枚举
如果一个枚举建模的是现实世界中可能不断扩展的概念，它就适合被标记为non_exhaustive。例如HTTP状态码：
#[non_exhaustive]
pub enum HttpStatus {
Ok,
NotFound,
InternalServerError,
}
HTTP协议本身在演进，新的状态码可能被定义，因此这个枚举在逻辑上就是一个开放集合，不应该被外部代码穷尽匹配。
3. 防止用户依赖内部实现细节
有时，一个结构体现在可能只有一两个字段，但你清楚地知道未来会添加更多配置项。使用#[non_exhaustive]可以强制用户通过构造函数来获取实例，而不是依赖当前的字面量结构，从而为未来的扩展铺平道路。
为什么说它“值得拥有”？
1. 维护API的向后兼容性
根据Rust的语义版本规范，为公有枚举新增变体属于破坏性变更，需要主版本号升级。#[non_exhaustive]巧妙地绕开了这一限制，使得新增变体成为一种非破坏性的添加。它让你的API更容易演进、更加稳定，也更符合语义化版本控制的初衷。
2. 强制用户编写更健壮的代码
在没有#[non_exhaustive]的情况下，用户可能写出看似完整、实则脆弱的匹配：
match error {
Error::Io(e) => handle_io(e),
Error::Parse(e) => handle_parse(e),
// 如果未来新增Error变体，这里会编译失败
}
而使用了#[non_exhaustive]后，用户被迫思考“未知情况”的处理：
match error {
Error::Io(e) => handle_io(e),
Error::Parse(e) => handle_parse(e),
_ => log_unknown_error(), // 处理未来可能出现的新错误
}
这样，即使库在未来版本中增加了新的错误类型，用户的程序也能以定义好的方式（如记录日志、返回默认错误）优雅处理，而非直接崩溃或无法编译。
3. 避免“API被过早锁死”
一个没有#[non_exhaustive]的公有枚举，相当于向所有用户做出了一个强有力的承诺：此枚举的变体集合已经最终确定，永不变更。然而在实际的库开发与业务演进中，这种承诺往往难以维持。#[non_exhaustive]属性提供了一种机制，避免因早期的设计决策而将API“锁死”，为后续的迭代保留了必要的灵活性。
使用#[non_exhaustive]的最佳实践
1. 主要应用于公共API
#[non_exhaustive]的意义在于定义跨crate边界的契约。对于仅限内部模块使用的类型，通常没有必要添加此属性。
2. 避免滥用
并非所有枚举都需要它。如果一个枚举在逻辑上就是一个封闭集合，则不应使用。例如：
pub enum Direction {
Up,
Down,
Left,
Right,
}
空间的基本方向不会增加第五个，这是一个逻辑上封闭的集合，使用#[non_exhaustive]反而会误导使用者。
3. 为non_exhaustive结构体提供构造函数
如果你将一个结构体标记为#[non_exhaustive]，那么提供便捷的构造函数（如new()）就几乎是必须的，否则用户将无法创建该类型的实例。
#[non_exhaustive]
pub struct Config {
pub timeout: u64,
}
impl Config {
pub fn new() -> Self {
Self { timeout: 30 }
}
// 也可以提供 with_timeout 等构造器
}
4. 可单独作用于枚举变体
有时，你只希望枚举中的某个特定变体（通常是带字段的元组或结构体变体）可以扩展，而其他变体保持不变。你可以将属性直接标在变体上：
pub enum Event {
Click,
#[non_exhaustive]
KeyPress {
code: u32,
}
}
这样，未来你可以向KeyPress变体中添加新字段（如modifiers: u8），而不会构成破坏性变更。
总结
#[non_exhaustive]是Rust为库设计者量身打造的一项重要工具，它通过在类型系统层面划定“开放边界”，巧妙地平衡了API的稳定性和演进灵活性。它强制了更健壮的用户代码，并使得“新增枚举变体或结构体字段”从一项破坏性变更转变为安全的增量更新。
当你在设计一个Rust库，尤其是其公共API时，如果预见到某个枚举或结构体在未来很可能需要扩展，那么认真考虑使用#[non_exhaustive]将是明智之举。它不仅能提升你的库在长期演进中的兼容性与健壮性，也是体现专业API设计思想的重要标志。在云栈社区的Rust技术讨论中，如何优雅地设计长期稳定的API也是一个经常被深入探讨的话题。
参考链接：https://doc.rust-lang.org/reference/attributes/type_system.html
发表于 11 小时前
|
查看: 2|
回复: 0
