Rust / 系统课时

定义错误类型

定义错误类型

当字符串错误或通用错误对象无法表达业务含义时,应把可能失败的情况建模为明确的错误类型。本课将实现一个配置读取错误枚举,并接入 Display、Error 与 From,使错误既能分类处理,也能配合 ? 传播。

学习目标

  • 使用枚举表达不同失败原因
  • 实现标准错误接口并保留错误链
  • 通过 From 让底层错误自动转换

先确定错误边界

自定义错误类型的重点不是“把所有异常都包起来”,而是让调用方知道哪些失败值得区分。读取端口配置时,文件不可读、格式不正确、数字无法解析和端口超出业务范围,通常需要不同的提示或处理策略,因此适合建模为不同枚举变体。

错误变体应携带诊断所需的最少信息。底层系统错误可以直接保存原始错误对象;业务校验错误则保存触发问题的值。不要只保存一段拼接后的字符串,否则调用方只能比较文本,难以稳定分类。

完整示例:配置读取错误

下面的程序定义 ConfigError,读取 port=<数字> 格式的配置,并要求端口位于 1 到 65535 之间。

rust
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(())
}

预期输出:

text
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! 的适用场景。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义错误类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通