Rust / 系统课时
公开库的错误类型怎样保持兼容
公开库的错误类型怎样保持兼容
公开库的错误类型一旦进入下游代码的 match、测试和重试逻辑,就成为 API 契约的一部分。本篇聚焦三个演进风险:新增公开变体、穷尽匹配,以及把 std::io::Error 等底层类型直接暴露给调用方。
学习目标
- 判断哪些错误类型改动会让下游源码失去兼容性。
- 用
#[non_exhaustive]为未来新增错误类别预留空间。 - 区分稳定的领域分类与仅用于诊断的底层错误来源。
公开变体为什么会锁住未来设计
如果公开枚举允许下游做穷尽匹配,那么枚举当前有哪些变体,就等于承诺“未来仍只有这些情况”。库后来新增一个变体时,旧的 match 会变得不完整,调用方升级依赖后必须修改源码才能重新编译。
这类兼容性问题不是“运行时多了一种错误”这么简单,而是库作者改变了消费方必须处理的类型空间。对于长期维护的公共库,应先决定哪些分类值得成为稳定契约,再决定是否允许穷尽匹配。
| 公开设计 | 后续新增错误类别 | 主要代价 |
|---|---|---|
| 普通公开枚举 | 通常会破坏下游穷尽匹配 | 演进空间小 |
#[non_exhaustive] 枚举 |
可新增变体,下游必须保留兜底分支 | 调用方不能假设集合已封闭 |
| 公开变体直接包底层错误 | 更换底层实现可能影响下游类型匹配 | 实现细节泄漏 |
稳定分类 + 不透明 source |
分类可稳定,底层实现可替换 | 下游不应依赖具体 source 类型 |
用 non_exhaustive 明确“未来还会增加”
如果错误类别会随着协议、存储后端或平台能力增加,适合在第一次发布前就把公开枚举标记为 #[non_exhaustive]。这样下游必须写兜底分支,库才能在后续版本中增加新变体而不要求所有调用方同步修改匹配逻辑。
片段示例(库 crate 中的公开契约):
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ErrorKind {
NotFound,
PermissionDenied,
}片段示例(依赖该库的消费方 crate):
fn classify(kind: ErrorKind) -> &'static str {
match kind {
ErrorKind::NotFound => "not found",
ErrorKind::PermissionDenied => "permission denied",
_ => "other",
}
}这里的 _ 不是“偷懒”,而是兼容性协议的一部分。将来库增加 RateLimited,旧消费方仍可编译,并会把它归入 "other"。如果需要对新类别采取专门动作,消费方可以在升级后再显式增加分支。
不要把底层实现当成控制流契约
公开错误常见的另一种锁死方式,是把实现细节直接放进可匹配变体,例如 Error::Io(std::io::Error)。一旦下游开始匹配 Io、读取具体错误种类,库以后从文件切换到数据库、远程存储或内存实现,就很难在不影响调用方的前提下替换底层机制。
更稳妥的做法,是把调用方真正需要据此做决策的类别暴露成稳定字段,把具体错误保留为 source,用于日志、诊断和错误链追踪。下面是一个不依赖第三方宏的片段示例:
use std::error::Error as StdError;
use std::fmt;
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ErrorKind {
NotFound,
PermissionDenied,
InvalidData,
}
#[derive(Debug)]
pub struct LibraryError {
kind: ErrorKind,
source: Option<Box<dyn StdError + Send + Sync + 'static>>,
}
impl LibraryError {
pub fn kind(&self) -> ErrorKind {
self.kind
}
fn with_source(
kind: ErrorKind,
source: impl StdError + Send + Sync + 'static,
) -> Self {
Self {
kind,
source: Some(Box::new(source)),
}
}
}
impl fmt::Display for LibraryError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "library operation failed: {:?}", self.kind)
}
}
impl StdError for LibraryError {
fn source(&self) -> Option<&(dyn StdError + 'static)> {
self.source
.as_deref()
.map(|err| err as &(dyn StdError + 'static))
}
}kind() 是面向控制流的稳定入口;source() 则保留根因链。消费方可以记录 source,但不应把“当前 source 恰好是某个具体实现类型”当作长期保证,否则仍会把库的内部实现重新变成事实上的公共 API。
规划稳定边界而不是冻结所有细节
设计公共错误时,可以把问题拆成两个层次:调用方必须稳定识别什么,以及调用方只需要知道发生过什么。前者适合少量、语义稳定的错误类别;后者适合消息、上下文和 source 链。
如果某个错误只影响日志文案,就没有必要为它增加新的公开变体;如果调用方需要据此决定“重试、提示用户、重新认证还是终止”,才值得考虑成为公开分类。这样错误类型不会因为每次内部重构都膨胀,也能为后续版本留下兼容演进空间。