方法与 impl：把所有权写进 API

你正在给一个下载任务补接口。最初的代码大概是这样的：

struct Download {
    file_name: String,
    received: u64,
    total: u64,
}
 
fn progress(download: &Download) -> f64 {
    if download.total == 0 {
        100.0
    } else {
        download.received as f64 / download.total as f64 * 100.0
    }
}
 
fn receive(download: &mut Download, bytes: u64) {
    download.received = download
        .received
        .saturating_add(bytes)
        .min(download.total);
}

这段代码没有错。问题出现在项目继续长大以后：创建下载任务的函数在一个模块里，更新进度的函数在另一个模块里，校验 total 的逻辑又散在第三个地方。调用者只看见三个公开字段，根本不知道哪些值合法，也不知道一次操作会借用任务、修改任务，还是直接把任务消费掉。

impl 解决的正是这个问题。它不是给结构体“加一点面向对象味道”，而是把一组行为放回它们所属的类型旁边，并让方法签名公开说明所有权变化。看到 &self，你知道对象只是被共享借用；看到 &mut self，你知道调用期间需要独占访问；看到 self，你最好先停半秒，因为调用结束后原值通常就不能再用了。

这章不打算把这些接收者背成三条口诀。我们会从一个 API 为什么难用、为什么被借用检查器拦下开始，再倒推方法应该怎样设计。编译器在这里很像一位严格的接口评审：它不会替你决定产品语义，却会认真追问“这个值现在归谁”“这份引用准备活多久”“两个同名方法到底要调用哪一个”。这些问题刚开始确实烦，尤其当你只是想改一个字段时；但它们也会逼着含糊的 API 变得清楚。

方法和关联函数不是一回事

先把最常见的语法放到一个完整例子里：

#[derive(Debug)]
struct Download {
    file_name: String,
    received: u64,
    total: u64,
}
 
