Rust / 系统课时

重构 IO 解析与校验错误边界

重构 IO 解析与校验错误边界

配置加载需要连续跨过文件 IO、反序列化和业务校验三个失败点。如果它们最终都变成字符串,上层就失去分类处理能力。本篇用一个完整 Rust 示例建立分层错误,并让调用方只依赖稳定的 ConfigError 契约。

学习目标

  • 为 IO、反序列化和业务校验建立独立错误变体
  • 保留底层 source,同时向上层暴露稳定错误类型
  • 把日志与退出策略留在应用边界,避免多层重复处理

把失败点映射成稳定错误类型

三个阶段的错误性质不同:IO 需要路径和原始 io::Error,解析需要保留 toml::de::Error,校验则更适合暴露字段名和业务消息。统一枚举的意义,是让上层只认识一个错误入口,同时仍能按变体做精确决策。

读取、反序列化与业务校验的分层错误边界

这里的“稳定”不是保证错误文本永远不变,而是保证调用方可以依赖 ConfigError::Io、ConfigError::Parse、ConfigError::Validate 这些分类,而不是解析字符串内容。

实现分层配置加载器

创建一个最小项目,Cargo.toml 使用已发布的 serde 与 toml API:

toml
[package]
name = "config-boundary"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = { version = "1", features = ["derive"] }
toml = "0.8"

准备 app.toml。这里故意让端口为 0,以触发业务校验,而不是语法错误:

toml
host = "127.0.0.1"
port = 0

src/main.rs:

rust
use serde::Deserialize;
use std::error::Error;
use std::fmt;
use std::fs;
use std::io;

#[derive(Debug, Deserialize)]
struct RawConfig {
    host: String,
    port: i64,
}

#[derive(Debug)]
struct Config {
    host: String,
    port: u16,
}

#[derive(Debug)]
enum ConfigError {
    Io {
        path: String,
        source: io::Error,
    },
    Parse {
        path: String,
        source: toml::de::Error,
    },
    Validate {
        field: &'static str,
        message: String,
    },
}

impl fmt::Display for ConfigError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Io { path, .. } => write!(f, "cannot read config file: {path}"),
            Self::Parse { path, .. } => write!(f, "invalid TOML in config file: {path}"),
            Self::Validate { field, message } => {
                write!(f, "invalid field {field}: {message}")
            }
        }
    }
}

impl Error for ConfigError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            Self::Io { source, .. } => Some(source),
            Self::Parse { source, .. } => Some(source),
            Self::Validate { .. } => None,
        }
    }
}

fn validate(raw: RawConfig) -> Result<Config, ConfigError> {
    if raw.host.trim().is_empty() {
        return Err(ConfigError::Validate {
            field: "host",
            message: "must not be empty".to_string(),
        });
    }

    if !(1..=65535).contains(&raw.port) {
        return Err(ConfigError::Validate {
            field: "port",
            message: "must be between 1 and 65535".to_string(),
        });
    }

    Ok(Config {
        host: raw.host,
        port: raw.port as u16,
    })
}

fn load_config(path: &str) -> Result<Config, ConfigError> {
    let text = fs::read_to_string(path).map_err(|source| ConfigError::Io {
        path: path.to_string(),
        source,
    })?;

    let raw: RawConfig = toml::from_str(&text).map_err(|source| ConfigError::Parse {
        path: path.to_string(),
        source,
    })?;

    validate(raw)
}

fn main() {
    match load_config("app.toml") {
        Ok(config) => println!("listening on {}:{}", config.host, config.port),
        Err(ConfigError::Validate { field, message }) => {
            eprintln!("configuration error [{field}]: {message}");
        }
        Err(err) => {
            eprintln!("configuration error: {err}");
            if let Some(source) = err.source() {
                eprintln!("caused by: {source}");
            }
        }
    }
}

load_config 不记录日志,只负责把每一层失败转换为稳定的错误变体。原始 IO 与 TOML 错误通过 Error::source 保留下来,真正需要诊断细节时仍然能追到根因。

运行并验证错误契约

执行:

bash
cargo run

预期输出:

text
configuration error [port]: must be between 1 and 65535

把 app.toml 改成合法值:

toml
host = "127.0.0.1"
port = 8080

再次执行:

bash
cargo run

预期输出:

text
listening on 127.0.0.1:8080

实际构建日志可能包含 Cargo 的编译信息;这里只关心程序自身的标准输出或标准错误。

为什么上层契约会更稳

调用方现在不需要知道 toml 的具体错误文本,也不需要猜字符串里是否包含 read 或 parse。它只匹配 ConfigError 变体,就能决定是提示配置字段、展示底层原因,还是在服务启动时转换为统一退出策略。

同时,底层依赖仍被限制在边界内部。以后即使把 TOML 换成 YAML,最外层仍可以保留 Io、Parse、Validate 这类稳定分类,只替换解析层内部保存的具体来源类型或转换逻辑。

选择在哪一层记录日志

库函数和领域函数通常返回错误,上层应用边界负责记录一次。这样同一失败不会在 IO 层、解析层、业务层和 main 中反复打印。

需要额外上下文时,应把路径、字段名、操作名作为错误数据向上传递,而不是提前 eprintln!。这样既保留诊断信息,也把“如何展示、是否重试、是否退出”的决定交给真正拥有运行策略的那一层。

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

目录与阅读设置

阅读设置

17

记录一个想法

重构 IO 解析与校验错误边界

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

登录哪都通