Rust / 系统课时

区分用户消息与内部诊断信息

区分用户消息与内部诊断信息

错误发生后,系统往往同时面对两类读者:用户只需要知道发生了什么以及下一步能做什么,开发者却需要操作位置、错误链和根因。把这两类信息分开,能同时提高可用性、可观测性与安全性。

学习目标

  • 区分面向用户的稳定提示与面向开发者的诊断信息
  • 在 Rust 错误类型中同时保留公开消息和底层 source
  • 理解在接口边界统一转换错误,而不是在底层提前丢失上下文

两类信息解决不同问题

用户消息的目标是帮助业务操作继续进行,因此应简洁、稳定,避免泄露文件路径、数据库语句、令牌、内部服务名或第三方响应细节。内部诊断信息则用于定位问题,需要保留发生操作、关键上下文和底层错误链。

信息 主要读者 适合包含 不应包含
用户消息 最终用户或 API 调用方 可理解的原因、下一步动作、稳定错误码 堆栈、路径、凭据、内部拓扑
内部诊断 开发与运维 操作语义、字段名、错误链、请求关联信息 无必要的敏感业务数据

关键点不是“把错误写两遍”,而是让同一个错误在不同边界以不同形式呈现。底层仍然保留原始原因,上层决定哪些内容可以公开。

在错误类型里保留两条信息通道

下面的完整示例把公开提示放在 public_message 中,同时通过 Error::source 保存解析失败的根因。Display 用于内部诊断,不直接当作用户响应。

rust
use std::error::Error;
use std::fmt;
use std::num::ParseIntError;

#[derive(Debug)]
// 对外提示保持稳定,内部字段保留定位所需上下文。
struct AppError {
    public_message: &'static str,
    operation: &'static str,
    source: ParseIntError,
}

impl AppError {
    fn public_message(&self) -> &'static str {
        self.public_message
    }
}

impl fmt::Display for AppError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}: {}", self.operation, self.source)
    }
}

// source 保留底层原因,供日志边界继续遍历。
impl Error for AppError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        Some(&self.source)
    }
}

fn parse_port(input: &str) -> Result<u16, AppError> {
    input.parse::<u16>().map_err(|source| AppError {
        public_message: "端口配置无效",
        operation: "parse service port failed",
        source,
    })
}

fn main() {
    match parse_port("not-a-number") {
        Ok(port) => println!("监听端口: {port}"),
        Err(err) => {
            // 用户通道与诊断通道分开,避免把内部细节直接暴露出去。
            println!("返回给用户: {}", err.public_message());
            eprintln!("内部诊断: {err}");

            if let Some(source) = err.source() {
                eprintln!("根因: {source}");
            }
        }
    }
}

预期输出

text
返回给用户: 端口配置无效
内部诊断: parse service port failed: invalid digit found in string
根因: invalid digit found in string

这里公开内容只有“端口配置无效”,而诊断信息还说明失败动作与解析根因。真实服务中,前者通常进入 HTTP 响应、CLI 提示或界面文案,后者进入日志系统。

在边界处决定公开什么

错误越靠近基础设施层,越不应该决定最终用户看到的文案。文件读取、SQL、HTTP 客户端等底层代码只负责保留技术原因;应用或接口边界再把它映射成稳定的用户消息。

例如,数据库连接失败、连接池超时和 DNS 解析失败都可能统一映射成“服务暂时不可用”,但内部日志仍应区分真实根因。这样既不会让接口契约随底层实现变化,也不会为了“提示友好”而丢失排障所需信息。

哪些信息应该进入哪一侧

用户侧信息应稳定且可操作,例如“参数格式不正确”“资源不存在”“服务暂时不可用”。内部侧信息则要回答“哪个操作失败、输入处于什么业务上下文、底层原因是什么”。

如果产品确实需要向用户暴露更多细节,优先增加经过设计的错误码或结构化字段,而不是把内部错误字符串原样透传。这样可以让公开契约保持可控,同时保留完整诊断链供开发者排查。

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

目录与阅读设置

阅读设置

17

记录一个想法

区分用户消息与内部诊断信息

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

登录哪都通