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;只有应用入口决定如何输出并退出。

rust
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 后应能通过编译;执行下面的命令可验证正常路径。

bash
cargo run --quiet

预期输出:

text
accepted port: 8080

再运行错误分支测试:

bash
cargo test --quiet

预期输出中的耗时等细节可能不同,但应包含:

text
running 1 test
.
test result: ok. 1 passed; 0 failed

这个实现可以从六个维度逐项检查:配置错误通过 Result 可恢复;PortError 保留类型;origin 和 value 提供诊断上下文;业务失败不 panic;输出集中在应用边界;测试直接断言错误变体和字段,而不是依赖易变的完整文案。

重点检查日志是不是只记一次

同一个错误在仓储层、服务层和入口层各打印一次,通常不会增加信息,只会制造三条近似日志。评审时要追踪责任边界:底层函数负责返回错误和补充必要上下文,真正决定重试、降级、返回状态码或结束进程的上层再记录。

如果项目使用 tracing 等结构化日志框架,优先记录请求 ID、资源 ID、错误类型等可检索字段;错误文本用于解释,字段用于关联。不要为了“日志更详细”而把敏感配置或用户凭据直接写进去。

把检查结果写成可执行的评审意见

好的评审意见应指出风险、边界和修改方向,而不是只写“这里错误处理不好”。可以按下面的方式落地:

  • “这里的文件读取失败属于运行时可恢复错误,请返回 Result,不要 expect;由调用者决定是否使用默认配置。”
  • “当前把 ParseIntError 转成了 String,导致上层无法区分错误类型;建议在本模块错误枚举中保留对应变体。”
  • “错误消息缺少配置来源,请补充文件或字段上下文,但不要记录密钥值。”
  • “该错误已经在服务层记录,HTTP 入口又记录一次;保留在最终处置边界的一次结构化日志即可。”
  • “测试只覆盖成功路径,请至少补一个关键错误分支,并断言错误变体而不是完整展示文本。”

一次错误处理评审完成后,代码应能回答三个问题:失败发生在哪里、调用方可以怎样处理、出问题时能否通过类型和上下文稳定定位。若这三点清楚,Result、日志和测试通常也会落在正确的工程边界上。

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

目录与阅读设置

阅读设置

17

记录一个想法

用检查清单评审错误处理代码

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

登录哪都通