函数：把边界写清楚，让编译器替你守门

你接手了一个小服务。它从文本配置里读取端口、超时时间和日志级别，然后启动监听。代码不长，线上却有一个很烦人的问题：配置缺字段时，有的地方返回 0，有的地方直接崩溃，还有的地方悄悄使用默认值。调用者看到一个 u16，根本猜不到它是用户真的填了 0，还是解析失败后留下的“暗号”。

这正是函数设计开始发挥作用的地方。函数不只是把几行代码包起来。它的签名要回答几个很实际的问题：你需要交给它什么，它会把什么交还给你，缺少数据算不算正常，失败时谁负责处理，它会不会借走或拿走你的值，以及传进去的回调允许修改多少状态。

Rust 对这些问题很较真。少写一个返回类型、尾表达式多写一个分号、错误类型对不上、返回的引用活得不够久，编译器都会拦住你。刚开始这种严格确实有痛感，尤其当你只是想“先跑起来”时。但换个角度看，编译器是在替 API 的调用者追问那些作者很容易含糊过去的问题。

这一章不会从一串术语开始。我们会一边改造配置 API，一边把函数签名、Option、Result、?、泛型、函数指针、闭包、impl Trait 和生命周期串起来。重点不是背语法，而是学会看见签名背后的设计选择。

先让函数签名说人话

先看一个看似省事的版本：

fn read_port(text: String) -> u16 {
    text.trim().parse().unwrap_or(0)
}

它能编译，也很短，但签名几乎把所有重要信息藏了起来。

调用者必须交出 String 的所有权，哪怕函数只读一眼；返回的 u16 无法区分真实的端口 0 与解析失败；错误原因被直接抹掉；unwrap_or(0) 还把“无效配置”变成了“合法结果”。短不等于边界清楚。

更诚实的第一版可以写成：

use std::num::ParseIntError;
 
fn parse_port(text: &str) -> Result<u16, ParseIntError> {
    text.trim().parse()
}

这四个部分各自承担一件事：

• fn parse_port 给行为起名。
• text: &str 表示只借用一段 UTF-8 文本，不需要调用者放弃所有权。
• -> Result<u16, ParseIntError> 表示成功时得到端口，失败时保留具体解析错误。
• 函数体最后的 text.trim().parse() 是返回表达式。

参数的类型不是装饰。Rust 要求普通函数明确写出每个参数的类型，因为函数本身就是模块之间的检查点。闭包有时能从调用现场推断参数类型，普通函数却不能把契约留给猜测。

参数接收的是值、共享借用还是可变借用

设计参数时，你可以先问一句：这个函数需要“拥有”、只需要“看”，还是需要“改”？

fn normalize_owned(mut text: String) -> String {
    text.make_ascii_lowercase();
    text
}
 
fn count_lines(text: &str) -> usize {
    text.lines().count()
}
 
