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:
[package]
name = "config-boundary"
version = "0.1.0"
edition = "2021"
[dependencies]
serde = { version = "1", features = ["derive"] }
toml = "0.8"准备 app.toml。这里故意让端口为 0,以触发业务校验,而不是语法错误:
host = "127.0.0.1"
port = 0src/main.rs:
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 保留下来,真正需要诊断细节时仍然能追到根因。
运行并验证错误契约
执行:
cargo run预期输出:
configuration error [port]: must be between 1 and 65535把 app.toml 改成合法值:
host = "127.0.0.1"
port = 8080再次执行:
cargo run预期输出:
listening on 127.0.0.1:8080实际构建日志可能包含 Cargo 的编译信息;这里只关心程序自身的标准输出或标准错误。
为什么上层契约会更稳
调用方现在不需要知道 toml 的具体错误文本,也不需要猜字符串里是否包含 read 或 parse。它只匹配 ConfigError 变体,就能决定是提示配置字段、展示底层原因,还是在服务启动时转换为统一退出策略。
同时,底层依赖仍被限制在边界内部。以后即使把 TOML 换成 YAML,最外层仍可以保留 Io、Parse、Validate 这类稳定分类,只替换解析层内部保存的具体来源类型或转换逻辑。
选择在哪一层记录日志
库函数和领域函数通常返回错误,上层应用边界负责记录一次。这样同一失败不会在 IO 层、解析层、业务层和 main 中反复打印。
需要额外上下文时,应把路径、字段名、操作名作为错误数据向上传递,而不是提前 eprintln!。这样既保留诊断信息,也把“如何展示、是否重试、是否退出”的决定交给真正拥有运行策略的那一层。