Rust / 系统课时
为错误携带定位所需的数据
为错误携带定位所需的数据
只有错误名称而没有上下文,往往只能告诉你“失败了”,却不能告诉你失败发生在哪个文件、字段或业务对象上。Rust 的枚举变体可以直接携带定位数据。本节重点是如何保留足够的诊断信息,同时避免把密码、令牌、SQL 等敏感实现细节暴露给调用者。
学习目标
- 能为错误变体选择路径、字段名、输入值和标识等定位数据
- 能区分“诊断需要的信息”和“不应外泄的信息”
- 能用
Display控制对外错误文本,而保留结构化字段供程序处理
错误数据应该服务于定位
错误携带什么字段,应从排查问题需要回答的问题出发:哪个资源失败、哪个字段不合法、哪个对象不存在。常见且有价值的数据包括 PathBuf、字段名、业务 ID、非敏感输入值以及可安全公开的状态信息。
相比 InvalidConfig 这种无上下文错误,InvalidField { path, field, value } 可以让日志直接指向具体位置,也允许调用者按字段生成更精确的提示。结构化字段还比拼接好的字符串更容易测试和匹配。
用结构化字段保存上下文
下面的示例把配置文件路径、字段名和输入值放进错误变体。程序既可以模式匹配这些字段,也可以通过 Display 生成适合日志或命令行的文本。
use std::fmt;
use std::path::PathBuf;
#[derive(Debug)]
enum ConfigError {
Missing {
path: PathBuf,
},
InvalidField {
path: PathBuf,
field: &'static str,
value: String,
},
}
impl fmt::Display for ConfigError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ConfigError::Missing { path } => {
write!(f, "missing config: {}", path.display())
}
ConfigError::InvalidField {
path,
field,
value,
} => {
write!(
f,
"invalid field `{field}` in {}: `{value}`",
path.display()
)
}
}
}
}
fn parse_port(path: &str, content: Option<&str>) -> Result<u16, ConfigError> {
let path = PathBuf::from(path);
let text = content.ok_or_else(|| ConfigError::Missing {
path: path.clone(),
})?;
let value = text.trim();
value.parse::<u16>().map_err(|_| ConfigError::InvalidField {
path,
field: "port",
value: value.to_owned(),
})
}
fn main() {
for input in [None, Some("not-a-number")] {
if let Err(error) = parse_port("./app.conf", input) {
println!("{error}");
}
}
}预期输出:
missing config: ./app.conf
invalid field `port` in ./app.conf: `not-a-number`这个例子没有把上下文压成一条字符串,而是先保留为字段,再决定如何显示。这样测试代码可以直接匹配 field 或 path,日志系统也能把它们记录为结构化属性。
不是什么都应该塞进错误
“定位所需”不等于“底层能拿到的全部信息”。密码、访问令牌、完整请求体、银行卡号、原始 SQL 或内部网络地址,都可能在日志、API 响应或监控平台中扩散。
对于输入值本身,也要区分场景。像端口号、枚举值这类低敏感数据通常可以直接保留;自由文本、认证头或用户秘密则更适合只记录“哪个字段失败”,必要时在更受控的诊断层保存底层原因。
对外展示与内部诊断分层
结构化错误让“程序如何处理”和“人看到什么文本”可以分开。枚举字段用于匹配与定位,Display 用于生成稳定、可读且经过筛选的消息;如果还需要底层 source 供开发者追踪,可以把它保留在内部错误层,而不是直接拼到面向用户的字符串里。
设计时只保留完成恢复、定位和审计所需的数据。字段越具体,排查越高效;暴露越克制,接口也越安全、越容易长期演进。