fn append_newline(text: &mut String) {

normalize_owned 接收 String，表示它可以保留、移动、修改并最终返回这块数据。count_lines 只借用，调用结束后原字符串照常可用。append_newline 需要独占的可变借用，因为它要改调用者持有的字符串。

别为了“避免复制”机械地把所有参数都写成引用。若函数确实要把值存进结构体、发到线程或长期持有，按值接收往往更直接。反过来，一个只读函数若强迫调用者交出 String，就会制造没有必要的移动。好的签名是在所有权意图和调用便利之间做明确选择。

参数模式能解构，但别把签名写成谜语

函数参数位置可以使用模式。例如：

fn area(&(width, height): &(u32, u32)) -> u32 {
    width * height
}
 
fn main() {
    let size = (8, 5);
    assert_eq!(area(&size), 40);
}

这段代码在参数处直接拆开元组。小型、结构稳定的数据这样写很顺手。不过当模式变复杂时，把解构放进函数体通常更容易读，也能给中间值起清楚的名字。语法允许你压缩代码，不代表 API 边界越紧凑越好。

返回类型是调用者能依赖的承诺

没有显式写 -> ... 的函数，返回类型是单元类型 ()。它表示函数主要在做动作，没有要交给调用者的业务值。

fn report_port(port: u16) {
    println!("准备监听端口 {port}");
}

() 也是一个真实的类型和值，不是“什么都不存在”。这点会在编译器报错时出现得很频繁。你本来想返回 u16，尾表达式却被分号变成了语句，编译器常会告诉你“期望 u16，实际得到 ()”。

表达式返回与早退

Rust 的函数体是一个块，而块本身可以产生值。于是最常见的返回方式不是在最后写 return，而是把值留成尾表达式。

fn retry_delay(attempt: u32) -> u64 {
    let capped = attempt.min(6);
    100 * 2_u64.pow(capped)
}
 
fn main() {
    assert_eq!(retry_delay(0), 100);
    assert_eq!(retry_delay(3), 

let capped = ...; 是语句，负责绑定名字；最后的乘法是表达式，产生 u64。函数调用、if、match 和普通代码块也都是表达式，因此它们可以直接成为返回值。

fn log_label(verbose: bool) -> &'static str {
    if verbose {
        "debug"
    } else {
        "info"
    }
}

这里两个分支都要产生 &'static str。若一个分支是 "debug"，另一个分支只执行 println! 并得到 ()，整个 if 就无法形成统一的返回类型。编译器不是在挑格式，它是在阻止调用者面对一个“有时返回字符串，有时没有返回值”的含糊函数。

一个分号为什么能改变类型

下面这段代码不会编译：

fn double(value: u32) -> u32 {
    value * 2;
}

你可能只觉得多了一个无关紧要的符号，编译器看到的却是：value * 2 被当成表达式语句执行，函数块最后没有值，于是得到 ()，而签名承诺了 u32。

修复方式是去掉分号：

fn double(value: u32) -> u32 {
    value * 2
}

这个错误很常见，不用把它理解成 Rust 在考语法细节。编译器其实已经告诉你两个世界没有对上：签名承诺一个数，函数体却把这个数扔掉了。

尾表达式负责正常路径，return 负责及时结束

return 可以从函数任意位置退出。它最适合早退：先把不满足前提的情况挡在门口，再让后面的代码保持一条清楚的主线。

fn validate_port(port: u16) -> Result<u16, &'static str> {
    if port == 0 {
        return Err("端口不能为 0");
    }
 
    if port < 1024 {
        return Err("普通进程不应使用系统保留端口");
    }
 
    Ok(port)
}

如果把所有逻辑塞进多层 if，正常路径会一路向右缩进。早退能把异常条件平铺出来。不过也别把每个小表达式都写成 return。下面两种写法都对，但第二种更符合 Rust 代码的常见节奏：

fn add_tax_a(price: u64) -> u64 {
    return price + price / 10;
}
 
fn add_tax_b(price: u64) -> u64 {
    price + price / 10
}

永不返回的分支也能参与类型统一

panic!、return 和某些无限循环不会产生一个普通值，它们的类型可理解为“这条路不会走到后面”。因此它们能出现在本来需要其他类型的位置。

fn required_name(name: Option<&str>) -> &str {
    match name {
        Some(value) => value,
        None => panic!("调用 required_name 前必须提供名称"),
    }
}

这能编译，但不意味着业务缺失就该 panic!。如果名称缺失是用户输入可能造成的情况，返回 Result 会更合适。panic! 表达的是程序无法合理继续，或者调用方违反了一个本应由程序逻辑保证的前提。把普通失败写成崩溃，只是把 API 设计问题推到了运行时。

Option：没有值也可以是正常答案

假设配置允许省略 timeout_ms。没有这个字段时，程序会沿用上层默认值。这不是故障，也不需要一段错误原因。此时 Option<T> 比哨兵值更贴切：

fn find_setting<'a>(text: &'a str, key: &str) -> Option<&'a str> {
    text.lines().find_map(|line| {
        let (found_key, value) = line.split_once('=')?;

Option<&str> 明确表示只有两种状态：Some 里有借来的文本，None 表示没找到。它没有解释“为什么没找到”的空间，这正是它的语义边界。

如果你用空字符串表示缺失，就会立刻遇到歧义：用户真的写了空值怎么办？如果你返回 0，同样要解释 0 是有效值还是暗号。Option 把这种约定放进类型里，调用者无法假装没看见。

match 最啰嗦，却最能看清全貌

第一次接触 Option 时，先把两条路径写全很有帮助：

fn show_timeout(value: Option<u64>) -> String {
    match value {
        Some(ms) => format!("{ms} 毫秒"),
        None => String::from("沿用默认超时"),
    }
}

当逻辑只有一次简单变换时，可以再换成组合子。不要因为 match 行数多就认为它“不够 Rust”。当每个分支要记录日志、补充上下文或做几步操作时，match 往往比一条很长的方法链更诚实。

map 改里面的值，不改变有没有

fn setting_length(text: &str) -> Option<usize> {
    find_setting(text, "timeout_ms").map(str::len)
}

map 只会在 Some 时调用转换函数，None 原样通过。上例只是演示形状变化，真实解析当然不能拿字符串长度当超时。

一个更实际的组合是先查找，再尝试解析：

fn optional_timeout_lossy(text: &str) -> Option<u64> {
    find_setting(text, "timeout_ms")
        .and_then(|value| value.parse::<u64>().ok())
}

这里必须用 and_then，因为闭包本身也返回 Option<u64>。若使用 map，结果会变成 Option<Option<u64>>：外层表示字段是否存在，内层表示解析是否成功。and_then 把两个“可能没有”压成一层。

不过这段 API 也暴露了一个设计损失：字段不存在和字段写错都会得到 None。如果调用者需要区分这两件事，就不应该过早调用 .ok() 丢弃解析错误。稍后我们会用 Result<Option<u64>, E> 保存三种状态。

filter 保留满足条件的 Some

fn nonzero_timeout(value: Option<u64>) -> Option<u64> {
    value.filter(|ms| *ms > 0)
}

filter 不会把里面的 u64 变成别的类型。它只是让 Some 经过一道条件：通过就保留，没通过就变成 None。

默认值要分清立即计算和需要时计算

fn timeout_or_default(value: Option<u64>) -> u64 {
    value.unwrap_or(3000)
}

如果默认值只是一个便宜的常量，unwrap_or 很清楚。若默认值需要读取文件、分配字符串或进行其他计算，使用带闭包的惰性版本：

fn display_name(configured: Option<String>) -> String {
    configured.unwrap_or_else(|| {
        String::from("未命名服务")
    })
}

unwrap_or(expensive()) 会先计算参数，再决定用不用；unwrap_or_else(|| expensive()) 只在 None 时运行闭包。它们不是审美差异，而是求值时机不同。

Option 不是把错误藏起来的垃圾桶

.ok() 很方便，它能把 Result<T, E> 变成 Option<T>。代价也很明确：错误值 E 被丢掉。搜索缓存时“不命中”可能只需要 None；解析用户配置时，把“不是整数”的原因抹掉通常会让排查更难。

Result：失败是返回值，不是意外插曲

端口字段与超时不同：服务必须有一个合法端口才能启动。缺字段、格式错误和范围不合适都值得说明原因。Result<T, E> 表示成功得到 T，失败得到 E。

先定义一组贴近领域的错误：

use std::num::ParseIntError;
 
#[derive(Debug)]
enum ConfigError {
    Missing(&'static str),
    InvalidNumber {
        key: &'static str,
        source: ParseIntError,
    },
    OutOfRange {
        key: &'static

调用者不必猜一个数字的含义：

fn main() {
    let config = "port = 8080";
 
    match required_port(config) {
        Ok(port) => println!("监听端口 {port}"),
        Err(error) => eprintln!("配置不可用：{error:?}"),
    }
}

错误枚举看起来比 String 麻烦。它也确实要多写一些代码。但调用者可以可靠地区分缺字段、数字格式错误和范围错误，测试不需要匹配文案，后续还可以为不同错误决定不同恢复策略。若这是一次性脚本，String 可能够用；若这是库的公开 API，结构化错误通常更耐用。

map 与 map_err 各管一条轨道

Result 可以想成两条轨道：Ok 是正常轨道，Err 是失败轨道。map 只变换成功值，map_err 只变换错误。

fn timeout_seconds(text: &str) -> Result<u64, ConfigError> {
    let raw = find_setting(text, "timeout_ms")
        .ok_or(ConfigError::Missing("timeout_ms"))?;
 
    raw.parse::<u64>()
        .map(|ms

如果解析失败，map(|ms| ...) 不会执行；如果解析成功，map_err(...) 不会碰成功值。这种“只改一侧”的能力很适合在层与层之间调整形状。

and_then 串联下一步也可能失败的操作

fn checked_timeout(ms: u64) -> Result<u64, ConfigError> {
    if (100..=60_000).contains(&ms) {
        Ok(ms)
    } else {
        Err(ConfigError::OutOfRange {
            key: "timeout_ms",
            value: ms,

这条链能工作，但读起来已经需要在脑中追踪三次类型变化。改用几个局部变量和 ? 往往更清楚：

fn required_timeout_clear(text: &str) -> Result<u64, ConfigError> {
    let raw = find_setting(text, "timeout_ms")
        .ok_or(ConfigError::Missing("timeout_ms"))?;
 
    let ms = raw.parse::<u64>().map_err

组合子不是“高级写法”，match 也不是“初学者写法”。判断标准应该是错误上下文是否清楚、类型变化是否容易跟上。链条一旦需要复杂闭包、重复缩进或临时日志，就拆开。

unwrap 与 expect 是明确选择崩溃

unwrap() 在 Ok 时取出值，在 Err 时触发 panic。expect("...") 同样会 panic，只是附带你写的上下文。

测试代码、教学中的固定数据、程序启动时不可恢复的不变量，偶尔适合使用它们。处理网络输入、用户配置、文件内容时，unwrap 常常等于“我决定让一次可预期失败结束整个线程或进程”。

这不是说生产代码里绝对不能出现 expect。如果前面的逻辑已经保证索引存在，且这个保证被破坏代表程序自身有 bug，expect 能把不变量写出来。关键是你要能解释为什么这条失败路径无法恢复，而不是因为处理错误多写了几行。

Option 与 Result 之间保留三种状态

配置里的可选超时很有代表性：

• 没写字段：正常，使用默认值。
• 写了合法数字：采用这个值。
• 写了但无法解析：配置错误，不能悄悄当成没写。

这三种状态最适合 Result<Option<u64>, ConfigError>：

fn optional_timeout_checked(
    text: &str,
) -> Result<Option<u64>, ConfigError> {
    let Some(raw) = find_setting(text, "timeout_ms") else {
        return Ok(None);
    };
 
    let ms = raw.parse::<u64

这种返回类型第一次看有点绕。你可以从外向内读：整个操作可能失败；若没失败，字段可能存在，也可能不存在。

ok_or 与 ok_or_else 给 None 补上错误

当缺失从“正常情况”变成“必须说明的失败”时，使用 ok_or：

fn required_host(text: &str) -> Result<&str, ConfigError> {
    find_setting(text, "host")
        .ok_or(ConfigError::Missing("host"))
}

如果构造错误很贵，或需要分配一段详细信息，用 ok_or_else 让错误只在 None 时创建。它与 ok_or 的差别和 unwrap_or_else 类似：一个立即求值，一个按需调用闭包。

transpose 把嵌套翻到更好处理的一面

有时组合子自然产生 Option<Result<T, E>>：

fn optional_workers(
    text: &str,
) -> Result<Option<u16>, ConfigError> {
    find_setting(text, "workers")
        .map(|raw| {
            raw.parse::<u16>().map_err(|source| {

map 后的形状是“字段可能没有；如果有，解析可能失败”。transpose 把它翻成“解析流程可能失败；成功后字段可能没有”。数据没有神奇地变化，只是外层控制权从 Option 换成了 Result，这样调用方就能直接使用 ?。

反方向也存在类似需求。例如批量处理若只关心成功项，可以显式使用 .ok() 丢掉错误，但最好把这个信息损失写在容易看见的位置。只要错误可能影响业务判断，就别为了得到一条漂亮的方法链而把它吞掉。

问号运算符：让失败沿着签名规定的出口离开

? 常被口语化地解释成“遇到错误就返回”。这个直觉够你开始写代码，但它还有两件值得弄明白的事：成功时它会拆出里面的值，失败时它返回的是与当前函数兼容的失败形状，而且错误类型可能在离开前发生转换。

先把一段 ? 展开：

fn parse_workers(text: &str) -> Result<u16, ParseIntError> {
    let workers = text.parse::<u16>()?;
    Ok(workers)
}

它的控制流大致相当于：

fn parse_workers_expanded(
    text: &str,
) -> Result<u16, ParseIntError> {
    let workers = match text.parse::<u16>() {
        Ok(value) => value,
        Err(error) => return Err(error),
    };
 
    Ok(workers)
}

所以 ? 不是忽略错误，也不是抛出一个脱离类型系统的异常。它只是把重复的“成功取值，失败早退”交给语言处理。

下面的实验把 Result、Option 和不同返回类型放在同一张控制流图里。你可以切换输入，观察 ? 到底在哪一步取值、转换或提前离开函数。

为什么在返回空元组的函数里不能随便写问号

下面的代码不会编译：

use std::fs;
 
fn load_banner() {
    let _text = fs::read_to_string("banner.txt")?;
}

read_to_string 的失败出口是 Result 的错误，而 load_banner 的出口是 ()。编译器会提到当前返回类型无法接收这个残余失败，并提醒你考虑返回 Result 或自己处理错误。

一种修复是让签名承认失败：

use std::{fs, io};
 
fn load_banner() -> Result<String, io::Error> {
    let text = fs::read_to_string("banner.txt")?;
    Ok(text)
}

另一种修复是在本层决定如何恢复：

use std::fs;
 
fn load_banner_or_default() -> String {
    fs::read_to_string("banner.txt")
        .unwrap_or_else(|_| String::from("欢迎"))
}

应该选哪一种，取决于这一层是否真的知道如何恢复。底层库通常应该把错误交给上层；命令行入口或 HTTP 处理器更接近用户，往往适合在这里转成提示、状态码或默认策略。

错误类型不同，问号为什么有时仍然能通过

假设一个函数既读文件又解析端口：

use std::{
    fs,
    io,
    num::ParseIntError,
};
 
#[derive(Debug)]
enum LoadError {
    Io(io::Error),
    Port(ParseIntError),
}
 
impl From<io::Error> for LoadError {
    fn from(error

read_to_string 返回 io::Error，parse 返回 ParseIntError，当前函数却返回 LoadError。之所以两个 ? 都能用，是因为我们提供了从底层错误到上层错误的 From 转换。

你可以把编译器的工作想成一个出门检查：失败值准备从函数离开时，当前函数的返回类型能不能接住它？标准库用 FromResidual 描述“这种失败残余能否变成当前返回容器”，而 Result 的常见实现会借助 From 转换错误。日常业务代码里，你通常实现 From 或使用 map_err，不需要自己碰实验性的底层机制。

如果没有对应转换，编译器不会凭感觉把两种错误揉在一起。它会指出 ? 无法把某个错误转成函数声明的错误。这时你有三个常见选择：

• 为领域错误实现合理的 From。
• 在调用处用 map_err 补充字段名、路径或操作上下文。
• 修改函数返回的错误类型，让它准确覆盖可能的失败。

不要为“让 ? 能过”就把所有错误都转成同一句字符串。转换的目的，是让上层得到更合适的语义。

Option 上的问号只沿着 None 早退

fn first_word(text: &str) -> Option<&str> {
    let end = text.find(char::is_whitespace)?;
    Some(&text[..end])
}

找到位置时，? 取出 usize；找不到时，函数直接返回 None。但 Option 的 ? 不能直接从返回 Result 的函数中溜出去：

// 这段代码不能编译：
// fn required_word(text: &str) -> Result<&str, &'static str> {
//     let end = text.find(char::is_whitespace)?;
//     Ok(&text[..end])
// }

None 没有错误信息，编译器不知道该替你造一个什么 Err。先用 ok_or 明确补上语义：

fn required_word(text: &str) -> Result<&str, &'static str> {
    let end = text
        .find(char::is_whitespace)
        .ok_or("文本里没有分隔符")?;
 
    Ok(&text[..end])
}

泛型与 trait bound：只索取函数真正需要的能力

配置加载器最初只从文件读文本，后来测试希望从内存字符串读取，命令行版本又希望从标准输入读取。如果函数参数固定成 File，每加一种来源就要再包一层。

泛型允许你不写死具体类型，而是说明函数需要什么能力：

use std::io::{self, Read};
 
fn read_all<R>(mut reader: R) -> io::Result<String>
where
    R: Read,
{
    let mut text = String::new();
    reader.read_to_string

函数不关心 R 是文件、网络流还是内存缓冲区。它只要求 R: Read，因此函数体可以调用 Read 提供的方法。

这就是 trait bound 的实际意义：它既是给调用者的门槛，也是给函数体的工具清单。没有声明 Display，泛型函数就不能假设 T 能格式化；没有声明 Ord，就不能假设两个 T 可以全序比较。

下面的工作台允许你给泛型函数增删约束，并立即比较哪些调用能够通过。试着从最宽松的签名开始，只在函数体真正需要某项能力时加入对应 bound。

先写具体类型，再在重复出现时抽象

泛型很容易让人兴奋，然后把一个只处理 &str 的函数写出五个类型参数。抽象本身也有成本：签名更长、错误信息更复杂、编译时间增加，读者还要推断每个参数的关系。

更稳妥的节奏是先写清楚具体版本。等你真的出现两个或更多调用场景，并且它们共享同一组能力时，再把差异提成泛型。泛型应该消除真实重复，不是预付未来可能用不到的复杂度。

bound 写在尖括号还是 where 里

简单约束可以紧跟类型参数：

use std::fmt::Display;
 
fn label<T: Display>(value: T) -> String {
    format!("配置值：{value}")
}

约束一多，where 更容易扫描：

use std::fmt::{Debug, Display};
 
fn describe_pair<T, U>(left: &T, right: &U) -> String
where
    T: Display + Debug,
    U: Display,
{
    format!("左侧 {left}，右侧 {right}")

两种写法表达的能力相同。where 不是更强的语法，只是能把参数列表和能力清单分开。尤其当约束落在组合类型上时，它更自然：

fn clone_first<T>(items: &[T]) -> Option<T>
where
    T: Clone,
{
    items.first().cloned()
}

别为了返回值随手加 Copy

一个常见的“让编译器闭嘴”方案是给类型加 Copy：

fn larger_copy<T>(left: T, right: T) -> T
where
    T: Ord + Copy,
{
    if left >= right { left } else { right }
}

它对整数很好用，却拒绝 String，因为 String 不能按位复制。其实比较时并不需要复制两个值。按值接收后，我们可以比较借用，再移动选中的那个：

fn larger<T>(left: T, right: T) -> T
where
    T: Ord,
{
    if left >= right { left } else { right }
}
 
fn main() {
    let winner = larger(
        String::from("alpha"),
        String::

如果调用者还要保留两个原值，API 可以接收并返回引用：

fn larger_ref<'a, T>(left: &'a T, right: &'a T) -> &'a T
where
    T: Ord,
{
    if left >= right { left } else { right }
}

这三个签名表达了三种不同的所有权策略。Copy 不是一个通用的“修复泛型”按钮。

多个约束之间有时是在表达类型关系

fn total<I>(values: I) -> i64
where
    I: IntoIterator<Item = i64>,
{
    values.into_iter().sum()
}
 
fn main() {
    assert_eq!(total([10, 20, 30]), 60);

IntoIterator<Item = i64> 不只是说 I 能迭代，还把迭代元素固定为 i64。关联类型约束经常比“实现某个 trait”更有信息量，因为函数真正依赖的是能力和输出之间的关系。

函数项与函数指针：同样能调用，不代表类型相同

当你写下函数名而没有调用它时，得到的不是“一个模糊的可调用对象”，而是一个函数项。每个函数项都有自己独特、无法直接写出的类型，通常不占运行时存储，因为编译器已经知道你指的是哪个函数。

fn trim_value(value: &str) -> &str {
    value.trim()
}
 
fn main() {
    let operation = trim_value;
    assert_eq!(operation("  rust  "), "rust");
}

这里 operation 可以调用。编译器知道它就是 trim_value，因此没有必要在变量里额外存一个地址。

两个签名相同的函数仍是两个函数项类型

fn add_one(value: i32) -> i32 {
    value + 1
}
 
fn double(value: i32) -> i32 {
    value * 2
}
 
fn same_type<F>(_left: F, _right: F) {}
 
fn main() {
    // 不能编译：add_one 和 double 是不同的函数项类型

same_type 要求两个参数都是同一个 F。虽然两个函数签名相同，它们的身份不同，所以函数项类型也不同。编译器通常会在错误里把类型显示成类似 fn(i32) -> i32 {add_one} 的形式，花括号里的名字就是线索。

需要把不同函数当成同一种值存放时，显式使用函数指针：

fn add_one(value: i32) -> i32 {
    value + 1
}
 
fn double(value: i32) -> i32 {
    value * 2
}
 
fn apply_all(
    start: i32,
    operations: &[fn(i32) ->

函数项会被转换为相同签名的 fn(i32) -> i32。函数指针里存着可在运行时选择的函数地址，调用时需要一次间接跳转，但它结构简单、可复制，也很适合 C 接口或只接受普通函数的回调表。

fn 与 Fn 不只是大小写差别

fn(i32) -> i32 是函数指针类型。Fn(i32) -> i32 是闭包调用 trait，描述“这个值能以共享借用方式被调用”。

函数项和安全的 Rust ABI 函数指针通常能满足 Fn、FnMut、FnOnce 约束，所以接受泛型回调的 API 也能接普通函数：

fn transform<F>(value: i32, operation: F) -> i32
where
    F: Fn(i32) -> i32,
{
    operation(value)
}
 
fn square(value: i32) -> i32 {
    value * value
}
 
fn main

反过来不成立：捕获环境的闭包不能变成普通函数指针，因为函数指针没有地方存捕获的数据。只有不捕获环境的非异步闭包，才可以转换为匹配签名的函数指针。

闭包：把代码和现场一起交给函数

配置加载器需要允许调用者检查每个键。如果只接受函数指针，回调无法自然地带上调用现场的前缀、计数器或白名单。闭包解决的就是这个问题：它不只是一段可调用代码，还可能携带从周围环境捕获的状态。

fn visit_keys<F>(text: &str, mut visitor: F)
where
    F: FnMut(&str),
{
    for line in text.lines() {
        if let Some((key, _)) = line.split_once('=') {
            visitor(key

闭包修改了外面的 count，所以 visit_keys 必须接受 FnMut，参数本身也要写成 mut visitor 才能反复调用。

捕获方式与调用 trait 是两道不同的问题

这是闭包最容易被讲错的地方。

捕获方式回答“闭包怎样保存外部变量”：共享借用、可变借用，或按值拿进来。调用 trait 回答“调用闭包时需要怎样访问闭包自身”：共享借用的 Fn、可变借用的 FnMut，或消费闭包的 FnOnce。

编译器会根据闭包体如何使用捕获值，选择足够用的捕获方式：

fn main() {
    let prefix = String::from("[config]");
    let show = || println!("{prefix} 已加载");
    show();
    show();
}

show 只读取 prefix，通常以共享借用捕获，并实现 Fn。

fn main() {
    let mut count = 0;
    let mut next = || {
        count += 1;
        count
    };
 
    assert_eq!(next(), 1);
    assert_eq!(next(), 2);
}

next 修改捕获值，需要可变借用，因此至少需要 FnMut。

fn main() {
    let message = String::from("只发送一次");
    let send = || {
        drop(message);
    };
 
    send();
    // send(); // 不能再次调用，message 已从闭包中移出
}

send 在调用时把 message 移出并消费掉，只能满足 FnOnce。

所有闭包都实现 FnOnce，因为至少可以尝试通过拿走闭包自身来调用一次；不移出捕获值的闭包还实现 FnMut；既不修改也不移出的闭包进一步实现 Fn。因此接受 FnOnce 的 API 最宽松，代价是它只能保证调用一次。接受 Fn 的 API 对回调要求最严格，但可以通过共享引用反复调用。

你可以在下面的实验里切换共享借用、可变借用、按值捕获和移出操作。重点观察：move 决定值怎样进入闭包，调用 trait 则由闭包体怎样使用捕获值决定。

move 只决定捕获进闭包，不决定只能调用一次

下面的闭包使用 move，却仍然可以多次调用：

fn main() {
    let prefix = String::from("[worker]");
 
    let show = move || {
        println!("{prefix} 正在运行");
    };
 
    show();
    show();
}

move 把 prefix 的所有权移进闭包，让闭包可以脱离原作用域存在。但闭包体只是读取它，没有在调用时把它移出去，所以闭包仍可实现 Fn。

这一区分在多线程代码里很重要。线程常要求闭包拥有捕获的数据，于是你会频繁看到 move；这不等于线程闭包天然是 FnOnce。真正决定调用 trait 的，是闭包体会不会修改或移出捕获字段。

API 应该索取最弱的调用能力

如果回调只会调用一次，优先接受 FnOnce：

fn with_config<F, R>(text: String, action: F) -> R
where
    F: FnOnce(String) -> R,
{
    action(text)
}

它允许调用者在闭包中消费捕获值，适用范围最大。

如果要多次调用且允许回调积累状态，接受 FnMut：

fn retry<F, T, E>(
    attempts: usize,
    mut operation: F,
) -> Result<T, E>
where
    F: FnMut() -> Result<T, E>,
{
    assert!(attempts > 0);

只有当你确实需要通过共享引用反复调用，或明确保证不修改闭包状态时，才要求 Fn。约束写得越强，调用者能传入的闭包越少。

每个闭包表达式也有独特类型

即使两个闭包长得一模一样，它们仍是不同的匿名类型：

fn main() {
    let add_one = |n: i32| n + 1;
    let also_add_one = |n: i32| n + 1;
 
    // 下面不能直接组成同类型数组：
    // let operations = [add_one, also_add_one];
}

不捕获环境时，可以把它们转成函数指针：

fn main() {
    let operations: [fn(i32) -> i32; 2] = [
        |n| n + 1,
        |n| n * 2,
    ];
 
    assert_eq!(operations[0](10), 11);
}

若闭包捕获了不同环境，又要把它们放进同一个集合，常见方案是 Box<dyn Fn(...)>。这会引入动态分发，通常也伴随堆分配。它换来的好处是运行时异构：不同具体闭包类型可以共用一个容器。静态泛型更容易优化，动态对象更灵活，选哪个取决于你是否真的需要“多种回调放在一起”。

impl Trait：隐藏具体类型，但不能隐藏逻辑矛盾

impl Trait 最常见于参数和返回值，两个位置看起来相似，控制权却不同。

参数位置是匿名泛型

fn sum_values(values: impl IntoIterator<Item = i64>) -> i64 {
    values.into_iter().sum()
}

调用者选择传入的具体类型，只要它能产生 i64。函数会针对具体类型进行静态检查。

它与命名泛型很接近：

fn sum_values_named<I>(values: I) -> i64
where
    I: IntoIterator<Item = i64>,
{
    values.into_iter().sum()
}

什么时候需要给类型参数起名？当同一个类型要在签名多个位置建立关系时。

use std::fmt::Display;
 
fn show_two(
    left: impl Display,
    right: impl Display,
) -> String {
    format!("{left} / {right}")
}

两个 impl Display 是两个独立的匿名参数，所以 left 可以是整数，right 可以是字符串。

如果要求两者必须是同一个具体类型，就要用命名泛型：

use std::fmt::Display;
 
fn show_same<T>(left: T, right: T) -> String
where
    T: Display,
{
    format!("{left} / {right}")
}

把公开函数从命名泛型改成参数位置的 impl Trait 也不一定是无害重构。调用者原本可能显式写了泛型实参，而匿名参数改变了可显式指定的泛型列表。库 API 要把这看成签名变化。

返回位置由函数选择唯一的隐藏类型

迭代器适配器的具体类型又长又脆弱，暴露它会让实现细节漏进 API：

fn setting_keys(
    text: &str,
) -> impl Iterator<Item = &str> {
    text.lines().filter_map(|line| {
        line.split_once('=')
            .map(|(key, _)| key.trim

返回 impl Iterator<Item = &str> 的意思是：函数作者选择一个具体迭代器类型，调用者不知道它的名字，但可以依赖它实现 Iterator。这不是“运行时随便返回任何迭代器”，隐藏类型在编译期仍然是确定的。

为什么不同分支不能各返回一种实现

下面的直觉很自然，却不能编译：

// 不能编译：两个分支的具体迭代器类型不同
// fn numbers(filtered: bool)
//     -> impl Iterator<Item = i32>
// {
//     if filtered {
//         (0..10).filter(|n| n % 2 == 0)
//     } else {
//         0..10
//     }
// }

一个分支是 Filter<Range<_>, _>，另一个分支是 Range<_>。它们都实现 Iterator，但返回位置的 impl Trait 要求所有路径解析到同一个具体类型。编译器必须为返回值确定布局、析构方式和调用实现，不能只凭“它们都会 next”就把两个布局当成一个。

如果差异只是“是否过滤”，可以把分支移进同一个适配器，让外层类型统一：

fn numbers(
    filtered: bool,
) -> impl Iterator<Item = i32> {
    (0..10).filter(move |n| {
        !filtered || n % 2 == 0
    })
}

如果两条流水线真的完全不同，可以返回 trait 对象：

fn numbers_boxed(
    filtered: bool,
) -> Box<dyn Iterator<Item = i32>> {
    if filtered {
        Box::new((0..10).filter(|n| n % 2 == 0))
    } else {
        Box

Box<dyn Iterator<...>> 允许运行时选择不同具体类型，代价是堆分配和动态分发。另一种方案是自己定义枚举，把两种迭代器作为变体，并为枚举实现 Iterator；代码更多，但保留静态分发。这里没有永远正确的方案：热点路径可能在意分配，普通业务代码可能更在意简单和可维护。

返回 impl Fn 很适合制造闭包

闭包的具体类型无法直接写出，impl Fn 正好能隐藏它：

fn has_prefix(prefix: String) -> impl Fn(&str) -> bool {
    move |value| value.starts_with(&prefix)
}
 
fn main() {
    let is_api = has_prefix(String::from("/api/"));
    assert!(

这里返回的隐藏类型是某一个确定闭包类型。若函数根据运行时分支返回两个不同闭包，同样会撞上“具体类型必须相同”的限制；那时可以统一闭包结构，或改用 Box<dyn Fn(...)>。

生命周期边界：返回借用时要说清它跟谁走

函数返回拥有所有权的 String 时，值可以独立于输入继续存在。返回 &str 时，调用者拿到的只是借用，签名必须说明它不能活过哪一份输入。

回到 find_setting：

fn find_setting<'a>(
    text: &'a str,
    key: &str,
) -> Option<&'a str> {
    text.lines().find_map(|line| {
        let (found_key, value) = line.split_once(

生命周期 'a 把返回切片与 text 绑在一起，却没有与 key 绑定。原因很具体：返回值切自配置文本，不切自查询键。签名不是在延长引用寿命，而是在描述已经存在的借用关系。

很多简单签名可以省略生命周期：

fn first_line(text: &str) -> &str {
    text.lines().next().unwrap_or("")
}

这里只有一个输入引用，返回引用的来源没有歧义，省略规则能推断出来。输入引用一多，来源可能不清楚：

// 不能编译：返回值可能来自 left，也可能来自 right
// fn longer(left: &str, right: &str) -> &str {
//     if left.len() >= right.len() { left } else { right }
// }

显式说明两者都至少活过同一个 'a：

fn longer<'a>(
    left: &'a str,
    right: &'a str,
) -> &'a str {
    if left.len() >= right.len() {
        left
    } else {
        right
    }
}

这并不强迫两个原始变量寿命完全相同。调用点会选择一个两者共同覆盖的较短范围，返回引用在这个范围内有效。

编译器不允许函数返回局部变量的引用

// 不能编译：result 在函数结束时会被释放
// fn broken_name() -> &str {
//     let result = String::from("service");
//     &result
// }

给它加一个 'static 标注也救不了。生命周期参数不能把局部变量变长，它只描述关系。正确方案是把所有权交出去：

fn owned_name() -> String {
    String::from("service")
}

或者返回真正存放在程序静态数据区的字符串字面量：

fn default_name() -> &'static str {
    "service"
}

'static 常被误解成“这个值会一直占用内存”。对引用而言，它表示引用可以在整个程序期间保持有效，字符串字面量就是典型例子。对泛型边界 T: 'static 而言，它更接近“T 里面不含必须在更短时间内失效的借用”；一个拥有所有权的 String 满足 'static，但它照样可以在今天这个代码块结束时被释放。

返回迭代器时，隐藏类型可能带着输入借用

fn nonempty_lines<'a>(
    text: &'a str,
) -> impl Iterator<Item = &'a str> + 'a {
    text.lines().filter(|line| !line.trim().is_empty

迭代器内部持有对 text 的借用，所以它不能比 text 活得更久。+ 'a 约束隐藏的具体返回类型不能含有短于 'a 的借用，Item = &'a str 则说明产出的每个切片也来自那份文本。

返回位置的 impl Trait 会捕获它实际使用的泛型与生命周期参数，不同 edition 的精确捕获规则存在差异。对普通 API，显式写出与返回项有关的 'a 往往最容易让读者和编译器都看明白。遇到 edition 迁移报错时，应先检查隐藏类型到底捕获了哪些输入，而不是盲目加 'static。

闭包边界里的生命周期也有方向

fn make_key_filter<'a>(
    prefix: &'a str,
) -> impl Fn(&str) -> bool + 'a {
    move |key| key.starts_with(prefix)
}

返回闭包捕获了 prefix 的引用，所以闭包不能活过 'a。move 只把“这个引用值”移进闭包，并没有把引用指向的字符串变成永久数据。

如果把回调送到可能长期运行的线程，API 常要求 F: 'static。这通常迫使闭包按值拥有数据，或者只捕获真正的静态引用。面对“borrowed data escapes”一类错误时，先找哪一个引用被闭包带出了原作用域，再决定克隆所有权、缩短任务范围，还是重新设计接口。给所有东西加 'static 往往只是把真正的所有权问题藏得更深。

高阶生命周期表达每次调用都借用自己的输入

有些回调不是绑定某一个固定生命周期，而是要对任意一次调用收到的借用都成立。例如，一个回调接收短暂的 &str，并把同一份切片返回：

fn apply_to_line<F>(line: &str, operation: F) -> &str
where
    F: for<'a> Fn(&'a str) -> &'a str,
{
    operation(line)
}
 
fn identity(value:

for<'a> 可以读成“对每一个调用者选择的 'a 都成立”。这类写法并不常见，但当编译器指出闭包或函数“实现不够一般”时，它能解释真正缺少的关系：API 需要一个能处理任意短借用的回调，而不是只处理某个预先固定生命周期的回调。

把编译错误当成 API 评审意见

Rust 的函数错误看起来很多：返回类型不匹配、? 不能使用、闭包 trait 不满足、生命周期不够长、两个隐藏类型不相同。它们表面上来自不同语法，背后却常是同一个问题：签名说了一套，实现偷偷做了另一套。

刚接触编译器输出时，你可能会直接跳到最后一行的 help，照着建议改。这样偶尔能过，但容易留下一个更奇怪的签名。更稳的读法是分三步：先看“期望什么、实际是什么”，再找类型从哪里产生，最后才决定修改实现还是修改承诺。

expected 与 found 是一张对账单

看这个函数：

fn load_timeout(text: &str) -> Result<u64, &'static str> {
    let value = text.parse::<u64>();
    Ok(value)
}

编译器会告诉你，Ok 里期望 u64，实际却放进了 Result<u64, ParseIntError>。不要急着在外面再套一层类型。沿着值往回看：parse 本身可能失败，所以 value 还没有成为数字。

如果当前函数确实要把解析失败转成自己的错误，可以先拆出数字：

fn load_timeout(text: &str) -> Result<u64, &'static str> {
    let value = text
        .parse::<u64>()
        .map_err(|_| "超时必须是非负整数")?;
 
    Ok(value)
}

如果当前函数没能力给出有意义的领域错误，也可以把 ParseIntError 保留下来。哪一种更好，不由“哪段代码更短”决定，而由调用者需要哪种失败信息决定。

“期望与实际不一致”也经常揭示嵌套容器。比如你以为自己有 Option<u64>，实际拿到 Option<Result<u64, E>>。编译器没有要求你随便加一个 unwrap；它在提示流程里有两层不确定性，需要你决定哪层控制外部函数。若解析失败必须中止流程，transpose 通常能把 Result 翻到外层。

trait bound 不满足，先问函数体究竟用了什么

假设你写了一个泛型最大值函数：

fn maximum<T>(values: &[T]) -> Option<&T> {
    values.iter().max()
}

编译器会指出 T: Ord 没有得到保证。这里最合理的修复确实是添加 Ord，因为函数体调用 max，而“能建立全序”就是算法真实需要的能力。

但不是每个 trait 错误都该用加约束解决。看另一个版本：

fn debug_value<T>(value: T) {
    println!("{value:?}");
}

你可以添加 T: Debug。如果这个打印只是临时排查日志，删掉打印也许才是正确修复。公开 API 每增加一个 bound，就会排除一批本来可能使用它的类型。编译器只告诉你当前实现需要什么，不会替你判断这个实现细节值不值得成为调用门槛。

这也是为什么“看到方法不存在就疯狂加 trait”很危险。先查清这个方法来自哪个 trait，再问函数的核心职责是否依赖它。如果只为了格式化错误文案加上 Clone + Display + Debug，调用者很可能在替你的实现便利买单。

闭包报 FnOnce 时，找哪一个值被移了出去

下面的处理器想把消息发送两次：

fn run_twice<F>(mut action: F)
where
    F: FnMut(),
{
    action();
    action();
}
 
fn main() {
    let message = String::from("配置已更新");
 
    run_twice(|| {
        drop(message);
    });

编译器会指出闭包只实现 FnOnce，无法满足 FnMut。原因不是 String 被闭包捕获了，而是 drop(message) 在第一次调用时把它从闭包环境中移了出去。第二次调用已经没有消息可用。

修复要根据真实意图选择。如果只是读取消息，就借用或打印它：

fn run_twice<F>(mut action: F)
where
    F: FnMut(),
{
    action();
    action();
}
 
fn main() {
    let message = String::from("配置已更新");
 
    run_twice(|| {
        println!("{message}");

如果业务就是“一次性交出消息”，那就别强迫闭包可重复调用，调用方与 API 都改成 FnOnce。若每次调用都必须得到一份拥有所有权的消息，可以在闭包里克隆，但要承认克隆有分配成本。编译器指出的是所有权事实，业务该选哪条路仍由你决定。

借用逃逸错误在问返回值到底属于谁

一个函数尝试构造临时字符串，再返回切片：

// 不能编译：返回值借用了即将销毁的局部 String
// fn normalized_name(raw: &str) -> &str {
//     let name = raw.trim().to_lowercase();
//     &name
// }

这里不能通过添加生命周期参数解决。局部的 name 会在函数结束时释放，任何指向它的引用都会悬垂。返回拥有所有权的 String 才符合数据流：

fn normalized_name(raw: &str) -> String {
    raw.trim().to_lowercase()
}

另一个常见场景是线程。线程任务可能在当前函数返回后继续运行，因此它不能借用当前栈上的短生命周期数据。使用 move 并把拥有所有权的数据交给线程，是在改变数据归属；仅仅给引用标 'static 并不会创造所有权。

当编译器说借用的数据“逃逸”时，可以按顺序问：返回值或闭包要活多久？它内部借用了谁？被借用者能否覆盖那段时间？如果不能，是应该缩短返回值寿命，还是让结果拥有数据？这三问比反复改生命周期字母有效得多。

错误建议是起点，不是自动修复按钮

编译器的 help 通常很有价值，但它只能基于局部类型信息给建议。例如它可能建议添加借用、增加 bound、使用 mut 或改变返回类型。建议能让当前片段通过，不保证 API 语义适合项目。

如果一个解析函数原本返回 u16，编译器建议你把某个表达式包进 Ok，你还得问错误路径在哪里；如果闭包需要 mut，你要确认状态变化是否符合并发要求；如果建议添加 'static，你要确认调用者是否真的应该交出拥有所有权的数据。

把编译错误当成一场严格的代码评审会更轻松：它负责指出契约冲突，你负责做业务决策。这样编译器不再只是红色终端输出，而是一个会持续追问“这个值到底从哪来、失败到底去哪”的搭档。

组合子、match 与早退该怎么选

Option 和 Result 的方法很多。刚学会 map、and_then、or_else、filter 和 transpose 时，很容易把“没有显式分支”误认为更优雅。结果往往是一条十几行的方法链，里面塞着多层闭包，出错时你自己都要从头推类型。

判断写法时，可以先看每一步是否只做一次简单形状变化。如果是，组合子很清楚；若一个分支包含多项业务动作，match 或局部变量通常更好。

一次简单映射适合 map

把可选端口变成展示文本，是一次纯粹变换：

fn port_label(port: Option<u16>) -> Option<String> {
    port.map(|value| format!(":{value}"))
}

有值就变换，无值就通过。读者不需要展开控制流也能理解。

如果闭包内部开始验证范围、记录日志、修改统计并构造错误，map 这个名字就不足以概括发生的事。把逻辑提成命名函数，或改用显式分支，会让行为更容易测试。

下一步返回同类容器时用 and_then

Option<T>::and_then 的闭包返回另一个 Option<U>，Result<T, E>::and_then 的闭包返回同错误类型的 Result<U, E>。它们的价值在于避免 Option<Option<U>> 或 Result<Result<U, E>, E>。

fn first_valid_port(values: &[&str]) -> Option<u16> {
    values
        .first()
        .and_then(|text| text.parse::<u16>().ok())
        .filter(|port| *port > 0)

这条链每一步都短：取第一个、尝试解析、排除零。代价也清楚：解析错误被主动丢弃。如果函数叫 first_valid_port，只关心有没有合法值，这可能合理；如果它负责诊断配置，丢弃错误就不合理。

错误类型变化时 map_err 比一把抹平更有信息

底层错误常只知道“数字解析失败”，上层知道失败发生在端口字段。map_err 适合在层级上升时补上下文：

fn parse_port_field(raw: &str) -> Result<u16, String> {
    raw.parse::<u16>()
        .map_err(|error| format!("port 字段无效：{error}"))
}

真实库更适合结构化错误，这里用 String 只是突出“补充字段上下文”。不要在最底层就把所有错误写成面向最终用户的长句。底层函数不知道调用环境，过早格式化会让上层难以分类、翻译或映射成状态码。

惰性组合子避免无用工作，也避免意外副作用

unwrap_or、ok_or、or 接收的是已经计算好的值；带 _else 的版本接收闭包，只在需要时调用。

fn choose_name(configured: Option<String>) -> String {
    configured.unwrap_or_else(|| {
        println!("没有名称，正在生成默认值");
        String::from("service")
    })
}

如果写成 unwrap_or(generate_name())，即使 configured 是 Some，生成逻辑也会先执行。默认值只是整数常量时不用在意；默认值会读环境、写日志或分配大对象时，求值时机就是可观察行为。

同样，ok_or(build_error()) 会立即构造错误。若错误包含路径克隆或详细诊断，用 ok_or_else(|| build_error()) 更合适。不要机械地把所有版本都换成 _else，一个简单枚举值用直接版本反而更清楚。

match 适合分支本身有故事的时候

假设加载配置时，文件不存在可以创建模板，权限不足要报错，其他 I/O 错误需要保留：

use std::{
    fs,
    io::{self, ErrorKind},
};
 
fn load_or_template(path: &str) -> io::Result<String> {
    match fs::read_to_string(path) {
        Ok(text) => Ok(text),
        Err(error) if error.

这段代码用 match 比组合子更自然，因为错误分支有不同策略。你能直接看到哪些错误会恢复，哪些会继续返回。若硬写成 or_else，守卫条件和多步动作会缩进到闭包里，未必更易读。

let-else 适合先挡住缺失，再走主流程

let Some(value) = ... else { ... }; 很适合“没有值就早退”的场景：

fn require_nonempty(value: Option<&str>) -> Result<&str, &'static str> {
    let Some(value) = value else {
        return Err("缺少配置值");
    };
 
    if value.trim().is_empty() {
        return Err

它把缺失路径放在入口，后续的 value 已经是普通 &str。如果 None 只需转换成一个错误，ok_or(...)? 更短；如果早退前还要记录指标或清理资源，let-else 更容易承载完整动作。

方法链一旦需要注释类型，就考虑拆开

一个实用检查是：如果你必须在方法链每一行旁边写“现在是 Option<Result<...>>”，说明读者正在替编译器执行太多类型推演。给中间结果起名不会降低抽象程度，反而会暴露每一步的业务含义。

fn parse_optional_port(
    raw: Option<&str>,
) -> Result<Option<u16>, ParseIntError> {
    let parsed = raw.map(str::parse::<u16>);
    parsed.transpose()
}

相比把两步压成一行，这个版本可以在 parsed 上加断点、日志或类型标注。函数的目标是让控制流可信，不是展示你能记住多少组合子。

在项目里给函数分层

真实项目很少只有一个 parse_port。通常会经历“取原始数据、解析类型、校验业务规则、组合配置、执行副作用”几层。如果所有步骤塞进一个大函数，任何一个错误类型或输入来源变化都会牵动整段代码。

把函数按职责分层，并不是为了追求每个函数只有三行，而是让每一层只处理自己真正知道的事情。

查找层只回答有没有原始值

find_setting 只从文本中查找键，返回 Option<&str>。它不判断端口是否必填，也不决定超时默认值。这样同一个查找函数可以服务必填字段和可选字段。

如果查找层直接把缺失写成 ConfigError::Missing，所有字段都会被迫变成必填；如果它擅自使用默认值，上层就无法区分用户配置与系统默认。底层保持较少策略，通常更容易复用。

解析层只负责从文本得到类型

parse_number 把字符串转换成数字，并把底层解析错误包进领域错误。它不应该顺便判断“端口必须大于 1024”，因为这个规则不是数字解析规则。

拆开之后，解析函数可以用于端口、工作线程数和超时值，业务校验则各自表达范围。若以后允许端口 0 表示让操作系统自动分配，只需要修改端口校验，不必碰整数解析。

校验层处理已经有类型的数据

fn validate_timeout(ms: u64) -> Result<u64, &'static str> {
    if ms < 100 {
        return Err("超时不能低于 100 毫秒");
    }
 
    if ms > 60_000 {
        return Err("超时不能超过 60 秒");
    }
 
    Ok(ms)
}

校验函数接收 u64，所以它不用再操心“abc 能否解析”。测试也变得直接：边界值 99、100、60_000、60_001 各自应该得到什么。

有些校验函数成功时只返回 ()，表示原值仍由调用者持有；有些像上面这样把值原样交回，方便接到 ? 后面。选哪一种取决于调用链是否需要移动值，不必为追求统一风格强行固定。

组合层把缺失、解析和校验连接起来

组合层知道字段名、是否必填以及错误上下文，所以适合使用 ok_or、map_err、transpose 和 ?：

fn build_timeout(text: &str) -> Result<Option<u64>, ConfigError> {
    let Some(raw) = find_setting(text, "timeout_ms") else {
        return Ok(None);
    };
 
    let parsed = raw.parse::<u64>().map_err

这层不负责读文件，也不负责打印最终错误。于是它可以在单元测试中直接喂字符串，不需要文件系统夹具。

边界层负责把错误变成用户能理解的结果

命令行入口、HTTP 处理器或任务执行器最接近用户，通常由它们决定记录日志、返回退出码、构造响应或使用备用配置。

底层函数若同时打印错误又返回错误，上层可能重复打印；库代码若直接结束进程，调用者也无法恢复。一个实用原则是：能处理就处理，不能处理就带着上下文向上返回。日志通常放在真正决定“到此为止”的边界，而不是每经过一层就打印一次。

公共函数的错误类型也是兼容性承诺

在应用内部修改错误枚举比较自由，公开库则要更谨慎。调用者可能对错误变体做模式匹配，也可能依赖错误链。随意删除变体、改变字段类型或把结构化错误改成 String，都会影响外部代码。

这不代表第一版必须预测所有未来错误。可以先定义与当前领域匹配的稳定分类，把变化频繁的底层细节放进 source，或把部分错误标记为不鼓励穷举。核心仍是诚实：调用者需要做恢复决策的差异，应在类型中保留；纯诊断细节不一定要变成公共变体。

接受 &str 还是 String 要看数据是否跨过边界

解析函数通常只在调用期间读文本，接收 &str 最方便。配置对象若要独立长期存在，可以在构造时转成 String；若它只在原文本存在期间使用，借用切片能少一次分配。

没有一种形式天然更“高性能”。借用会把生命周期传播到结构体和调用链，增加类型复杂度；拥有值会发生分配或移动，却让对象更容易存储、发送和返回。小字符串配置通常不值得为了省一次分配把整个架构绑在复杂生命周期上。热点解析器处理大量数据时，借用才可能带来实际收益。

泛型边界应停在有复用价值的位置

让 read_all<R: Read> 接受多种读取来源很有价值，因为文件、标准输入和内存缓冲都共享明确能力。把 parse_config 泛化成任意键类型、任意错误构造器、任意字段容器，可能只是把简单业务变成一套小框架。

每个泛型参数都会把一部分选择权交给调用者，也会把更多错误信息暴露给调用者。若只有一种实际类型，先用具体签名；等第二个场景出现，再确认它们共享的到底是行为还是偶然相似的代码。

回调适合反转一个小决策，不适合藏住整个流程

一个函数接受回调，可以让调用者决定过滤规则、重试动作或事件处理。若回调参数多到包含配置、日志器、缓存、数据库连接和错误构造器，函数边界往往已经失去焦点。

回调的 Fn、FnMut、FnOnce 还会把状态和所有权要求传给调用者。只调用一次的构造流程用 FnOnce 很自然；反复重试用 FnMut；并发共享可能要求 Fn + Send + Sync + 'static。这些 bound 每一个都有实际含义，不要复制一串约束后才反推它们为什么存在。

小函数不是目的，可测试的决策点才是

把每行代码提成函数，会让读者不停跳转；把所有逻辑塞进一个函数，又会让错误和所有权搅在一起。比较好的拆分点通常是独立决策：字段是否存在、文本能否解析、范围是否合法、错误是否恢复、回调调用几次。

这些决策能用简单输入输出测试，也能在签名里说清楚。函数长度只是结果，不是规则。一段十五行但只有一个明确职责的函数，往往比五个名字含糊的三行函数更容易维护。

合并代码前做一次签名走查

函数通过编译，不代表边界已经设计好。提交前可以先把实现折起来，只看名字和签名。假设你是第一次调用它，能否判断参数会被拿走、失败是否可能发生、返回引用来自哪里、回调会被调用几次？如果这些问题都要靠阅读函数体才能回答，签名可能把重要策略藏住了。

先看输入。只读文本通常接收 &str，只读集合通常接收切片；函数需要存储或跨线程传递时，再考虑接收拥有所有权的值。接收 &String 或 &Vec<T> 往往把调用者限制得过窄，因为函数真正需要的可能只是字符串切片或元素切片。可变引用则应该对应明确的原地修改，不能只因为“以后也许会改”就提前索取独占访问。

再看输出。返回 bool 很方便，但要确认两种状态是否真的够用。登录校验返回真假也许会丢失“用户不存在、密码错误、账户锁定”等差异；搜索列表时返回 Option<&T> 则很自然。返回数字时检查有没有哨兵值，返回字符串时检查调用者是否还要解析文案才能知道结果类别。

然后看错误。错误类型要与当前层能看到的信息匹配。解析层保留格式错误，业务层补充字段和规则，上层边界再决定展示文案。若一个函数返回 Result<T, String>，问问调用者是否需要分类恢复；若返回一个庞大枚举，也要问这些变体是否真属于同一个抽象层。错误越具体不总是越好，关键是保留调用者会据此做决定的差异。

泛型签名要逐个检查 bound。你应该能指着函数体解释每个 Clone、Send、Sync、'static 为什么存在。解释不出来的约束可能是从别处复制来的，也可能只是某个临时实现造成的。删除多余约束不只是美化签名，它会让更多类型可以调用这个函数，并减少使用者面对的编译障碍。

回调参数还要说明调用方式。函数只调用一次却要求 Fn，会拒绝本来合法的消费型闭包；函数循环调用却只写 FnOnce，实现本身就无法兑现。若回调可能不调用、最多调用一次或遇到成功前调用多次，文档与测试都应覆盖这个事实，因为它会影响捕获状态和副作用。

返回借用时，把每个输出引用沿着实现追到输入。若来源唯一，利用省略规则可以保持简洁；若来源有多个，显式生命周期要准确表达可能关系。不要为了消除错误把所有输入都绑到同一个生命周期，这会让无关参数限制返回值。若返回值来自局部构造，就改成拥有类型，生命周期标注无法挽救即将释放的数据。

最后看调用现场。一个理论上漂亮的函数，如果每次调用都需要连续三次类型标注、手工错误转换和多余克隆，说明便利性成本可能被推给了使用者。反过来，一个接受过于宽泛 trait 的函数也可能让错误信息变得难懂。选两三个真实调用点放在一起审视，比只盯着函数实现更容易发现问题。

这次走查不需要写成庞大的流程表。你只要反复核对五件事：所有权是否准确、缺失是否正常、错误是否保留决策信息、抽象是否来自真实复用、借用是否有清楚来源。函数签名一旦把这五件事说清楚，函数体通常也会跟着变简单。

签名走查最好配上反例测试。正常输入只能证明主路径可用，真正塑造边界的是空字符串、缺少字段、最小值、最大值、重复调用回调以及输入先于返回值离开作用域的场景。对于返回结果的函数，分别测试成功值和每一类可恢复错误；对于可选值，明确测试没有值时不会被误判为失败；对于闭包参数，测试调用次数和状态变化；对于借用返回值，让编译器参与验证它不能越过所有者的作用域。

还有一个容易忽略的问题：函数名字也属于契约。叫 find 的函数返回没有结果通常很自然，叫 require 的函数更像会报告缺失，叫 parse 的函数应该保留格式失败，叫 get_or_default 的函数则明确承诺回退策略。名字不能代替类型，但好名字能让类型的含义更快被读懂。若名字、返回类型和实际行为各说各话，调用者迟早会在错误路径上踩坑。

把这些选择放进一个可用的 API

我们把前面的片段收束成一个配置解析器。目标不是展示最炫的类型，而是让调用者一眼知道哪些值必填、哪些值可选、哪些错误会保留。

use std::num::ParseIntError;
 
#[derive(Debug, PartialEq)]
struct ServerConfig<'a> {
    host: &'a str,
    port: u16,
    timeout_ms: Option<u64>,
}
 
#[derive(Debug)]
enum ConfigError {

这里有几个刻意做出的取舍。

ServerConfig 借用原文本里的 host，避免分配新字符串，所以结构体带生命周期。代价是配置对象不能比输入文本活得更久。如果配置要跨线程长期保存，改成拥有 String 会更省心。

parse_number 使用泛型，但它把错误类型限定为 ParseIntError，因此适合标准整数，不是假装支持所有可解析类型。这个约束看似窄，却准确匹配当前错误枚举。若以后加入布尔值或 IP 地址，应该扩展错误建模，而不是硬塞进现有泛型。

可选超时先得到 Option<Result<u64, ConfigError>>，再用 transpose 变成 Result<Option<u64>, ConfigError>。缺失会保留为 None，写错则成为错误，三种状态没有互相冒充。

错误枚举目前只派生了 Debug，足够示例与测试使用。公开库还会考虑实现 Display 和 Error，并决定哪些内部错误细节适合成为稳定 API。这些都是接口维护成本，不该因为“结构化错误看起来专业”就一次性过度设计。

练习：从编译器反馈倒推签名

下面的练习不要求你一次写对。先预测编译器为什么不同意，再修改签名或实现。Rust 最有用的学习时刻，往往就是错误信息把一个隐含假设翻出来的时候。

修复被分号丢掉的返回值

fn clamp_timeout(value: u64) -> u64 {
    value.clamp(100, 60_000);
}

请先回答：函数体实际得到什么类型？为什么与签名不一致？

fn clamp_timeout(value: u64) -> u64 {
    value.clamp(100, 60_000)
}

区分可选字段与错误字段

实现下面的函数。字段不存在时返回 Ok(None)，字段存在且合法时返回 Ok(Some(value))，字段存在但无法解析时返回解析错误。

use std::num::ParseIntError;
 
fn optional_limit(
    raw: Option<&str>,
) -> Result<Option<u32>, ParseIntError> {
    todo!()
}

use std::num::ParseIntError;
 
fn optional_limit(
    raw: Option<&str>,
) -> Result<Option<u32>, ParseIntError> {
    raw.map(str::parse::<u32>).transpose()
}

选择正确的闭包约束

下面的函数会调用回调三次，回调可能修改自己捕获的计数器。把 ??? 换成最合适的 trait bound，并补全参数上的关键字。

fn repeat<F>(action: F)
where
    F: ???,
{
    action();
    action();
    action();
}

fn repeat<F>(mut action: F)
where
    F: FnMut(),
{
    action();
    action();
    action();
}
 
fn main() {
    let mut count = 0;
    repeat(|| count += 1);

让两个普通函数进入同一个表

下面两个函数签名相同，但直接要求它们拥有同一个泛型类型会失败。请把它们装进一个数组，并逐个调用。

fn trim(value: &str) -> &str {
    value.trim()
}
 
fn first_word(value: &str) -> &str {
    value.split_whitespace().next().unwrap_or("")
}

fn trim(value: &str) -> &str {
    value.trim()
}
 
fn first_word(value: &str) -> &str {
    value.split_whitespace().next().unwrap_or("")
}
 
fn main

修复返回引用的来源歧义

fn choose(
    preferred: &str,
    fallback: &str,
    use_preferred: bool,
) -> &str {
    if use_preferred { preferred } else { fallback }
}

请为输入和返回值补上生命周期。然后思考：如果返回值始终只来自 preferred，还需要把 fallback 绑定到同一个生命周期吗？

fn choose<'a>(
    preferred: &'a str,
    fallback: &'a str,
    use_preferred: bool,
) -> &'a str {
    if use_preferred { preferred } else { fallback }
}

fn choose_preferred

在静态分发与动态分发之间做选择

你要实现 make_transform(debug: bool)：调试模式为每个数字加一，普通模式只保留偶数。两条迭代器流水线的具体类型不同。

请回答：为什么 -> impl Iterator<Item = i32> 的两个分支不能直接返回不同流水线？如果这个函数不在性能热点上，最直接的修复是什么？

fn make_transform(
    debug: bool,
) -> Box<dyn Iterator<Item = i32>> {
    if debug {
        Box::new((0..6).map(|n| n + 1))
    } else {

走到这里，你已经不只是会“写一个函数”了。你可以从调用者角度审视签名：值由谁拥有，缺失是否正常，失败怎样离开，泛型索取哪些能力，回调能否修改或消费状态，返回的借用跟谁一起结束。

下一次编译器告诉你类型不匹配、闭包只实现 FnOnce、隐藏返回类型不统一，或者引用活得不够久时，先别急着往签名上堆约束。把错误当成这位严格搭档的问题：你刚才对 API 做了什么没有写出来的假设？把那个假设说清楚，修复通常就已经完成了一半。