Rust / 系统课时

为错误携带定位所需的数据

为错误携带定位所需的数据

只有错误名称而没有上下文,往往只能告诉你“失败了”,却不能告诉你失败发生在哪个文件、字段或业务对象上。Rust 的枚举变体可以直接携带定位数据。本节重点是如何保留足够的诊断信息,同时避免把密码、令牌、SQL 等敏感实现细节暴露给调用者。

学习目标

  • 能为错误变体选择路径、字段名、输入值和标识等定位数据
  • 能区分“诊断需要的信息”和“不应外泄的信息”
  • 能用 Display 控制对外错误文本,而保留结构化字段供程序处理

错误数据应该服务于定位

错误携带什么字段,应从排查问题需要回答的问题出发:哪个资源失败、哪个字段不合法、哪个对象不存在。常见且有价值的数据包括 PathBuf、字段名、业务 ID、非敏感输入值以及可安全公开的状态信息。

相比 InvalidConfig 这种无上下文错误,InvalidField { path, field, value } 可以让日志直接指向具体位置,也允许调用者按字段生成更精确的提示。结构化字段还比拼接好的字符串更容易测试和匹配。

用结构化字段保存上下文

下面的示例把配置文件路径、字段名和输入值放进错误变体。程序既可以模式匹配这些字段,也可以通过 Display 生成适合日志或命令行的文本。

rust
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}");
        }
    }
}

预期输出:

text
missing config: ./app.conf
invalid field `port` in ./app.conf: `not-a-number`

这个例子没有把上下文压成一条字符串,而是先保留为字段,再决定如何显示。这样测试代码可以直接匹配 field 或 path,日志系统也能把它们记录为结构化属性。

不是什么都应该塞进错误

“定位所需”不等于“底层能拿到的全部信息”。密码、访问令牌、完整请求体、银行卡号、原始 SQL 或内部网络地址,都可能在日志、API 响应或监控平台中扩散。

对于输入值本身,也要区分场景。像端口号、枚举值这类低敏感数据通常可以直接保留;自由文本、认证头或用户秘密则更适合只记录“哪个字段失败”,必要时在更受控的诊断层保存底层原因。

对外展示与内部诊断分层

结构化错误让“程序如何处理”和“人看到什么文本”可以分开。枚举字段用于匹配与定位,Display 用于生成稳定、可读且经过筛选的消息;如果还需要底层 source 供开发者追踪,可以把它保留在内部错误层,而不是直接拼到面向用户的字符串里。

设计时只保留完成恢复、定位和审计所需的数据。字段越具体,排查越高效;暴露越克制,接口也越安全、越容易长期演进。

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

目录与阅读设置

阅读设置

17

记录一个想法

为错误携带定位所需的数据

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

登录哪都通