需求:从配置里读一个端口号,允许前后有空格,非法值要给出人能看懂的提示。用其他语言写,可能一行 int(raw) 加个 try/catch 就完了。Rust 里第一版代码会卡在两处:"70000" 解析成 u16 该不该报错?"abc" 呢?返回值用 Option 还是 Result?

这些问题看起来是「选哪个 API」,其实是在做类型设计:你要在类型里表达「可能没有值」还是「可能失败」,调用方必须处理哪种情况,编译器会替你检查。Rust 的类型系统比多数语言严格,换来的就是调用方不会漏掉错误分支。

这篇从一个端口解析出发,讲清基本类型的边界、Option/Result 的用法、match 的穷尽性,以及那些看起来多余、实际能防线上事故的类型约束。

场景走查:从字符串到端口号

先用 Result 版本,因为「解析失败」需要给出原因:

fn parse_port(raw: &str) -> Result<u16, String> {
    raw.trim()
        .parse::<u16>()
        .map_err(|e| format!("端口 {raw:?} 不合法:{e}"))
}

fn main() {
    for raw in ["8080", " 9090 ", "70000", "abc"] {
        match parse_port(raw) {
            Ok(p) => println!("端口 = {p}"),
            Err(e) => println!("错误:{e}"),
        }
    }
}

cargo run 的真实输出:

端口 = 8080
端口 = 9090
错误:端口 "70000" 不合法:number too large to fit in target type
错误:端口 "abc" 不合法:invalid digit found in string

这里有三个类型决定同时生效:u16 把合法范围限定在 0 到 65535,所以 70000 解析失败;Result<u16, String> 让失败带着原因返回,而不是抛异常或返回 -1;trim() 返回 &str,和 parse 的输入类型对得上,中间没有多余分配。

如果换成 Option 版本:

fn parse_port_opt(raw: &str) -> Option<u16> {
    raw.trim().parse().ok()
}

能跑,但调用方只知道「没有值」,不知道是超范围还是格式不对。用于「有这个配置项吗」这类查询是合适的;用于给用户报错就不够。Option 表达缺席,Result 表达失败,这是选型的核心区别。

判断标准其实只有一句话:调用方需不需要知道失败的原因。需要,就用 Result;不需要,只是「有没有」,就用 Option。如果一个函数既可能缺失又可能写错,那它应该返回 Result<Option<T>, E>,或者干脆拆成两个函数,而不是用一个 Option 把两种情况压扁。

整数类型和溢出:debug 和 release 不一样

Rust 的整数类型写得很明确:i8/i16/i32/i64/i128/isize 有符号,u8/u16/u32/u64/u128/usize 无符号,数字就是位宽。isize/usize 跟平台指针宽度一致,索引和长度用它。

溢出行为是最容易踩的坑。默认情况下:

fn main() {
    let mut x: u8 = 255;
    x += 1;
    println!("{x}");
}

用 cargo run(debug profile)跑,程序 panic:

thread 'main' panicked at src/main.rs:3:5:
attempt to add with overflow

用 cargo run --release 跑,输出 0——溢出回绕了,没有任何提示。同一个程序,两种行为,取决于 profile。这不是 bug,是官方的设计:开发期帮你抓溢出,发布期为了性能不做检查。

需要明确语义时,用标准库提供的方法:checked_add 返回 Option,saturating_add 饱和到边界,wrapping_add 明确回绕,overflowing_add 返回值和溢出标志。不要靠「release 下会回绕」这种隐式行为写业务逻辑,它换个编译配置就变了。

类型转换也一样。下面这行不会报错,但结果不是你以为的 300:

let x: u16 = 300;
println!("300 as u8 = {}", x as u8);   // 输出 44

as 是截断转换,只保留低位,不检查范围。审计金额、端口、长度这类数值时,as 用在边界上非常危险。安全做法是用 TryFrom:

let x: u16 = 300;
match u8::try_from(x) {
    Ok(v) => println!("转换成功:{v}"),
    Err(e) => println!("超出范围:{e}"),
}

try_from 失败时返回 TryFromIntError,调用方必须处理。这就是 Rust 类型系统的风格:把「可能失败」放进返回类型,而不是藏在注释里。

Option:把「可能没有」写进类型

Option<T> 只有两个变体:Some(T) 和 None。它替代了其他语言里的 null,区别是 null 可以出现在任何引用里,而 Option 必须显式写在类型上。编译器因此能强制你处理 None。

常用操作,按「安全程度」从高到低:

写法行为什么时候用
match opt { Some(v) => ..., None => ... }两个分支都处理需要给 None 一个明确的业务含义
if let Some(v) = opt { ... }只处理有值的情况没有值时确实什么都不用做
let Some(v) = opt else { return; };没有值就提前返回函数开头做前置条件检查
opt.unwrap_or(default)没有值时用默认值默认值便宜且语义合理
opt.unwrap_or_else(|| ...)惰性计算默认值默认值需要分配或计算
opt.map(|v| ...)有值时转换,保留 Option 外壳链式处理,不想解包
opt.unwrap()没有值直接 panic只在测试或「逻辑上不可能为 None」时用

