Rust / 系统课时
设计所有权友好的 API
设计所有权友好的 API
一个所有权友好的 Rust API,关键不是“尽量借用”,而是让参数和返回值准确表达数据责任:只读就共享借用,需要原地修改就可变借用,必须接管就按值传入,新建结果则返回拥有值,从而减少无意义的 clone 与生命周期传播。
学习目标
- 根据数据责任选择
T、&T、&mut T与拥有型返回值 - 用借用视图类型降低调用者的转换和复制成本
- 判断何时应返回引用,何时应返回拥有值以隔离生命周期
先判断谁需要拥有数据
设计签名时先问两个问题:被调用者是否必须把数据保存到调用结束之后,以及操作是否需要修改调用者原来的值。答案基本决定了所有权形态,而不是先写代码再靠 clone 消除编译错误。
| 形态 | 调用者发生什么 | 适合场景 |
|---|---|---|
T |
所有权转移,原变量通常不能再用 | 被调用者要保存、拆解或最终消费该值 |
&T |
只产生共享借用 | 只读取,不需要拥有数据 |
&mut T |
借用期间独占访问 | 直接修改调用者已有对象 |
-> T |
调用者获得独立拥有值 | 结果是新数据,或不希望返回值依赖输入生命周期 |
对于字符串和集合,参数还可以优先接收“借用视图”:只读字符串常用 &str 而不是 &String,只读序列常用 &[T] 而不是 &Vec<T>。这样既能接受拥有型容器,也能接受其中的一部分。
用一个接口组合展示四种选择
下面的程序让不同函数分别承担明确的数据责任:统计标签只借用,添加标签原地修改,规范化函数根据借用输入创建新字符串,最后一个函数明确消费整个 Profile 并取走其中的名字。
#[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}");
}预期输出
tag count=1
tags=["rust", "borrowing"]
normalized=ownership api
name=Alice这里没有为了通过借用检查而复制整个 Profile。真正发生的新分配只有规范化字符串和新增标签,这是业务结果本身需要拥有数据,而不是所有权设计失误造成的补丁。
返回引用还是返回拥有值
如果返回值只是输入数据的一部分,而且调用者会在原对象仍然存在时立即读取,返回引用通常最自然,例如从 Profile 中返回 Option<&str>。这种签名会明确告诉调用者:结果不能比 Profile 活得更久。
如果结果需要跨越缓存、任务队列、共享状态借用保护或后续可变操作,返回 String、Vec<T> 等拥有值更稳妥。它可能需要一次有目的的复制或构造,但能把生命周期约束截断在 API 边界,避免公共接口到处携带生命周期参数。
让签名承担约束说明
优先把最小权限写进类型:能用 &T 就不要用 &mut T,能借用就不要无理由接管 T。相反,如果函数确实要保存参数到自身状态中,就应明确取得所有权,而不是接收引用后把生命周期扩散到整个结构体。
最终判断标准不是“借用越多越好”,而是调用者能从签名直接看出数据是否会被消费、是否会被修改,以及返回值是否独立拥有。这样的边界通常也最容易测试、组合和重构。