Rust / 系统课时

设计所有权友好的 API

设计所有权友好的 API

一个所有权友好的 Rust API,关键不是“尽量借用”,而是让参数和返回值准确表达数据责任:只读就共享借用,需要原地修改就可变借用,必须接管就按值传入,新建结果则返回拥有值,从而减少无意义的 clone 与生命周期传播。

学习目标

  • 根据数据责任选择 T、&T、&mut T 与拥有型返回值
  • 用借用视图类型降低调用者的转换和复制成本
  • 判断何时应返回引用,何时应返回拥有值以隔离生命周期

先判断谁需要拥有数据

设计签名时先问两个问题:被调用者是否必须把数据保存到调用结束之后,以及操作是否需要修改调用者原来的值。答案基本决定了所有权形态,而不是先写代码再靠 clone 消除编译错误。

形态 调用者发生什么 适合场景
T 所有权转移,原变量通常不能再用 被调用者要保存、拆解或最终消费该值
&T 只产生共享借用 只读取,不需要拥有数据
&mut T 借用期间独占访问 直接修改调用者已有对象
-> T 调用者获得独立拥有值 结果是新数据,或不希望返回值依赖输入生命周期

对于字符串和集合,参数还可以优先接收“借用视图”:只读字符串常用 &str 而不是 &String,只读序列常用 &[T] 而不是 &Vec<T>。这样既能接受拥有型容器,也能接受其中的一部分。

用一个接口组合展示四种选择

下面的程序让不同函数分别承担明确的数据责任:统计标签只借用,添加标签原地修改,规范化函数根据借用输入创建新字符串,最后一个函数明确消费整个 Profile 并取走其中的名字。

rust
#[derive(Debug)]
struct Profile {
    name: String,
    tags: Vec<String>,
}

fn tag_count(profile: &Profile) -> usize {
    profile.tags.len()
}

fn normalize(raw: &str) -> String {
    // 结果是新字符串,因此直接返回拥有值,不把生命周期绑到 raw。
    raw.trim().to_ascii_lowercase()
}

fn add_tag(profile: &mut Profile, raw: &str) {
    let tag = normalize(raw);

    // 只有确实需要修改 Profile 时才申请独占借用。
    if !profile.tags.contains(&tag) {
        profile.tags.push(tag);
    }
}

fn into_name(profile: Profile) -> String {
    // 按值接收表示调用者同意交出整个 Profile。
    profile.name
}

fn main() {
    let mut profile = Profile {
        name: "Alice".to_owned(),
        tags: vec!["rust".to_owned()],
    };

    println!("tag count={}", tag_count(&profile));

    add_tag(&mut profile, "  Borrowing  ");
    println!("tags={:?}", profile.tags);

    let label = normalize("  Ownership API  ");
    println!("normalized={label}");

    // 此处之后 profile 已被消费,但取出的 String 归调用者所有。
    let name = into_name(profile);
    println!("name={name}");
}

预期输出

text
tag count=1
tags=["rust", "borrowing"]
normalized=ownership api
name=Alice

这里没有为了通过借用检查而复制整个 Profile。真正发生的新分配只有规范化字符串和新增标签,这是业务结果本身需要拥有数据,而不是所有权设计失误造成的补丁。

返回引用还是返回拥有值

如果返回值只是输入数据的一部分,而且调用者会在原对象仍然存在时立即读取,返回引用通常最自然,例如从 Profile 中返回 Option<&str>。这种签名会明确告诉调用者:结果不能比 Profile 活得更久。

如果结果需要跨越缓存、任务队列、共享状态借用保护或后续可变操作,返回 String、Vec<T> 等拥有值更稳妥。它可能需要一次有目的的复制或构造,但能把生命周期约束截断在 API 边界,避免公共接口到处携带生命周期参数。

让签名承担约束说明

优先把最小权限写进类型:能用 &T 就不要用 &mut T,能借用就不要无理由接管 T。相反,如果函数确实要保存参数到自身状态中,就应明确取得所有权,而不是接收引用后把生命周期扩散到整个结构体。

最终判断标准不是“借用越多越好”,而是调用者能从签名直接看出数据是否会被消费、是否会被修改,以及返回值是否独立拥有。这样的边界通常也最容易测试、组合和重构。

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

目录与阅读设置

记录一个想法

设计所有权友好的 API

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

登录哪都通