let else 是 1.65 引入的写法,处理「不满足条件就退出」特别顺手:

fn load_port(raw: Option<&str>) -> u16 {
    let Some(raw) = raw else {
        eprintln!("没有配置端口,使用 8080");
        return 8080;
    };
    raw.trim().parse().unwrap_or(8080)
}

它比嵌套 if let 少一层缩进,也比 match 更直接。注意 else 分支必须发散(return、break、panic! 之类),否则编译器不允许,因为 let Some(...) 之后的代码默认这里一定有值。

unwrap 的 panic 信息只告诉你「called `Option::unwrap()` on a `None` value」,不告诉你是哪条业务假设错了。线上服务里除非你已经证明不可能为 None,否则用 expect("...") 写上原因,或者用 ? 往上抛。别把 unwrap 当成「先跑起来」的快捷键。

match 必须穷尽,不是啰嗦

把上面的 Option 忘了写 None 分支,编译器会直接拒绝:

fn main() {
    let x: Option<i32> = Some(1);
    match x {
        Some(v) => println!("{v}"),
    }
}
error[E0004]: non-exhaustive patterns: `None` not covered
  |
3 |     match x {
  |           ^ pattern `None` not covered
  |
help: ensure that all possible cases are being handled by adding a match arm
      with a wildcard pattern or an explicit pattern as shown
  |
4 ~         Some(v) => println!("{v}"),
5 ~         None => todo!(),

这就是穷尽性检查。它的价值在于:以后你给枚举加了一个变体,所有没处理新变体的 match 都会编译失败,逼你逐个确认,而不是运行时悄悄走到默认分支。动态语言里「加一个枚举值,忘了改某个 switch」是常见事故,Rust 把它变成了编译错误。

模式匹配能做的事远不止判空。常见的几种:

let pair = (3, "beta");

// 解构元组
let (n, name) = pair;

// 匹配范围
match n {
    0 => println!("零"),
    1..=9 => println!("一位数"),
    _ => println!("多位数"),
}

// 带守卫条件
match n {
    x if x % 2 == 0 => println!("{x} 是偶数"),
    x => println!("{x} 是奇数"),
}

// 或模式
match name {
    "alpha" | "beta" => println!("已知名称"),
    _ => println!("未知名称"),
}

_ 是通配符,匹配任何值且不绑定。_x 会绑定但立刻被忽略,两者用途不同。还要注意:match 的分支按顺序匹配,范围重叠时前面的先生效,编译器会提示不可达的分支。

穷尽性检查真正发挥作用的场景,是你自己定义的枚举。假设程序里有一个 Level 枚举,只有 Info、Warn、Error 三个变体,所有 match 都写了三个分支。某天需求要把 Debug 加进来,你改完枚举定义,编译器立刻把所有漏掉 Debug 的 match 列出来,位置精确到行。换成字符串常量或整数码,同样的改动只能靠搜索和人工确认,漏一处的后果通常是线上少打印一类日志,或者统计结果凭空少一截。这也是为什么内部表示尽量用枚举而不是字符串:字符串拼错了编译器不管,枚举拼错了直接编译不过。

如果值来自引用,模式里的绑定默认也是引用。想拿走所有权,需要 match value { ... } 而不是 match &value,或者在模式里用 ref/ref mut(现代写法更推荐直接用 & 解构)。这一条和上一篇的借用规则直接相关,遇到 cannot move out of borrowed content 时,先确认你匹配的是不是引用。

Result 的入口用法

Result<T, E> 也是枚举:Ok(T) 表示成功,Err(E) 表示失败。它和 Option 最大的区别是失败可以带数据——错误码、错误消息、底层 I/O 错误,都能放进去。

入门阶段先记住三件事:

用 ? 提前返回表达式返回 Err 时直接退出当前函数,把错误交给调用方。要求函数返回类型能接受这个错误。
用 map_err 转换错误底层错误不适合直接暴露给上层时,转成自己的错误类型,保留上下文。
不要用 Result 表达「没有」「查不到」用 Option,「查不到且要说明原因」用 Result。两种语义混用会让调用方很困惑。

一个常见的组合:从环境变量读端口,缺失用默认值,存在但非法就报错。

use std::env;

fn port_from_env() -> Result<u16, String> {
    match env::var("PORT") {
        Ok(raw) => raw.trim().parse::<u16>()
            .map_err(|e| format!("PORT={raw:?} 无效:{e}")),
        Err(_) => Ok(8080),
    }
}

这里把「变量不存在」当成正常情况(返回默认值),把「存在但格式错」当成错误。区分这两种情况很重要:前者是配置缺失,后者是配置写错,运维处理方式完全不同。

错误处理的完整用法(自定义错误类型、thiserror、错误链)放到第六篇,这里只需要会用 map_err 和 ?,并知道 ? 不是「忽略错误」,而是「交给上层」。

newtype:用类型挡住「传错参数」

有一种线上事故和逻辑无关,纯粹是参数顺序传错:transfer(from_id, to_id, amount) 三个都是数字,调用方把两个 id 写反了,编译器毫无意见。Rust 的解法是给每种含义包一层独立类型:

struct UserId(u64);
struct OrderId(u64);

fn load_order(user: UserId, order: OrderId) -> String {
    format!("user={} order={}", user.0, order.0)
}

fn main() {
    let user = UserId(42);
    let order = OrderId(1001);
    println!("{}", load_order(user, order));
    // load_order(order, user);  // 编译错误:类型不匹配
}

这叫 newtype 模式。它没有运行时成本(编译后就是一个 u64),但能防住一整类「相邻参数类型相同」的 bug。领域模型里,凡是「数字/字符串但含义不同」的字段,都值得考虑包一层。后面讲结构体和 trait 时会看到,newtype 也是实现自定义 trait 和孤儿规则绕过的常用手段。

代价是写法变啰嗦:取值要 .0,比较要手动实现,JSON 序列化要加 #[serde(transparent)]。所以只在「传错会出事」的边界上用,内部计算不必包。

现象对照

现象真实原因第一步查什么
debug 下 panic,release 下结果莫名其妙整数溢出在 debug 检查、release 回绕搜 + - * 附近是否可能越界,改用 checked_*/saturating_*
数值转换后变小或变负as 截断不检查范围改用 try_from,或确认取值范围后再 as
non-exhaustive patternsmatch 漏了枚举变体看报错点名的变体,补分支;不要第一反应加 _
called `Option::unwrap()` on a `None` value假设有值但实际没有追这个值的来源,确认哪一步可能返回 None,改成 ? 或默认值
mismatched types / expected u16, found u32字面量或函数返回值类型不一致看报错两端的类型,用 try_from 或显式标注转换
cannot infer type泛型参数没有足够信息推断给变量、collect 结果或函数调用加显式类型标注
invalid digit found in stringparse 遇到非数字字符先确认是否该 trim,再检查输入编码和正负号
数值比较结果不对有符号/无符号混用,或类型宽度不同统一类型,必要时用 as 前先做范围断言

边界与代价

类型严格的第一层代价是写起来更慢。一个「可能没有」的值,从函数签名到调用分支,都要显式处理。Option 链一长,代码会显得啰嗦。缓解手段是 ?、map、and_then、unwrap_or_else,但这些也有学习成本,用过头会变成另一种难读。

第二层代价是类型设计本身可能出错。比如把「用户不存在」和「数据库连不上」都塞进同一个 Err(String),调用方就没法区分该重试还是该返回 404。错误类型要按「调用方会怎么处理」来划分,不是按「哪里出错」来堆字符串。这一点第六篇会展开。

第三层代价是 as 的诱惑。它写起来最短,编译器也不拦,但它是 Rust 里少数几个「明显不安全却默认可用」的操作。团队约定里可以直接禁用 as 做数值转换(clippy 有对应 lint),统一走 From/TryFrom。

第四层代价是 Option 嵌套。Option<Option<T>> 通常意味着语义没想清楚:外层表示「有没有配置」,内层表示「配置了但值为空」,这两种「没有」在业务上往往需要不同处理。遇到嵌套就该拆成枚举,而不是继续 flatten。

最后,模式匹配虽然强,但不要让一个 match 分支过多。十几个分支的 match 往往说明这个枚举承担了太多职责,或者该拆成几个类型。可读性比「一个 match 解决所有」更重要。

还有一个和公开 API 有关的细节:如果一个枚举会被别的 crate 匹配,将来加变体就会破坏对方的穷尽 match。标准库和成熟库常用 #[non_exhaustive] 标注这类枚举,告诉外部「以后可能加变体,你的 match 必须留 _ 分支」。代价是外部不能再享受穷尽性检查,收益是库作者可以安全地扩展。自己项目内部的枚举不要加这个标注,穷尽性正是你要的。

小结

Option 表达缺席,Result 表达失败,两者都必须被处理,这是 Rust 类型系统最日常的收益。整数溢出 debug 检查、release 回绕,as 截断不报错,这两处要主动用 checked_* 和 try_from 兜住。

match 的穷尽性不是麻烦,是给你未来的自己留的提醒:枚举加变体时,编译器会把所有需要改的地方列出来。

当天可以自己验证的练习:

  1. 把 parse_port 的返回类型改成 Option<u16>,改写 main 里的 match,比较两种写法丢失了什么信息。
  2. 用 cargo run 和 cargo run --release 各跑一次溢出示例,确认两种行为,然后在 Cargo.toml 里给 release 打开 overflow-checks = true 再试一次。
  3. 写一个函数,参数是 &[&str],用 match 处理 0、1、多个三种长度,确认穷尽性。
  4. 给 UserId 和 OrderId 各加一个方法,再故意把参数顺序写反,看编译器报什么。
  5. 用 let Some(x) = ... else { ... } 改写一段嵌套 if let,比较缩进和可读性。

下一篇讲结构体、枚举与 trait。Option 和 Result 本身就是枚举,理解它们的最好方式是自己定义一个枚举并跟 match 配合;再往上,trait 决定了「哪些类型能做什么」,也是 Rust 泛型和动态分发的入口。