Rust / 系统课时
区分用户消息与内部诊断信息
区分用户消息与内部诊断信息
错误发生后,系统往往同时面对两类读者:用户只需要知道发生了什么以及下一步能做什么,开发者却需要操作位置、错误链和根因。把这两类信息分开,能同时提高可用性、可观测性与安全性。
学习目标
- 区分面向用户的稳定提示与面向开发者的诊断信息
- 在 Rust 错误类型中同时保留公开消息和底层
source - 理解在接口边界统一转换错误,而不是在底层提前丢失上下文
两类信息解决不同问题
用户消息的目标是帮助业务操作继续进行,因此应简洁、稳定,避免泄露文件路径、数据库语句、令牌、内部服务名或第三方响应细节。内部诊断信息则用于定位问题,需要保留发生操作、关键上下文和底层错误链。
| 信息 | 主要读者 | 适合包含 | 不应包含 |
|---|---|---|---|
| 用户消息 | 最终用户或 API 调用方 | 可理解的原因、下一步动作、稳定错误码 | 堆栈、路径、凭据、内部拓扑 |
| 内部诊断 | 开发与运维 | 操作语义、字段名、错误链、请求关联信息 | 无必要的敏感业务数据 |
关键点不是“把错误写两遍”,而是让同一个错误在不同边界以不同形式呈现。底层仍然保留原始原因,上层决定哪些内容可以公开。
在错误类型里保留两条信息通道
下面的完整示例把公开提示放在 public_message 中,同时通过 Error::source 保存解析失败的根因。Display 用于内部诊断,不直接当作用户响应。
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}");
}
}
}
}预期输出
返回给用户: 端口配置无效
内部诊断: parse service port failed: invalid digit found in string
根因: invalid digit found in string这里公开内容只有“端口配置无效”,而诊断信息还说明失败动作与解析根因。真实服务中,前者通常进入 HTTP 响应、CLI 提示或界面文案,后者进入日志系统。
在边界处决定公开什么
错误越靠近基础设施层,越不应该决定最终用户看到的文案。文件读取、SQL、HTTP 客户端等底层代码只负责保留技术原因;应用或接口边界再把它映射成稳定的用户消息。
例如,数据库连接失败、连接池超时和 DNS 解析失败都可能统一映射成“服务暂时不可用”,但内部日志仍应区分真实根因。这样既不会让接口契约随底层实现变化,也不会为了“提示友好”而丢失排障所需信息。
哪些信息应该进入哪一侧
用户侧信息应稳定且可操作,例如“参数格式不正确”“资源不存在”“服务暂时不可用”。内部侧信息则要回答“哪个操作失败、输入处于什么业务上下文、底层原因是什么”。
如果产品确实需要向用户暴露更多细节,优先增加经过设计的错误码或结构化字段,而不是把内部错误字符串原样透传。这样可以让公开契约保持可控,同时保留完整诊断链供开发者排查。