需求:服务启动时读一个 port.txt,里面只有一行端口号。三种情况都会发生:文件不存在、文件内容不是数字、端口超出范围。产品要求三种都能给出人能看懂的提示,并且退出码非零,方便运维的启动脚本判断。
第一版通常这么写:
use std::fs;
fn main() {
let text = fs::read_to_string("port.txt").unwrap();
let port: u16 = text.trim().parse().unwrap();
println!("port = {port}");
}
文件不存在时,cargo run 直接崩:
thread 'main' panicked at src/main.rs:4:55:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound,
message: "系统找不到指定的文件。" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
背后那一大串 Os { code: 2, ... } 是给开发者看的调试信息,运维看不懂;而且 unwrap 不区分「文件不存在」和「内容不合法」,两种情况都是一句同样的 panic。unwrap 的本质是「我认为这里不会失败,失败就崩」——它没有错,错在这里的判断不成立。
这篇要解决的就是这个问题:怎么把「可能失败」写进函数签名,怎么用 ? 把错误往上交,以及什么时候 panic 才是合理选择。
场景走查:从 unwrap 到能报错的版本
目标版本要求:每种失败都有独立提示,正常时打印端口。先把错误定义成一个枚举,每个变体对应调用方需要区分的一种情况。
use std::fmt;
use std::fs;
use std::io;
#[derive(Debug)]
enum ConfigError {
Io(io::Error),
BadPort(String),
}
impl fmt::Display for ConfigError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
ConfigError::Io(e) => write!(f, "读配置失败:{e}"),
ConfigError::BadPort(raw) => write!(f, "端口不是数字:{raw:?}"),
}
}
}
impl From<io::Error> for ConfigError {
fn from(e: io::Error) -> Self {
ConfigError::Io(e)
}
}
fn load(path: &str) -> Result<u16, ConfigError> {
let text = fs::read_to_string(path)?;
let port = text
.trim()
.parse()
.map_err(|_| ConfigError::BadPort(text.clone()))?;
Ok(port)
}
fn main() {
match load("port.txt") {
Ok(p) => println!("port = {p}"),
Err(e) => {
eprintln!("加载失败:{e}");
std::process::exit(1);
}
}
}
三种输入的实际运行结果(本机 rustc 1.99、edition 2021 实测):
# port.txt 内容为 8080
port = 8080
# port.txt 内容为 abc
加载失败:端口不是数字:"abc"
# port.txt 不存在
加载失败:读配置失败:系统找不到指定的文件。 (os error 2)
退出码 1
注意最后一条的「系统找不到指定的文件。」是 Windows 系统给的中文文案,换平台或换语言环境会变。自己固定文案的写法是匹配 e.kind():
match e.kind() {
io::ErrorKind::NotFound => eprintln!("配置文件不存在:{path}"),
io::ErrorKind::PermissionDenied => eprintln!("没有权限读:{path}"),
_ => eprintln!("读配置失败:{e}"),
}
ErrorKind 是稳定的分类,Display 是给人看的字符串,两者用途不同:程序做分支判断用 kind,展示给用户用 Display。
Result 与 panic:两种完全不同的失败
Rust 里「失败」分两类,处理方式不同:
可恢复错误 → Result
调用方有办法应对:文件不存在可以提示用户,网络超时可以重试,端口被占用可以换一个。这类错误必须出现在返回类型里,强迫调用方处理。
不可恢复错误 → panic
程序已经处于非法状态,继续跑只会更糟:数组越界、断言失败、内部不变量被破坏。panic 展开栈、执行析构、打印位置后终止(或按配置直接 abort)。
第三类容易被忽略:程序员的 bug。这类也应该是 panic,比如「这个值按设计不可能为空」却空了。区别在于:可恢复错误是「外部世界不配合」,panic 是「我的代码假设错了」。前者要向上报告,后者要暴露出来让人修。
Result<T, E> 的定义很直白:Ok(T) 成功带值,Err(E) 失败带错误。关键是 E 选什么。E 不是「错误信息的容器」,而是「调用方能据此做什么决策」的载体。全部塞成 String 就失去了类型信息,调用方只能打印,不能分支。
| 错误类型选择 | 适合场景 | 代价 |
|---|---|---|
String / &str | 一次性脚本、原型、日志里随手记 | 调用方无法区分错误种类,无法重试或返回不同状态码 |
自定义 enum | 库、服务内部的模块边界 | 要写 Display、From 等样板,错误种类多时维护成本高 |
Box<dyn Error> | 应用入口、测试、不在乎分类的场合 | 丢失具体类型,只能打印;每次错误一次堆分配 |
标准库具体类型,如 io::Error | 只有一种失败来源的薄封装 | 多层组合时被迫手工转换 |
? 到底做了什么
? 不是语法糖式的「忽略错误」,它做三件事:取出 Ok 里的值;遇到 Err 就提前返回;返回前用 From 把错误转成函数签名里的错误类型。第三步是关键,也是大部分报错的来源。
第一个常见报错:函数根本不返回 Result。
fn load() {
let text = fs::read_to_string("config.toml")?;
println!("{}", text.len());
}
error[E0277]: the `?` operator can only be used in a function that returns
`Result` or `Option` (or another type that implements `FromResidual`)
|
3 | fn load() {
| --------- this function should return `Result` or `Option` to accept `?`
4 | let text = fs::read_to_string("config.toml")?;
| ^ cannot use the `?` operator
| in a function that returns `()`
|
help: consider adding return type
|
3 ~ fn load() -> Result<(), Box<dyn std::error::Error>> {
6 + Ok(())
|
人话版:? 遇到错误要「提前返回一个 Err」,可你的函数返回的是 (),返回不了 Err。编译器连改法都给了:改返回类型,末尾补 Ok(())。这是新手最常见的一类,通常发生在把一段代码从 main 挪进辅助函数的时候。
第二个报错:返回类型是 Result,但错误类型对不上。
fn load() -> Result<u16, ConfigError> {
let text = fs::read_to_string("port.txt")?;
let port: u16 = text.trim().parse()?;
Ok(port)
}
error[E0277]: `?` couldn't convert the error to `ConfigError`
|
7 | fn load() -> Result<u16, ConfigError> {
| ------------------------ expected `ConfigError` because of this
8 | let text = fs::read_to_string("port.txt")?;
| ------------------------------^ the trait `From<std::io::Error>`
| is not implemented for `ConfigError`
|
note: `ConfigError` needs to implement `From<std::io::Error>`
= note: the question mark operation (`?`) implicitly performs a conversion on
the error value using the `From` trait
error[E0271]: type mismatch resolving `<u16 as FromStr>::Err == ConfigError`
|
9 | let port: u16 = text.trim().parse()?;
| ^^^^^ expected `ConfigError`, found `ParseIntError`
两条错误是同一类问题:? 想把 io::Error 和 ParseIntError 变成 ConfigError,但没找到转换路径。修法就是前面那段程序里的 impl From<io::Error> for ConfigError,以及用 map_err 手动处理解析错误(因为要带上原始字符串)。
这里有个设计细节值得停一下:ParseIntError 其实也实现了 From,可以给枚举加一个 Parse(ParseIntError) 变体然后直接 ?。但这个错误对用户没用——用户需要知道「哪段文本不合法」,而不是「无效数字」。所以这里用 map_err 换成带上下文的 BadPort(String)。换句话说,? 能自动转换不代表就该自动转换,错误的可读性要自己负责。
? 也能用在返回 Option 的函数里,语义是「None 就提前返回 None」。判断标准同上:没有值不需要解释原因时用 Option,需要说明为什么失败时用 Result。自定义错误类型:按调用方怎么处理来划分
写自定义错误时,最容易犯的错是「按出错位置划分变体」,比如 ReadConfigFailed、ParseFailed、ConnectFailed。数量会越加越多,调用方还是一样只能打印。更好的划分是按「调用方要做什么」:
| 业务情况 | 变体设计 | 调用方动作 |
|---|---|---|
| 用户配置写错了 | BadConfig { field, reason } | 打印给用户,退出码 2,不重试 |
| 依赖的远端临时不可用 | Temporary { source } | 退避重试,超过次数再报错 |
| 权限或认证问题 | Unauthorized | 刷新凭据,或返回 401 |
| 自己的代码假设被破坏 | 不放进错误枚举,直接 panic! | 修 bug,不是运行时处理 |
一个实用原则:错误枚举的每个变体,都应该能对应调用方代码里的一个分支。如果某个变体从来没有人 match,那它大概率该合并或删掉。
实现上,自定义错误至少要满足两个 trait:Debug(#[derive(Debug)] 即可)和 Display。前者给开发者看,后者给用户看。main 返回 Result 时只要求 Debug,所以下面这段能编译,但输出很难看:
fn main() -> Result<(), Box<dyn std::error::Error>> {
let text = fs::read_to_string("missing.txt")?;
println!("{}", text.len());
Ok(())
}
Error: Os { code: 2, kind: NotFound, message: "系统找不到指定的文件。" }
main 返回 Err 时,运行时会用 Debug 格式打印并给出退出码 1。要输出友好的文案,就得自己 match 后用 eprintln! 打 Display,像前面那样。想让自定义错误也能进 Box<dyn Error>,还需要实现 std::error::Error,并在实现里提供 source() 指回底层错误——这样错误链不会断,排查时能一层层看到根因。
panic 的边界
什么时候可以放心 panic?经验上有四条:
一是测试和示例代码,unwrap 让失败直接可见,比吞掉错误好。二是启动阶段的配置校验——如果配置错了,服务继续跑只会产生更坏的结果,不如立刻崩掉让编排系统重启。三是已经用类型或断言证明过的不变量,比如 split_once 之后 unwrap 结果,因为 split_once 返回 Some 的条件刚刚才检查过。四是原型阶段,先把流程打通,但要在上线前逐个换成 ? 或默认值。
反过来,这些地方不该 panic:处理用户输入、网络 IO、文件读写、任何「失败是正常业务一部分」的路径。服务端最忌讳的是「一个请求的参数不合法,整个进程挂了」——panic 在默认配置下会展开当前线程,多线程服务里只死一个 worker,但如果持有锁或在 Drop 里 panic,后果会扩散。
还有几个运行时的 panic 是「隐式」的,不写 panic! 也会发生:
let v = vec![1, 2, 3];
let i = 5;
println!("{}", v[i]);
thread 'main' panicked at src/main.rs:4:21:
index out of bounds: the len is 3 but the index is 5
下标越界、整数溢出(debug 下)、unwrap 到 None/Err、RefCell 重复可变借用、除零,都是 panic 的常见来源。它们的共同点是:这些操作在类型层面没有留下「可能失败」的痕迹,所以只能在运行时检查。想避免,就用 get(i) 代替 v[i]、用 checked_* 代替算术运算符。
panic 不能穿过 extern "C" 边界。FFI 回调里 panic 会直接 abort 进程,而不是展开。第十篇写 unsafe 和 FFI 时会再提一次:跨语言边界必须用 catch_unwind 拦住,或者干脆保证不 panic。发布构建可以在 Cargo.toml 里把 panic = "abort" 打开,省掉展开表、减小体积,代价是失去 catch_unwind 的能力。多数后端服务用默认的 unwind 更灵活。
现象对照
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
the `?` operator can only be used in a function that returns `Result` or `Option` | 函数返回 (),? 无法提前返回 Err | 改签名加 Result,末尾补 Ok(()) |
`?` couldn't convert the error to `ConfigError` | 缺少 From<底层错误> 实现 | 加 impl From,或在调用处 map_err |
type mismatch resolving `<u16 as FromStr>::Err == ConfigError` | parse()? 的错误类型和返回类型不一致 | 看 expected ... found ... 两端类型,加 map_err 转换 |
called `Result::unwrap()` on an `Err` value: Os { code: 2, ... } | 该路径失败但被当作「不可能失败」 | 追这个值的来源,判断该 ?、默认值还是真的该崩 |
index out of bounds: the len is 3 but the index is 5 | 下标运行时越界,类型不检查长度 | 改用 v.get(i),或先校验长度 |
错误信息只有一句 Error: ...,看不出根因 | main 返回 Err 走 Debug 打印,且错误没链 source() | 手动 eprintln! Display,并检查每层错误是否保留了 source |
| 调用方只能打印错误,没法分支处理 | 错误全被拍平成 String | 按调用方动作重新设计 enum 变体 |
| 服务偶发整体退出,日志只有一行 panic | 某条业务路径 panic,触发了进程终止 | 搜 unwrap/expect/panic!,确认是否在请求处理路径上 |
边界与代价
第一层代价是样板代码。每加一个错误来源,就要加一个变体、一个 From、一段 Display。错误种类上到十几个时,这套手写实现很烦。社区方案是 thiserror(用 derive 生成 Display/From)和 anyhow(应用层用 Box<dyn Error> 加上下文)。引入前先想清楚:如果是库,错误类型是对外 API 的一部分,别用 anyhow 暴露给下游;如果是应用入口,anyhow 的 context() 能省很多事。(这两个 crate 本文未实际引入运行,仅作选型说明。)
第二层代价是错误转换会丢信息。? 里的 From 只保留类型,不保留「当时在做什么」。同一个 io::Error 可能是读配置、写日志、上传文件,日志里只看得到「文件不存在」,不知道是哪一步。解决办法是加上下文:要么手写 map_err(|e| ConfigError::ReadConfig { path, source: e }),要么用 anyhow::Context 的 .context("读取端口配置")。
第三层代价是「每层都包装一次」的噪音。见过四层调用分别定义四种错误,每层都写一遍 From,最后日志里套娃三层 caused by。合理的做法是:模块内部用具体错误,模块边界收敛成一个错误类型,应用入口用统一类型收口。层数不必等于抽象层数。
第四层是 panic 的不可预测性。panic 会跳过正常的错误处理路径,只跑析构。如果此时正在修改共享状态,可能留下半更新的数据。服务里更稳妥的做法是让每个请求的处理函数返回 Result,panic 只留给「真不该发生」的情况,并且用 catch_unwind 在 worker 边界兜底(是否值得兜底取决于框架,actix-web、axum 都自带处理)。
最后,Result 会让签名变长,组合时要用 and_then、map、ok_or 之类的组合子,读起来有门槛。这部分的收益是显式的控制流:看到签名就知道这个函数会不会失败、失败时带什么信息,不需要翻实现。
小结
可恢复的失败用 Result 写进签名,? 负责取值和向上传递,并借 From 做类型转换;不可恢复的、属于程序 bug 的失败用 panic。错误的类型设计按「调用方会怎么处理」划分,而不是按「哪里出错」堆字符串。
判断某个 unwrap 能不能留,就问一句:这里失败时,进程崩掉是合理的吗?答案是「不合理,应该提示用户或重试」,就换成 ? 或 expect 加说明;答案是「确实不该发生,崩了正好暴露 bug」,那就留着,但把原因写进 expect 的参数里。
当天可以自己验证的练习:
- 把开头的
unwrap版本改成?版本,分别用「文件不存在」「内容为 abc」「内容为 70000」三种输入跑一遍,对比退出码和输出。 - 给
ConfigError加一个impl std::error::Error,实现source(),再用Box<dyn Error>包装它,观察 Debug 输出里的错误链。 - 删掉
impl From<io::Error>,读一遍 E0277 的note,确认编译器点名的正是缺失的实现。 - 写一个返回
Option<u8>的函数,用?链式处理两次查找,理解「None 提前返回」和 Result 版本的差别。 - 在一个请求处理函数里故意
unwrap一个不存在的文件,用RUST_BACKTRACE=1跑,看栈里能不能定位到调用点。
下一篇讲集合与迭代器。这一篇的 load 只读了一行配置;真实服务要读几十行、去重、按 key 查找、统计。数据一多就要用 Vec、HashMap 和迭代器,而它们的 API 大量返回 Option 和 Result——get、parse、collect 全都建立在这一篇的机制上。