Rust / 系统课时
定义错误类型
定义错误类型
当字符串错误或通用错误对象无法表达业务含义时,应把可能失败的情况建模为明确的错误类型。本课将实现一个配置读取错误枚举,并接入 Display、Error 与 From,使错误既能分类处理,也能配合 ? 传播。
学习目标
- 使用枚举表达不同失败原因
- 实现标准错误接口并保留错误链
- 通过
From让底层错误自动转换
先确定错误边界
自定义错误类型的重点不是“把所有异常都包起来”,而是让调用方知道哪些失败值得区分。读取端口配置时,文件不可读、格式不正确、数字无法解析和端口超出业务范围,通常需要不同的提示或处理策略,因此适合建模为不同枚举变体。
错误变体应携带诊断所需的最少信息。底层系统错误可以直接保存原始错误对象;业务校验错误则保存触发问题的值。不要只保存一段拼接后的字符串,否则调用方只能比较文本,难以稳定分类。
完整示例:配置读取错误
下面的程序定义 ConfigError,读取 port=<数字> 格式的配置,并要求端口位于 1 到 65535 之间。
use std::{
error::Error,
fmt,
fs,
io,
num::ParseIntError,
};
#[derive(Debug)]
enum ConfigError {
Io(io::Error),
InvalidFormat(String),
InvalidPort(ParseIntError),
PortOutOfRange(u32),
}
impl fmt::Display for ConfigError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Io(_) => write!(f, "无法读取配置文件"),
Self::InvalidFormat(line) => write!(f, "配置格式错误:{line}"),
Self::InvalidPort(_) => write!(f, "端口必须是整数"),
Self::PortOutOfRange(value) => {
write!(f, "端口 {value} 不在 1 到 65535 范围内")
}
}
}
}
impl Error for ConfigError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
// 保留底层错误,便于日志系统打印完整错误链
Self::Io(error) => Some(error),
Self::InvalidPort(error) => Some(error),
Self::InvalidFormat(_) | Self::PortOutOfRange(_) => None,
}
}
}
impl From<io::Error> for ConfigError {
fn from(error: io::Error) -> Self {
Self::Io(error)
}
}
impl From<ParseIntError> for ConfigError {
fn from(error: ParseIntError) -> Self {
Self::InvalidPort(error)
}
}
fn load_port(path: &str) -> Result<u16, ConfigError> {
let content = fs::read_to_string(path)?;
let line = content.trim();
let (key, value) = line
.split_once('=')
.ok_or_else(|| ConfigError::InvalidFormat(line.to_string()))?;
if key.trim() != "port" {
return Err(ConfigError::InvalidFormat(line.to_string()));
}
let port = value.trim().parse::<u32>()?;
if !(1..=65_535).contains(&port) {
return Err(ConfigError::PortOutOfRange(port));
}
Ok(port as u16)
}
fn main() -> Result<(), Box<dyn Error>> {
const PATH: &str = "app.conf";
fs::write(PATH, "port=8080\n")?;
match load_port(PATH) {
Ok(port) => println!("port = {port}"),
Err(error) => eprintln!("{error}"),
}
fs::remove_file(PATH)?;
Ok(())
}预期输出:
port = 8080把配置改成 port=70000 后,程序会进入 PortOutOfRange 分支并输出业务可读的错误。由于该分支不是底层系统错误,source() 返回 None;文件读取和整数解析错误则保留原始来源。
标准接口各自负责什么
| 接口 | 主要作用 | 本例中的职责 |
|---|---|---|
Debug |
面向开发调试 | 展示枚举变体和内部字段 |
Display |
面向用户或日志摘要 | 输出稳定、可读的错误说明 |
Error |
接入标准错误生态 | 通过 source() 暴露底层错误链 |
From |
定义类型转换 | 让 io::Error 和 ParseIntError 可被 ? 自动转换 |
Error 的实现通常依赖 Debug 和 Display。From 不属于 Error trait,但它决定了底层错误能否顺畅传播到当前业务错误类型。
让调用方按类型处理
调用方需要做差异化处理时,应直接匹配枚举变体。例如,PortOutOfRange(value) 可以提示用户修改配置,Io(error) 则可能记录路径、权限或磁盘故障信息。这样分支依据是类型,而不是容易变化的错误文本。
对外发布的库如果未来可能新增错误变体,可以在错误枚举上使用 #[non_exhaustive]。调用方随后必须保留通配分支,避免新增变体破坏兼容性。应用内部的封闭错误类型通常不必使用该属性。
设计时的常见错误
不要在 Display 中输出密码、令牌或完整敏感配置。面向用户的消息应说明可采取的动作,详细上下文可以通过日志字段单独记录。
也不要为每个底层库错误机械增加一个变体。只有调用方需要识别或保留错误来源时才单独建模;其余错误可以在模块边界统一归类,避免错误枚举随依赖实现无限膨胀。
本课总结
- 枚举变体用于表达调用方真正需要区分的失败类型
Display提供可读消息,Error::source保留底层错误链- 实现
From后,兼容的底层错误可以继续使用?传播
下一课预告
下一课将进一步整理错误处理边界,比较返回 Result、在入口统一记录错误与使用 panic! 的适用场景。