impl Download {
    fn new(file_name: impl Into<String>, total: u64) -> Self {
        Self {
            file_name:

进度：25.0%
rust-book.pdf：已接收 200 字节

impl Download { ... } 里的函数都和 Download 这个类型关联，因此从大类上说，它们都是关联函数。其中，第一项参数名为 self 的关联函数又叫方法，可以用点号调用。progress、receive 和 finish 是方法，new 没有 self 参数，所以它只是关联函数。

调用方式把差别写得很明显：

let mut task = Download::new("archive.zip", 1_000);
 
let p1 = task.progress();
let p2 = Download::progress(&task);
 
assert_eq!(p1, p2);

Download::new(...) 用 :: 从类型的命名空间里找函数，不需要先有一个实例。task.progress() 用点号从接收者出发找方法。第二种写法不是另一套函数机制，它只是帮你处理了接收者，并在需要时尝试自动借用和自动解引用。

在 impl Download 中，Self 就是当前实现的类型 Download。所以 fn new(...) -> Self 与 fn new(...) -> Download 表达的是同一个返回类型。优先写 Self 往往更耐改：类型重命名时，impl 内不必到处替换旧名字；在 trait 里，它还表示“实现这个 trait 的具体类型”。

什么时候应该写普通函数，什么时候应该放进 impl？可以先问一句：这个操作是否天然属于这个类型的词汇。Download::new、task.progress()、task.finish() 读起来都有明确主语。反过来，一个需要同时协调数据库、消息队列和三个领域对象的工作流，硬塞进某个小结构体的方法里，主语就会失真。impl 能组织接口，但它不是把所有函数都吞进去的抽屉。

方法也是模块边界的一部分

把函数移进 impl 不会自动封装字段。真正决定外部能做什么的是可见性：类型可以公开，字段保持私有，再通过公开方法提供受控操作。

mod accounts {
    #[derive(Debug)]
    pub struct Account {
        owner: String,
        balance_cents: i64,
        frozen: bool,
    }
 
    #[derive(Debug, PartialEq, Eq)]
    pub enum WithdrawError {
        Frozen,
        NonPositiveAmount,
        InsufficientFunds

外部模块可以持有 Account，却不能写 account.balance_cents = -100。余额只能通过 deposit 和 withdraw 改变，方法有机会检查冻结状态、正数金额和余额是否充足。freeze 使用 pub(crate)，表示同一个 crate 内的管理流程可以调用，crate 外部用户看不到。可见性不必只有“完全公开”和“完全私有”两档。

getter 不等于机械复制字段

Rust 不会自动生成 getter。你可以让字段和方法同名：account.owner 是字段访问，account.owner() 是方法调用，括号让语法没有歧义。字段私有时，外部只能调用方法。

是否提供 getter 要看调用者是否真的需要这份信息。返回余额可能是合理查询；直接暴露 frozen_mut(&mut self) -> &mut bool 则等于把冻结规则重新交给外部，前面的封装几乎白做。特别是返回 &mut 字段时，调用者能在引用存活期间任意写入，方法退出后你也没有再次校验的机会。

比起给每个字段生成 set_xxx，更值得提供有业务含义的动作。withdraw(amount) 比 set_balance(new_balance) 多表达了失败原因和状态约束；rename(new_name) 可以清理空白并记录修改；mark_delivered(at) 可以同时更新互相关联的时间和状态。方法的价值不在于把赋值换成括号，而在于把一次合法状态变化定义完整。

私有字段会给内部表示留下调整空间

如果公开 balance_cents: i64，调用者会依赖具体字段名和整数单位。以后改成一个 Money 类型，所有结构体字面量和字段访问都要跟着变。若一开始只公开 balance_cents() 与语义操作，内部可以在维持接口含义的前提下重构。

这也不是说所有字段都必须私有。纯数据传输结构、解析器的语法节点或只在小范围内部使用的记录，公开字段可能更直接。关键是判断类型是否在维护规则。如果它声称“任何实例都代表一个合法账户”，就必须控制能创建和修改它的入口；如果它只是“刚从输入读到的一包原始字段”，过早封装反而增加样板。

先看调用之后还要不要这个值

方法设计最实用的起点，不是“这段实现要改几个字段”，而是“调用者接下来还需要怎样使用这个值”。三个常见接收者可以先这样理解：

• &self：借来看一会儿，方法结束后原值仍归调用者。
• &mut self：借来修改一会儿，借用期间其他代码不能同时访问原值。
• self：把整个值交给方法，方法可以拆开、转换或转交其内部资源。

它们的完整写法分别是 self: &Self、self: &mut Self 和 self: Self。缩写很短，承诺却很重。

如果你还在凭感觉选接收者，可以先在这个交互实验里切换“是否修改”“是否转移所有权”等条件，观察推荐签名怎样变化。它适合在继续看借用报错前，先把三个接收者的边界走一遍。

只读查询通常从 &self 开始

如果一个方法只需要观察对象，&self 通常是最宽松的接口。调用者可以连续查询，也可以同时保留多份共享引用：

struct User {
    name: String,
    login_count: u32,
}
 
impl User {
    fn name(&self) -> &str {
        &self.name
    }
 
    fn login_count(&self) -> u32 {
        self.

这里有一个常被轻描淡写、实际很容易卡住的细节：name 返回的 &str 借自 user.name。这个引用不能比 user 活得更久，也会在存活期间维持对 user 的共享借用。

impl User {
    fn record_login(&mut self) {
        self.login_count += 1;
    }
}
 
fn main() {
    let mut user = User {
        name: String::from("小林"),
        login_count: 0,
    };
 
    let

这段代码会被拒绝。name 在最后一行仍要使用，所以共享借用还活着；中间的 record_login 又想独占借用整个 user。编译器不是不知道 record_login 实际只改 login_count，而是方法签名写的是 &mut self，对调用者来说，它有权修改整个 User。接口承诺的权限比当前实现碰了哪个字段更重要。

你可以让共享引用在修改前最后一次使用：

let name = user.name();
println!("{name}");
user.record_login();

也可以明确拿一份独立数据：

let name = user.name().to_owned();
user.record_login();
println!("{name}");

第二种写法多了一次字符串分配，却换来了独立所有权。没有哪个方案永远更好。高频查询、临时展示适合借用；数据需要跨越后续修改、线程边界或原对象生命周期时，拥有自己的 String 往往更省心。API 可以同时提供 name(&self) -> &str 和语义明确的拥有型操作，但别为了“方便”让每次读取都无条件克隆。

修改状态需要 &mut self

&mut self 表示方法在调用期间独占接收者。调用点的绑定通常也要声明为 mut：

#[derive(Debug)]
struct RetryPolicy {
    attempts: u8,
    max_attempts: u8,
}
 
impl RetryPolicy {
    fn record_failure(&mut self) -> bool {
        if self.attempts >= self.max_attempts {
            return false;
        }
 
        self

独占借用不是“只能有一个变量指向它”这么粗糙。更准确地说，在这次可变借用可被使用的范围内，不能再通过其他引用读写同一份受保护的数据。这个限制让 record_failure 不必担心执行到一半，别处同时观察到只更新了一半的状态。

&self 不等于物理上一个字节都不改

共享借用禁止你通过普通字段赋值修改对象，但 Rust 仍有内部可变性工具。比如 Cell 可以在 &self 方法中更新适合按值存取的小数据：

use std::cell::Cell;
 
struct Metrics {
    reads: Cell<u64>,
}
 
impl Metrics {
    fn reads(&self) -> u64 {
        let next = self.reads.get() + 1;
        self

所以，&self 更准确的含义是“共享访问”，不是“绝对不可变”，更不自动等于“可以在线程间安全共享”。Cell 和 RefCell 适合单线程内部可变性，其中 RefCell 把一部分借用检查推迟到运行时，规则违反时会 panic；多线程共享状态通常还要借助锁和相应的线程安全约束。

内部可变性很有用，例如缓存一次昂贵计算、记录不影响业务语义的计数。但它也会隐藏变化。一个看起来只读的方法如果悄悄改变会影响结果的业务状态，调用者会很难推理。不要只因为 &mut self 在调用处不够方便，就把所有字段塞进 RefCell。那相当于把严格负责的编译器请出了会议室，等运行时再来处理冲突。

值很小时，接收 self 也可能只是一次复制

“self 会消费原值”是理解所有权类型时很实用的起点，但还要补上 Copy 的情况。若类型实现 Copy，按值传入方法时会复制一份位模式，调用者手里的原值仍可继续使用：

#[derive(Clone, Copy, Debug)]
struct Point {
    x: i32,
    y: i32,
}
 
impl Point {
    fn translated(self, dx: i32, dy: i32) -> Self {
        Self {
            x: self.

Point { x: 0, y: 0 }
Point { x: 3, y: 4 }

这里的 self 仍然是按值接收，只是调用表达式根据 Copy 规则复制了 origin。对坐标、颜色、短标识符这类小值，self -> Self 能自然表达函数式变换。对持有 String、Vec、文件句柄的类型，按值调用通常会真的移动所有权。API 设计不能只看接收者拼写，还要看类型是否 Copy，以及复制的语义是否合理。

不要仅为了让某个消费者方法“调用后还能用”就给领域类型实现 Copy。Copy 表示隐式逐位复制始终合理，且类型不能实现 Drop。资源所有者、可增长容器和需要唯一身份的对象通常不适合它。

接收者可以比三种缩写更具体

常见教程只列 self、&self、&mut self，日常代码大多也只需要它们。不过接收者还可以写成受支持的显式形式，例如 self: Box<Self>、self: std::sync::Arc<Self> 或和固定地址有关的 self: std::pin::Pin<&mut Self>。

trait Job {
    fn run(self: Box<Self>);
}
 
struct CleanupJob {
    path: String,
}
 
impl Job for CleanupJob {
    fn run(self: Box<Self>) {
        println!("清理 {}", self.path);

Box<Self> 接收者表示方法取得装箱值的所有权，常见于需要按动态类型调用一次性方法的接口。Arc<Self> 可以表达方法接过一份共享所有权，方便把任务继续交给异步或线程工作；Pin<&mut Self> 则用于调用期间不能随意移动的值。

这些写法不是为了显得高级。普通业务对象如果用 &self 就足够，写成复杂接收者只会增加调用和理解成本。只有当“对象存在哪里”“方法是否要接管智能指针”“值能否移动”本身就是协议的一部分时，才值得让接收者承担这些信息。

构造器真正要守住的是不变式

假设你在写一个服务端点：主机名不能为空，端口不能是 0。如果字段全部公开，调用者随时都能绕开你的检查：

下面的工作台把“原始输入、校验步骤、合法对象与失败分支”放在同一条流程里。你可以调整输入，直观看到构造器为什么应该在返回 Self 之前完成检查。

struct Endpoint {
    host: String,
    port: u16,
}
 
let endpoint = Endpoint {
    host: String::new(),
    port: 0,
};

与其让每个方法都先猜“这个对象是不是坏的”，不如在创建时拦住非法状态，并把字段留在类型内部。这样一旦拿到 Endpoint，后续方法就可以依赖它的不变式。

use std::num::NonZeroU16;
 
#[derive(Debug, PartialEq, Eq)]
enum EndpointError {
    EmptyHost,
    ZeroPort,
}
 
#[derive(Debug, PartialEq, Eq)]
struct Endpoint {
    host: Box<str>,
    port: NonZeroU16

api.internal:8080

这里有两层防线。try_new 负责把外部字符串清理并校验；字段中的 NonZeroU16 继续在类型层面记录“端口不为零”。如果以后新增一个修改端口的方法，它也只能接收 NonZeroU16，不容易意外破坏不变式。

new 能不能返回 Result

语言没有禁止 new() -> Result<Self, E>。只是生态中的调用者经常把 new 理解为直接创建，把可能失败的版本命名为 try_new。命名不是法条，关键是同一套 API 要可预测：一眼能看出哪里需要处理错误。

可以按输入语义选择更具体的名字：

• new：最主要、通常直接成功的创建入口。
• try_new：创建时要检查，失败属于正常分支。
• with_capacity：提前指定容量，但仍创建同一种对象。
• from_parts：从已经拆开的部件组装。
• parse 或实现 FromStr：输入是文本表示，格式错误很自然。
• default 或实现 Default：有一个明确、不会让人吃惊的默认值。

From<T> 适合不会失败的转换，因为它也会带来 Into。可能失败的转换更适合 TryFrom<T>。不要为了让调用代码少写一个 ?，在转换失败时偷偷选择一个默认值；也不要在正常的用户输入错误上直接 panic。便利性如果靠吞掉错误换来，问题通常只会被推迟。

构造器不必接受所有字段

一个常见误区是把结构体每个字段都变成 new 的参数，结果构造器像数据库表的插入语句一样长。更好的边界是区分三类信息：

1. 缺少它就无法形成合法对象的必填信息。
2. 有稳定默认值的可选配置。
3. 应由对象内部推导或维护的状态。

下载任务的 file_name 和 total 可能是必填项，received 应从 0 开始，不该让调用者随便传。重试策略可以有默认次数，再通过构建器覆盖。内部生成的请求编号则不应该暴露成普通构造参数。

失败时别留下半个对象

构造关联函数通常先在局部变量里完成解析和校验，最后一次性返回 Self。这样失败时只有临时值被丢弃，不会把半初始化对象交出去。Rust 本身不会允许读取未初始化字段，但“字段都有值”不代表“业务构造完成”。Result<Self, E> 正好把这两个出口写进签名：成功得到完整对象，失败得到可处理的原因。

错误返回也是方法协议

接收者说明成功或失败时值怎么流动，返回类型则说明调用者要面对哪些结果。bool、Option、Result 和 panic 都能表示“事情没按理想路径走”，含义却不同。

如果失败只有一个自然含义，而且调用者通常只关心有没有值，Option 很合适。例如 cache.get(key) -> Option<&Value> 中的 None 就是“没有这个键”。如果调用者需要区分失败原因并采取不同动作，Result<T, E> 更清楚。账户提现失败可能是冻结、金额非法或余额不足，把它们全部压成 false 会让界面无法给出准确提示。

#[derive(Debug, PartialEq, Eq)]
enum RenameError {
    Empty,
    TooLong { max_chars: usize },
}
 
struct Project {
    name: String,
}
 
impl Project {
    fn rename(&mut self, name: impl Into<String>) 

这个方法在所有检查完成后才修改字段，所以返回 Err 时原名称不变。这样的失败原子性值得成为方法契约的一部分。若方法先清空名字，再发现新名字太长，调用者得到错误时还要猜对象是否已经被部分修改。

错误类型应服务于调用者的决定

应用内部原型用 String 做错误很省事，但公共或长期维护的 API 更适合结构化枚举。调用者可以匹配 RenameError::TooLong { max_chars }，把限制显示给用户，而不用解析一段可能改文案的字符串。错误枚举也不必把所有底层细节都泄漏出去；只保留当前边界的调用者能理解并处理的信息。

错误类型太细也会造成负担。若十种解析失败对调用者只有“这份配置无效”一个处理动作，可以在边界处归并，并把详细上下文留给日志。设计错误和设计方法一样，都要从调用方场景倒推，而不是字段越多越专业。

panic 适合表示契约被程序员破坏

正常输入不合法、网络暂时失败、文件不存在，都应该让调用者有机会处理。panic 更适合内部不变式已被破坏、数组索引写错，或某个在当前代码结构下理论上不可能发生的分支。即使如此，也要问能否通过类型去掉这个不可能分支。

类型状态示例中的 expect 之所以尚可接受，是因为私有字段和状态转换共同保证 HasPort 一定装有端口；如果用户传 0 就触发同一个 expect，那便是把普通输入错误伪装成程序缺陷。编译器是严格的搭档，panic 则是程序在运行时直接掀桌。不要用后者逃避本来可以写进 Result 的分支。

消费者方法会结束旧值的故事

当方法接收 self，调用者把所有权整个交了进去。这常见于三类操作：把对象转换成另一种表示、取出内部资源、结束某个只能执行一次的流程。

#[derive(Debug)]
struct Response {
    status: u16,
    body: String,
}
 
impl Response {
    fn status(&self) -> u16 {
        self.status
    }
 
    fn body(&self) -> &str {

200 ok
ok

body(&self) 只是暂借字符串，into_body(self) 则把内部的 String 移交给调用者，不用克隆。方法名里的 into_ 是很有用的路标：它通常暗示所有权转换。相似地，Rust API 常用下面这组命名表达成本和所有权：

• as_... 通常是便宜的借用视图，例如 as_str。
• to_... 通常会创建一个新值，可能分配或复制，例如 to_owned。
• into_... 通常消费原值，尽量复用已有资源，例如 into_bytes。

这不是编译器强制的语法，却能显著减少调用者读签名的次数。一个名为 get_body 的方法如果突然消费整个响应，会让人措手不及；into_body 则提前把代价说了出来。

为什么构建器经常消费自己

构建器的中间状态只为最终对象服务。build(self) 能把其中的字符串和容器直接移动出去，并阻止同一个构建器被误用两次：

#[derive(Debug)]
struct ClientConfig {
    base_url: String,
    timeout_ms: u64,
}
 
struct ClientBuilder {
    base_url: String,
    timeout_ms: u64,
}
 
impl ClientBuilder {
    fn new(base_url: impl Into<String>) ->

ClientConfig { base_url: "api.example.test", timeout_ms: 1500 }

timeout_ms(mut self, ...) 中的 mut 只表示方法体内可以修改这份已经移入的 self。调用者的原绑定不需要是 mut，因为每一步都消费旧构建器并返回一个新构建器。优化后资源通常直接沿着链移动，并不意味着每一步都会深拷贝。

消费并不总是最方便

如果调用者要反复尝试构建，或希望在循环中逐项修改同一个配置，&mut self -> &mut Self 风格可能更合适：

struct LoggerBuilder {
    verbose: bool,
}
 
impl LoggerBuilder {
    fn verbose(&mut self, enabled: bool) -> &mut Self {
        self.verbose = enabled;
        self
    }
}

两种构建器各有代价。self -> Self 很适合一条从创建到完成的表达式，也便于做“每一步产生新状态”的类型设计；&mut self -> &mut Self 方便条件分支和循环复用。不要因为链式调用看起来漂亮就强迫所有 API 消费自己。

带 Drop 的类型不能随便移出字段

如果类型实现了 Drop，消费者方法里直接移动某个非 Copy 字段可能会被编译器拦住。原因很实际：析构函数稍后还会接收到整个 self 的可变引用，它可能认为所有字段仍可用。常见做法是把可取出的资源存成 Option<T> 后调用 take()，或在 &mut self 中使用 std::mem::take 把字段替换成默认值。不要为了绕过这条规则轻易写 unsafe；先让类型的“资源是否已经取走”在字段里有明确表示。

方法链好不好用取决于错误放在哪里

链式 API 最吸引人的地方，是让代码按动作顺序读下去：创建、配置、构建。真正棘手的是某一步可能失败时，链上究竟应该出现 Result。

这个交互图会沿着每次方法调用标出当前值究竟是构建器还是 Result，也能观察 ? 在哪里提前返回。先拖动执行到失败节点，再回来看下面的代码，链上的类型变化会更容易读出来。

下面的请求构建器选择“尽早校验请求头，最后校验必填字段”：

#[derive(Debug, PartialEq, Eq)]
enum BuildError {
    EmptyPath,
    InvalidHeaderName,
    MissingMethod,
}
 
#[derive(Debug)]
struct Request {
    method: String,
    path: String,
    timeout_ms: u64,
    headers: Vec<(String

POST /events，超时 1000ms，请求头 1 个

注意 header(...) 之后的 ?。在它之前，链上的值是 RequestBuilder；调用之后得到的是 Result<RequestBuilder, BuildError>。Result 没有这个构建器的 build 方法，所以你需要用 ? 取出成功值并提前传播错误，或者用 and_then、map 继续组合。

let request = RequestBuilder::new("/health")
    .method("GET")
    .header("accept", "text/plain")
    .and_then(RequestBuilder::build);

这段写法能工作，因为 and_then 在请求头合法时把构建器传给 build，失败时保留原错误。它适合短组合；链一长，闭包和类型变化会让代码变得比普通局部变量更难读。链式调用是表达手段，不是越长越成熟。

早失败还是最后一起失败

让每个设置方法都返回 Result<Self, E>，可以在无效值出现的位置立刻报错，缺点是链上到处都是 ?。让设置方法只存原始值，统一由 build 校验，链很干净，也便于一次收集多个问题，但对象会在构建器内部暂时处于非法状态。

可以按错误性质拆分：格式完全不可能被后续配置修复时尽早失败；字段之间的组合约束留到 build。比如请求头名称含空白，后续设置不会让它变合法，适合立即返回错误；“认证方式 A 需要字段 B，但不能和 C 同时出现”则必须等配置接近完成再判断。

Result 链不要吃掉上下文

下面这种写法虽然能把错误变成默认值，却可能让真实配置问题悄悄混过去：

let timeout = "abc".parse::<u64>().unwrap_or(3_000);

如果 abc 来自用户配置，这通常不是合理默认，而是应当报告的输入错误。方法链的目标是让数据流清楚，不是把所有失败都压成一个看似顺畅的成功值。错误类型应该保留调用者能采取行动的信息，例如“缺少方法”和“请求头名称非法”就是不同的修复方向。

类型状态能让错误调用根本没有方法可选

普通构建器把必填字段存成 Option<T>，最后由 build 检查。这种设计简单、错误信息集中，通常已经够好。还有一种更严格的做法：把“端口有没有设置”编码进构建器类型，让只有完整状态才拥有 build 方法。

use std::marker::PhantomData;
use std::num::NonZeroU16;
 
struct MissingPort;
struct HasPort;
 
#[derive(Debug)]
struct Server {
    host: String,
    port: NonZeroU16,
}
 
struct ServerBuilder<State> {

0.0.0.0:8080

ServerBuilder<MissingPort> 没有 build。调用 port 会消费缺端口的构建器，返回 ServerBuilder<HasPort>，新类型才提供 build。如果漏写 .port(...)，编译器不会等到运行时返回“缺少端口”，而是直接说当前类型没有这个方法。

这个设计里 Option<NonZeroU16> 看起来有点重复：类型状态已经说明端口存在，为什么字段还要 Option？因为两个状态共用同一个结构体布局，MissingPort 阶段确实没有端口。更复杂的实现可以让不同状态持有不同字段结构，从而去掉 expect，但代码量还会继续增加。示例中的 expect 依赖私有字段和私有状态转换维护的内部不变式，外部安全代码无法构造一个 port: None 的 HasPort 构建器。

类型状态的收益和账单

类型状态适合步骤少、顺序重要、非法调用代价高的流程，例如握手阶段、事务提交、文件写入完成、协议状态转换。它把运行时分支搬到编译期，也让方法集合随状态变化。

代价是类型数量、泛型参数和错误信息都会变多。若构建器有十个可选字段和五个可任意顺序设置的必填字段，为每种组合编码状态很快会膨胀。此时一个普通 build(self) -> Result<T, E> 往往更容易维护，也更方便从动态配置逐项填充。

还要考虑库的使用者。如果他们只是写一段静态配置，类型状态能给出很好的补全提示；如果字段来自循环、配置文件或条件分支，不同分支产生不同泛型状态，代码可能需要额外重组。类型系统能表达不代表一定值得表达。先估算错误发生频率、修复时机和 API 使用方式，再决定把检查放在编译期还是 build。

多个 impl 是组织工具，也是条件能力

一个类型可以有多个固有 impl 块。它们不会创建多个版本的类型，只是把方法分开放置：

struct Session {
    token: String,
    requests: u64,
}
 
impl Session {
    fn new(token: impl Into<String>) -> Self {
        Self {
            token: token.into(),
            requests: 0,
        }
    }

小类型没必要为了形式拆开。类型较大时，可以按职责把构造、查询、状态转换和内部辅助方法分组；泛型类型还可以只在满足额外条件时提供某些方法。

#[derive(Debug)]
struct Bag<T> {
    items: Vec<T>,
}
 
impl<T> Bag<T> {
    fn new() -> Self {
        Self { items: Vec::new() }
    }
 
    fn push(&mut self

2 Some(9)
rust + impl

所有 Bag<T> 都有 new、push 和 len。只有元素实现 Ord 的袋子才有 max，只有 Bag<String> 才有 joined。这是一种很自然的 API：能力跟着类型条件出现，调用者不必在运行时问“这个袋子能不能求最大值”。如果条件不满足，方法根本不在候选集合里，编译器会指出缺少的 trait 约束。

多个 impl 也有维护成本。把同一类方法散到十几个文件，读者仍然要四处寻找。拆分应该服务于稳定边界，例如“所有 T 都有的基础操作”和“T: Ord 才有的排序操作”，而不是每个方法单独一个块。

trait 扩展方法让能力跟着约束走

固有方法写在 impl Type 中，只有定义这个类型的 crate 能添加。trait 方法则先声明一份能力契约，再为满足条件的类型实现。它特别适合两种场景：多个类型要共享同一种操作；你想给外部类型补一组本 crate 内可用的方法。

mod statistics {
    pub trait SliceStats {
        fn mean(&self) -> Option<f64>;
    }
 
    impl SliceStats for [i32] {
        fn mean(&self) -> Option<f64> {
            if self.is_empty() {
                return

Some(20.0)

数组通过自动转换候选找到了切片上的实现。更关键的是，SliceStats 必须在调用处可见；如果移除 use statistics::SliceStats，点号不会在所有依赖中全局搜索扩展方法。这个限制避免不同库悄悄塞进大量同名方法，也让调用者能够看出能力来自哪里。

如果你只想触发方法可用、又不想在当前作用域直接使用 trait 名，可以写：

use statistics::SliceStats as _;

trait 是契约，不只是“外挂方法”

扩展 trait 的名字和方法应说明行为约束。mean 对空切片返回 None，这是契约的一部分。若一个实现返回 0.0，另一个实现 panic，泛型调用者就很难可靠使用它们。编译器能检查签名一致，却不会替你验证语义一致，文档、测试和命名仍由作者负责。

trait 也可以提供默认方法：

trait Summary {
    fn title(&self) -> &str;
 
    fn summary(&self) -> String {
        format!("《{}》", self.title())
    }
}
 
struct Article {
    title: String,
}
 
impl

默认实现能复用基于其他必需方法的公共逻辑。它不是继承一份可变状态，也不能访问实现类型没有暴露给 trait 的字段。

blanket impl 很强，也会占住位置

你可以为一整类满足约束的类型实现 trait：

use std::fmt::Debug;
 
trait DebugLabel {
    fn debug_label(&self) -> String;
}
 
impl<T: Debug> DebugLabel for T {
    fn debug_label(&self) -> String {
        format!("{self:?}")

这样所有实现 Debug 的类型都获得 debug_label。方便的代价是覆盖范围很大：你不能再给某个同样实现 Debug 的具体类型写另一份重叠实现。公共库发布 blanket impl 前要谨慎，因为它会影响下游未来能写哪些实现。

泛型代码只能依赖写出来的能力

对具体类型写方法调用时，编译器知道它有哪些固有方法，也能检查作用域内的 trait。对类型参数 T，函数体不能假设调用者碰巧传入某个有同名方法的类型；可用能力必须出现在 trait 约束里。

trait Validate {
    type Error;
 
    fn validate(&self) -> Result<(), Self::Error>;
}
 
fn save<T>(value: &T) -> Result<(), T::Error>
where
    T: Validate,
{

save 不关心 T 是用户、订单还是配置，只承诺在保存前调用 Validate::validate。关联错误类型让每个实现选择自己的错误，同时让函数返回值准确跟随 T。如果没有 T: Validate，即使你只在当前项目里用一个恰好有 validate 固有方法的类型调用，泛型函数体也不会通过编译，因为它必须对所有允许的 T 成立。

约束还能决定某个固有 impl 是否出现。前面的 impl<T: Ord> Bag<T> 表示 max 只有在元素可排序时存在；这里的 T: Validate 则表示泛型函数可以调用 trait 方法。两者都在做同一件事：把“这段代码需要什么能力”从实现细节提到签名。

静态分发与 trait 对象面对的是不同问题

泛型参数通常使用静态分发。编译器针对实际类型生成或优化调用，方法接收者的具体类型在编译期已知。若程序需要把不同具体类型放进同一个集合，可以使用 trait 对象，让方法在运行时根据实际对象分发：

trait Task {
    fn name(&self) -> &str;
    fn run(&mut self) -> Result<(), String>;
}
 
fn run_all(tasks: &mut [Box<dyn Task>]) {
    for task in tasks {
        let name =

这里先把 name 变成拥有的 String，再调用需要 &mut self 的 run。如果一直保留借自 task 的 &str 并在运行后使用，就会遇到与前面 User 示例相同的共享借用和可变借用冲突。换成 trait 对象不会让借用规则消失。

trait 对象要求方法能够通过对象安全地调用。返回 Self、没有合适接收者的泛型方法等设计，可能只适合静态知道具体类型的场景。你不必为了“以后也许会动态分发”把所有 trait 都限制成对象可用，但如果核心用途就是异构任务集合，应在设计接收者和返回值时尽早验证。

约束放在哪里会影响接口可读性

短约束可以直接写成 fn save<T: Validate>(...)，复杂约束放在 where 中更容易顺着读。若多个方法反复要求同一组能力，可以考虑把它们组合成领域 trait，但不要创建一个没有语义、只为少写几行 where 的“大杂烩 trait”。

约束过强会无谓缩小 API。例如只需要比较相等却要求 T: Ord，调用者就必须提供完整排序；只需格式化错误却要求 Clone + Send + Sync + 'static，也会排除本来合法的类型。和选择 &self 一样，泛型约束应只索取实现真正需要的能力。权限越小，接口通常越容易组合。

孤儿规则为什么不让你随便替别人实现

你可能想让 Vec<String> 直接支持格式化输出，于是写出下面的实现：

use std::fmt;
 
// 这段代码无法编译：trait 和类型都不是当前 crate 定义的。
impl fmt::Display for Vec<String> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.join(", "))

Display 属于标准库，Vec 也属于标准库。常见情形下，trait 或实现目标类型至少要有一方由当前 crate 定义，否则这份实现违反孤儿规则。

这条规则第一次遇到很像编译器在多管闲事：“我只是想打印一个列表，为什么不行？”把项目放大就能看出问题。假设两个依赖库都能替 Vec<String> 实现 Display，而且格式不同，你的程序同时引入它们时该选谁？更糟的是，某个依赖升级后新增这份实现，原本能编译的下游项目会突然冲突。孤儿规则提前消除了这类跨 crate 争夺，保证同一 trait 与类型组合的实现保持一致。

只想加方法时，定义本地 trait

如果需求只是在你的 crate 内给 Vec<String> 加一个方法，可以定义本地扩展 trait：

trait StringVecExt {
    fn non_empty_count(&self) -> usize;
}
 
impl StringVecExt for Vec<String> {
    fn non_empty_count(&self) -> usize {
        self.iter().filter(|s| !s.trim

trait 是你定义的，所以实现外部类型没有问题。调用者需要把这个 trait 引入作用域。它很轻量，但无法让 Vec<String> 变成一个语义不同的新类型，也不能替它实现那个外部 Display。

需要新身份时，用 newtype

newtype 是一个包住现有类型的本地元组结构体。它在运行时通常只是同一份数据，类型系统却把它视为新的类型：

use std::fmt;
 
#[derive(Debug, Default)]
struct TagList(Vec<String>);
 
impl TagList {
    fn new(tags: Vec<String>) -> Self {
        Self(tags)
    }
 
    fn as_slice(&self) -> &[

Rust · API 设计
2 个标签

现在 TagList 是本地类型，可以为它实现外部 trait。它还能阻止你把任意 Vec<String> 误传到只接受标签列表的接口里。代价也很诚实：你需要决定暴露哪些原始容器能力，必要时补 From、AsRef、迭代器等转换。

有人会立刻给 newtype 实现 Deref<Target = Vec<String>>，这样几乎所有 Vec 方法都能直接调用。对真正像智能指针、应该透明表现为内部目标的类型，这很自然；对有领域含义的包装类型，它可能过度暴露修改入口，让不变式再次失守，还会增加方法重名的可能。像上面的 TagList 一样提供 as_slice 和受控的 push，虽然多写几行，却把边界保留得更清楚。

enum 的方法把 match 收回类型内部

impl 不只属于结构体。枚举同样可以有固有方法、关联函数和 trait 实现。实际项目里，这一点能减少大量散落的 match，并把状态转换规则集中在类型附近。

#[derive(Debug)]
enum OrderState {
    Draft,
    Paid { receipt: String },
    Shipped { tracking: String },
    Cancelled { reason: String },
}
 
#[derive(Debug, PartialEq, Eq)]
struct TransitionError {
    state: &'static str,

草稿，可取消：true
已发货，可取消：false
已发货状态不能执行取消

label(&self) 和 can_cancel(&self) 只观察变体。三个转换方法接收 self，旧状态一旦参与转换就不能继续使用。这个选择避免了“支付成功后，调用者手里还留着一个可继续操作的草稿值”。转换失败时，示例只返回状态标签和动作，因此旧值也被消费；如果业务需要失败后重试，可以让错误携带原状态，或者改成 &mut self 并保证失败时不修改。

两种方案的权衡要由业务语义决定：

• fn transition(self) -> Result<Self, E> 很适合强调旧状态作废，也容易把不同状态做成不同类型。
• fn transition(&mut self) -> Result<(), E> 便于在同一个变量上反复操作，失败后对象仍在，但你必须保证修改是原子的，不能写到一半返回错误。

不要为了隐藏而隐藏 match

把常用判断收进 enum 方法能减少重复，也能确保新增变体时由编译器提醒你补全内部匹配。但如果调用者本来就要为每个变体执行完全不同的工作，返回一堆模糊布尔值反而会丢信息。match 不是坏味道；散落且反复复制同一业务规则的 match 才值得收拢。

枚举的关联函数也可以提供语义化入口，例如 OrderState::draft()。不过没有参数的单位变体已经能写成 OrderState::Draft，再包一层函数未必更清楚。构造函数应该隐藏复杂度或守住不变式，不必给每个变体机械套一层。

点号背后有自动借用和自动解引用

你早就用过自动借用，只是可能没注意：

let mut text = String::from("Rust");
text.push_str(" API");
println!("{}", text.len());

push_str 需要可变引用，调用点却没有手写 (&mut text).push_str(...)；len 需要共享引用，也没有手写 (&text).len()。点号调用会根据候选接收者类型尝试借用。

自动解引用则让指针和包装类型上的方法调用更自然：

let boxed = Box::new(String::from("  rust  "));
 
assert_eq!(boxed.len(), 8);
assert_eq!(boxed.trim(), "rust");

Box<String> 可以解引用到 String，String 又能解引用到 str。len 和 trim 的具体可用位置不必由调用者逐层写出 *。这不是继承，也不是把底层类型的所有方法复制了一份；编译器是在方法查找时构造一系列候选接收者。

可以用一个简化但实用的过程理解查找：

如果候选类型列表还是有点抽象，可以在这个方法查找显微镜里逐步展开接收者。它会把每次解引用、补上的共享或可变引用，以及最终命中的方法按顺序标出来。

最后一句很重要：方法查找不是先收集全世界所有固有方法，再把它们整体排在所有 trait 方法前面。搜索是沿候选接收者顺序进行的，因此较早候选上的 trait 方法可能先于较晚候选上的固有方法被选中。

struct Probe;
 
trait Inspect {
    fn inspect(&self) -> &'static str;
}
 
impl Probe {
    fn inspect(&mut self) -> &'static str {
        "固有方法"
    }
}
 
impl Inspect for Probe

trait 方法
固有方法

第一次点号调用先匹配到了共享引用候选上的 trait 方法。第二次改用 Probe::inspect(&mut probe)，明确选择固有方法。这个例子不常见，却能纠正一个危险口诀：“有同名固有方法就一定调用固有方法。”实际代码如果让方法名只靠接收者可变性区分，会给读者制造惊喜，最好直接换名。

Deref 会扩大公开 API

如果 T 实现 Deref<Target = U>，很多需要 &U 的上下文都能接受 &T，方法查找也会看见目标类型的方法。这使 Box<T>、String 等类型很好用，也意味着 Deref 不是一个无害的转发小技巧。

实现后，目标类型新增方法可能与你自己的方法重名；调用者也会自然认为包装值“就是一种目标值”。因此，只有当解引用便宜、不会失败，而且透明行为符合直觉时，才适合实现它。只想提供一次明确转换时，AsRef、Borrow 或普通的 as_slice、as_str 方法往往边界更清楚。

自动借用不会替你绕开所有权规则

点号能补 & 或 &mut，前提是对应借用本来就合法。下面的值没有声明为可变，编译器不能凭空取得可变引用：

let text = String::from("Rust");
// text.push('!');
// 取消注释会报错：不能把不可变绑定借用为可变。

同样，如果共享引用仍在使用，自动借用不会替你提前结束它。语法糖只减少符号，不会削弱借用检查。

重名时用完全限定语法把意图写全

当两个可见 trait 都为同一个类型提供同名方法，value.method() 可能无法决定目标。与其靠调整 use 碰运气，不如直接指出类型和 trait：

trait JsonView {
    fn render(&self) -> &'static str;
    fn media_type() -> &'static str;
}
 
trait TextView {
    fn render(&self) -> &'static str;
    fn media_type() 

固有摘要
{"status":"ok"}
status=ok
application/json

<Report as JsonView>::render(&report) 是完全限定语法。尖括号里写“把 Report 视为 JsonView 的实现”，后面再选关联项。对于有接收者的方法，有时 JsonView::render(&report) 已足够，因为实参能推断出 Self；完全限定形式信息最完整，在复杂泛型和重名场景中也最稳定。

media_type 没有 self 参数，调用时没有实例帮助推断到底是哪一个实现，所以 <Report as JsonView>::media_type() 尤其有用。固有方法也可以用 Report::render(&report) 调用。

不要背一张过度简化的优先级表

在最普通的同一接收者候选上，固有方法通常会让 report.render() 直接选择 Report 自己的实现。但自动借用、自动解引用、泛型 trait 约束和 trait 是否在作用域中都会影响候选集合。遇到以下情况，直接显式调用通常比猜解析顺序更好：

• 两个 trait 定义同名方法。
• 固有方法和 trait 方法接收者形式不同。
• 智能指针自身与它指向的值都有同名方法。
• trait 关联函数没有接收者，无法从实参推断实现类型。
• 泛型代码中，类型参数的 trait 约束提供了同名方法。

完全限定语法看起来长，却把本来藏在编译器查找过程里的选择搬到了代码表面。重名少时点号更自然，出现歧义时多写十几个字符通常很值。

公共方法一旦发布就会参与兼容性

在自己的应用里改方法签名，跟着编译器修完调用点就行。公共库的 impl 不一样：接收者、返回值、泛型约束和方法名都会成为下游代码的一部分。一个看似只改实现的动作，可能让调用者的所有权流程完全变掉。

改接收者不只是性能调整

把 fn name(&self) -> &str 改成 fn name(self) -> String，不只是“现在少一次借用”。旧调用者也许在取名字后继续使用对象，新版本却移动了它。反过来，把消费者方法改成借用方法，调用者可能失去直接取出内部资源的能力，被迫克隆。

&self 改成 &mut self 同样会破坏大量组合：原来可以通过共享引用调用的方法，现在要求调用者取得独占权限；放在 Arc<T> 后的值、同时存在其他引用的值，都可能无法直接调用。设计初期如果拿不准，优先授予完成任务所需的最小权限。以后新增一个更强的方法通常比收紧现有方法容易。

有时可以保留两种入口：

impl Response {
    fn body(&self) -> &str {
        &self.body
    }
 
    fn into_body(self) -> String {
        self.body
    }
}

它们不是重复 API。一个服务临时观察，一个服务所有权转移，名字也把区别说清楚。真正需要警惕的是同时提供 body_owned、get_body_string、clone_body 等多套含义接近却命名不一致的方法，让调用者每次都要查实现。

新增固有方法也可能影响旧的点号调用

假设下游一直通过某个扩展 trait 在你的类型上调用 value.format()。后来你给类型新增一个同名固有方法，接收者刚好也匹配，旧代码的点号调用可能改变目标或产生新的歧义。Deref 包装类型的风险更大，因为目标类型未来新增的方法也会进入查找范围。

所以公共类型的方法名不只要避免当前冲突，还要考虑它处于怎样的扩展生态。通用包装类型通常少放模糊的短名字；扩展 trait 可以使用更有领域信息的名称；需要稳定指定行为的内部代码可以使用完全限定语法。无法预测所有未来冲突，但可以避免主动制造一个挤满 get、run、convert 的命名空间。

返回具体借用会限制未来存储方式

fn name(&self) -> &str 很高效，也承诺结果直接借自 self。如果未来名称需要按需计算、从锁内读取，或拼接多个字段，继续返回普通 &str 可能变得困难。公共 API 设计时要判断这种借用是否反映类型的稳定本质。

这不意味着一律返回 String。为不确定的未来每次都分配，同样是实打实的成本。常见做法是：稳定存储的文本直接返回 &str；确实可能借用也可能拥有的结果考虑 Cow<'_, str>；昂贵计算提供显式拥有型结果；需要在锁内读取时让调用者通过闭包访问，或重新设计边界。返回类型既是性能选择，也是你对内部表示能否长期维持的承诺。

trait 默认方法和 blanket impl 也要留空间

给 trait 新增有默认实现的方法，通常比新增必需方法温和，因为旧实现不必立刻补代码。但名字仍可能和实现类型或其他 trait 冲突。新增 blanket impl 更需要谨慎，它可能与下游已有或计划中的实现重叠。

公共 API 没有“设计完就永远不动”的现实。更实用的目标是让每次变化都清楚：这是新增能力，还是改变所有权协议；调用者能否通过新方法逐步迁移；错误是否在编译期指向明确。Rust 的严格检查会让破坏性变化很快暴露，这有时显得吵，却比静默改变运行时行为更负责。

把接收者设计成调用者能读懂的协议

现在把前面的知识放回一个真实一点的 API 评审。假设你要设计“草稿消息”：可以设置收件人和正文，发送前要校验，发送后草稿不应再使用。

第一版可能把所有方法都写成 &mut self：

struct Draft {
    to: Option<String>,
    body: String,
}
 
impl Draft {
    fn set_to(&mut self, to: String) {
        self.to = Some(to);
    }
 
    fn set_body(&mut self, body: String) {

它能修改数据，却没有表达三件事：空收件人是否合法，发送是否会失败，发送后为什么还能再次调用 send。接收者不是实现细节；选错后，API 会允许不该发生的调用顺序。

可以把边界改成这样：

#[derive(Debug, PartialEq, Eq)]
enum DraftError {
    MissingRecipient,
    EmptyBody,
}
 
#[derive(Debug)]
struct Message {
    to: String,
    body: String,
}
 
#[derive(Debug, Default)]
struct Draft {
    to

预览：方法签名就是调用协议
收件人：reader@example.test
已向 reader@example.test 发送 30 字节

preview(&self) 允许反复查看；配置方法使用 self -> Self，形成一条一次性的构建链；build(self) 消费草稿并验证不变式；send(self) 又消费合法消息，避免同一个值被发送两次。编译器无法保证外部系统绝不重复投递——进程可能重试，请求可能超时——但它至少能保证这份内存中的 Message 不会被普通安全代码再次调用。

输出中的字节数是 UTF-8 字节数，不是中文字符数。String::len() 返回字节长度，这是一个很典型的 API 语义细节：方法名短不代表含义可以靠猜。如果业务需要字符数量，应明确使用 self.body.chars().count()，并考虑“用户眼中的一个字符”可能还涉及更复杂的文本边界。

编译器能保证什么，不能保证什么

方法接收者能表达内存中的所有权协议，却不是完整业务事务：

• self 能阻止当前值再次使用，不能阻止调用者提前克隆一份。
• &mut self 能保证当前进程安全 Rust 代码里的独占借用，不能自动锁住数据库中的同一行。
• 私有字段能收紧创建入口，不能替代外部输入校验和持久化迁移。
• Result 能强迫调用者面对失败分支，不能保证调用者不会直接 unwrap。

这不是 Rust 的失败，而是边界要诚实。让类型系统承担它擅长的局部保证，再用幂等键、数据库约束、事务和测试处理系统级问题。把 send(self) 宣传成“绝不会重复发送”就过头了；说它“让同一个消息值只能进入发送方法一次”才准确。

常见借用报错该怎样倒推接口

方法写完后遇到借用错误，不要先把所有返回值改成克隆。先看编译器指出的两次访问分别想做什么，再决定是缩短借用、拆分字段，还是改变 API。

返回引用后又想修改对象

struct Queue {
    items: Vec<String>,
}
 
impl Queue {
    fn first(&self) -> Option<&str> {
        self.items.first().map(String::as_str)
    }
 
    fn push(&mut

如果你保存 first() 的结果，接着调用 push()，最后还要使用旧引用，编译器会拒绝。Vec 扩容时可能移动底层缓冲区，旧引用真的可能悬空。这不是无意义的保守。

可选修复取决于需求：

• 先用完 first，再 push，缩短引用存活范围。
• 调用 map(str::to_owned) 得到独立字符串，接受分配成本。
• 如果只是需要位置，保存索引而不是引用，但后续删除和排序仍可能改变含义。
• 重新设计操作，把“查看并插入”合并成一个内部可安全完成的方法。

一次方法借用了整个 self

有时结构体字段互不相关，你却因为调用 &mut self 方法而无法同时借用另一个字段。编译器在直接字段访问时常能识别字段分离，但跨过方法边界后只看见签名授予了整个 self 的权限。

struct Editor {
    document: String,
    history: Vec<String>,
}
 
impl Editor {
    fn document_and_history(&mut self) -> (&mut String, &mut Vec<String>) {
        (&mut self.document, &mut self.history)

当一个操作确实需要同时处理两个字段，可以提供一次拆分借用，让编译器看见两份引用指向不同字段。另一种做法是把字段提炼成各自的子结构，让方法只借用需要的部分。不要马上使用 RefCell 绕开问题；很多时候，报错是在提醒你的类型承担了太多互不相关的职责。

self 方法在循环里把值移动了

struct Batch(Vec<String>);
 
impl Batch {
    fn finish(self) -> usize {
        self.0.len()
    }
}

如果在循环中反复调用 batch.finish()，第一次就移动了 batch。如果“完成”本来就只能发生一次，循环才是错误调用；如果你其实只想反复查询长度，方法应该是 len(&self)；如果需要多次尝试且失败后归还原值，可以返回带原值的错误，例如 Result<Output, (Self, Error)>。从报错倒推业务语义，往往比随手加 clone() 更接近正确设计。

链式方法和临时值生命周期

返回 &mut Self 的链可以直接操作一个命名变量，也常能作用于临时构建器。但如果某个方法返回的是借自临时对象的引用，语句结束后临时值被丢弃，引用不能继续保存。编译器通常会提示“临时值在仍被借用时被释放”。修复方法是先把拥有者绑定到局部变量，再取得引用；这不是多余仪式，而是在代码里明确谁负责让数据继续活着。

练习：让签名先替你说话

下面的题不要求背术语，重点是从调用后的所有权和失败方式反推签名。

设计一个有不变式的百分比类型

请实现 Percentage，要求内部值只能在 0..=100：

• 字段不能由类型外部直接修改。
• try_new(u8) -> Result<Self, PercentageError> 拒绝大于 100 的值。
• get(&self) -> u8 返回数值。
• into_inner(self) -> u8 消费包装值并返回内部数值。

#[derive(Debug, PartialEq, Eq)]
struct PercentageError {
    value: u8,
}
 
#[derive(Debug, PartialEq, Eq)]
struct Percentage(u8);
 
impl Percentage {
    fn try_new(value: u8) -> Result<Self, 

修复一次借用冲突

下面的代码为什么不能编译？请给出一种不分配的修复和一种拥有型修复。

let mut queue = Queue {
    items: vec![String::from("A")],
};
 
let first = queue.first().unwrap();
queue.push("B");
println!("{first}");

let first = queue.first().unwrap();
println!("{first}");
queue.push("B");

let first = queue.first().unwrap().to_owned();
queue.push(

为状态转换选择失败语义

给文件上传状态 Pending、Uploading、Completed、Failed 设计方法。先不要急着写实现，先回答：complete 失败后，调用者是否还需要原状态？

如果不需要，可以用：

fn complete(self) -> Result<Self, TransitionError>

如果需要修正信息后重试，可以让错误归还所有权：

fn complete(self) -> Result<Self, (Self, TransitionError)>

如果始终在同一个状态槽位上操作，并且失败保证不修改，可以用：

fn complete(&mut self) -> Result<(), TransitionError>

三种签名都可能正确。真正的设计题不是选出某个固定接收者，而是让调用者从签名里看见失败之后手里还剩什么。

写完 impl 后做一次接口对账

当一个 impl 越写越大，可以按下面的顺序检查。它不是风格警察清单，而是在发布 API 前替未来调用者走一遍真实路径。

1. 先看创建入口。调用者能否绕过校验构造非法值？失败是正常输入分支，还是程序员违反前置条件？前者通常返回 Result，后者也应尽量通过类型表达，而不是急着 panic。
2. 再看每个接收者。只读操作有没有误用 &mut self 限制组合？终结性转换有没有误用 &self 后被迫克隆？消费方法的名字是否向调用者提示原值会失效？
3. 检查返回引用。它借自哪个对象，调用者是否很可能需要跨过一次修改继续保存？如果这种需求常见，可以补一个拥有型转换，而不是取消高效的借用版本。
4. 检查方法链。链上的类型何时从 Self 变成 Result<Self, E>？错误在出现处返回还是在 build 汇总？长链是否已经掩盖了控制流？
5. 检查扩展边界。行为属于类型核心能力，还是适合做可导入的 trait？blanket impl 会不会挡住未来的具体实现？外部 trait 与外部类型的组合是否需要 newtype？
6. 最后检查重名和自动解引用。调用者看到 value.method() 能否合理预测目标？如果答案依赖一张复杂优先级表，就改名或用完全限定调用把意图写出来。

接口测试也应该围绕这些承诺，而不只验证几条成功输出。构造器要覆盖每一种不合法输入，并确认错误时没有产生对象；可变方法要验证失败后原状态是否保持；消费者方法要验证内部资源能否直接转移；枚举转换要覆盖每个不允许的状态。若你维护的是库，还可以写编译失败测试，明确展示“共享引用存活时不能修改”“缺少类型状态时没有 build”“消费后不能再次调用”。有些规则本来就是编译期行为，仅靠运行时单元测试看不见。

命名检查可以直接放到一段调用代码里做。不要盯着 impl 内部问名字是否优雅，而是连续写出最常见路径：

let endpoint = Endpoint::try_new("localhost", 8080)?;
let request = RequestBuilder::new("/health")
    .method("GET")
    .build()?;
let response = client.send(request)?;
let body =

即使这些类型来自不同模块，调用顺序也应该让人看出哪里可能失败、哪里会消费旧值。如果你发现必须在每行旁边写注释解释“这个方法其实会克隆”“那个方法失败后对象已改变”，签名和名字多半还没把协议说清楚。

还有一个很实际的检查方法：尝试站在调用者角度故意误用。能不能创建空主机？能不能在完成后重复提交？能不能拿着内部引用跨过一次会重新分配容器的修改？能不能因为某个 Deref 意外绕开校验？编译器能拦住的误用越接近业务规则，后续代码需要记忆的隐含约定就越少。不过也别把每条动态规则都硬编码成几十个泛型状态；当类型变得比业务本身更难读时，结构化 Result 和清楚的运行时校验通常更合适。

最后看一次实现是否索取了超过需要的权限。一个格式化方法如果接收 &mut self，会让它无法在共享上下文使用；一个只为读取字符串而消费 self 的方法，会迫使调用者提前安排所有权；一个泛型函数多要求了 Clone，调用者就可能为了满足签名而做无意义复制。最小权限不是抽象口号，它直接决定方法能否被放进更多真实调用流程。

做完这些检查，再读一遍编译器给出的警告。未使用字段可能说明示例没有展示真实语义，永远不会进入的分支可能意味着状态模型重复，没必要的 mut 则经常提示方法根本不需要修改权限。警告不一定都是设计缺陷，但它们很适合充当最后一轮接口评审的提问清单。

方法与 impl 最终解决的不是“函数放在哪个大括号里”，而是让数据的使用协议有一个清晰主语。&self、&mut self 和 self 把读取、独占修改、所有权转移写在入口处；构造器和私有字段守住合法状态；trait 与 newtype 决定能力怎样跨类型和 crate 延伸；方法查找与完全限定语法则处理点号背后的便利和歧义。

下一次编译器因为一次移动或借用冲突把你拦下来时，先别急着加 clone()。看看它究竟在追问哪段协议：旧值还该不该存在，引用还要活多久，这个方法有没有拿到过多权限。把答案写回签名，往往就是更可靠的 API。