Rust / 系统课时
用检查清单评审错误处理代码
用检查清单评审错误处理代码
错误处理评审的目标不是把所有错误都“包一层”,而是确认失败能否被调用方理解、处置和验证。下面用六个维度检查 Rust 工程中的 Result、错误类型、上下文、panic、日志与测试,并把问题转成可执行的评审意见。
学习目标
- 用六个维度快速发现错误处理中的工程性缺陷。
- 判断错误应保留类型、补充上下文,还是在边界处转换与记录。
- 用可运行示例验证错误分支是否可测试、可诊断且不过度
panic。
先按六个维度扫描代码
评审时先看失败是怎样流动的,再看具体写法是否优雅。重点不是要求每层都定义一种错误,而是让可恢复失败保持为 Result,让调用方在合适的边界做决定。
| 维度 | 应检查什么 | 常见问题 |
|---|---|---|
| 可恢复性 | 输入错误、文件缺失、网络失败等是否通过 Result 返回 |
对外部失败直接 unwrap()、expect() |
| 类型边界 | 领域内部是否保留可匹配的错误类型,是否过早变成字符串 | 到处使用 Result<T, String>,调用方只能解析文本 |
| 上下文 | 错误是否包含操作对象、关键参数或来源位置 | 只留下“parse failed”,无法知道解析了什么 |
panic |
是否只用于不可恢复的程序不变量破坏 | 把用户输入、配置缺失当成崩溃条件 |
| 日志 | 是否在真正负责处置的边界记录一次,字段是否可关联 | 每层都打印同一错误,产生重复日志 |
| 测试 | 成功路径和关键错误分支是否都能稳定断言 | 只测成功,或只比较整段错误文案 |
看错误是否保留了可恢复信息
如果函数可能因为正常环境条件失败,首先问“调用方还能做什么”。能重试、提示用户、切换默认值、返回 HTTP 状态码的失败,都应优先用 Result 表达,而不是直接 panic。
还要检查错误是否过早被压平成字符串。字符串适合最终展示,不适合作为内部控制流。调用方若需要区分“空配置”和“端口格式错误”,就应得到可匹配的枚举变体,而不是解析 "invalid port" 这样的文本。
一个实用原则是:库和领域层尽量返回结构化错误,应用边界再决定怎样展示、记录或映射成协议错误。 这样既能保持类型信息,又不会让底层代码承担 UI、HTTP 或日志策略。
用主示例检查类型、上下文与 panic
下面的 src/main.rs 是完整示例。解析端口时保留错误类型与来源上下文;正常配置错误不会触发 panic;只有应用入口决定如何输出并退出。
use std::error::Error;
use std::fmt;
#[derive(Debug, PartialEq)]
enum PortError {
Empty { origin: String },
Invalid { origin: String, value: String },
}
impl fmt::Display for PortError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
PortError::Empty { origin } => {
write!(f, "port is empty in {origin}")
}
PortError::Invalid { origin, value } => {
write!(f, "invalid port '{value}' in {origin}")
}
}
}
}
impl Error for PortError {}
fn parse_port(origin: &str, raw: &str) -> Result<u16, PortError> {
let value = raw.trim();
if value.is_empty() {
return Err(PortError::Empty {
origin: origin.to_owned(),
});
}
value.parse::<u16>().map_err(|_| PortError::Invalid {
origin: origin.to_owned(),
value: value.to_owned(),
})
}
fn main() {
match parse_port("config/app.env", "8080") {
Ok(port) => println!("accepted port: {port}"),
Err(err) => {
// 应用边界负责最终展示;底层函数不重复打印同一错误。
eprintln!("configuration error: {err}");
std::process::exit(2);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn invalid_port_keeps_context_and_type() {
let err = parse_port("config/app.env", "70000").unwrap_err();
assert_eq!(
err,
PortError::Invalid {
origin: "config/app.env".to_owned(),
value: "70000".to_owned(),
}
);
}
}预期结果:将代码保存到一个 Cargo 二进制项目的 src/main.rs 后应能通过编译;执行下面的命令可验证正常路径。
cargo run --quiet预期输出:
accepted port: 8080再运行错误分支测试:
cargo test --quiet预期输出中的耗时等细节可能不同,但应包含:
running 1 test
.
test result: ok. 1 passed; 0 failed这个实现可以从六个维度逐项检查:配置错误通过 Result 可恢复;PortError 保留类型;origin 和 value 提供诊断上下文;业务失败不 panic;输出集中在应用边界;测试直接断言错误变体和字段,而不是依赖易变的完整文案。
重点检查日志是不是只记一次
同一个错误在仓储层、服务层和入口层各打印一次,通常不会增加信息,只会制造三条近似日志。评审时要追踪责任边界:底层函数负责返回错误和补充必要上下文,真正决定重试、降级、返回状态码或结束进程的上层再记录。
如果项目使用 tracing 等结构化日志框架,优先记录请求 ID、资源 ID、错误类型等可检索字段;错误文本用于解释,字段用于关联。不要为了“日志更详细”而把敏感配置或用户凭据直接写进去。
把检查结果写成可执行的评审意见
好的评审意见应指出风险、边界和修改方向,而不是只写“这里错误处理不好”。可以按下面的方式落地:
- “这里的文件读取失败属于运行时可恢复错误,请返回
Result,不要expect;由调用者决定是否使用默认配置。” - “当前把
ParseIntError转成了String,导致上层无法区分错误类型;建议在本模块错误枚举中保留对应变体。” - “错误消息缺少配置来源,请补充文件或字段上下文,但不要记录密钥值。”
- “该错误已经在服务层记录,HTTP 入口又记录一次;保留在最终处置边界的一次结构化日志即可。”
- “测试只覆盖成功路径,请至少补一个关键错误分支,并断言错误变体而不是完整展示文本。”
一次错误处理评审完成后,代码应能回答三个问题:失败发生在哪里、调用方可以怎样处理、出问题时能否通过类型和上下文稳定定位。若这三点清楚,Result、日志和测试通常也会落在正确的工程边界上。