需求:给服务加一个指标上报模块。采集到的指标要能打到终端,方便本地调试;也要能存进内存,方便单元测试断言;将来还要推给远端。同一份数据,三个去处。

第一版写得很自然:一个结构体存一条指标,一个函数负责打印。加第二个去处时就卡住了——打印函数把「输出到终端」写死在里面,想换目标只能复制一份再改。这类「同一份数据、多种处理方式」的需求,正好对应 Rust 建模的三件工具:结构体表达「一条记录有哪些字段」,枚举表达「它属于哪几种之一」,trait 表达「处理它的东西必须具备什么能力」。

这篇不做名词解释,而是一步步把这个模块从能打印,做到能换输出目标、能同时支持编译期和运行期选择。中间会贴出五条真实报错,讲清它们在防什么。

场景走查:从一条指标到两个输出目标

先立最小需求:指标有名字、类型、数值。类型只有两种,计数器(只增不减)和仪表盘(可上可下)。

#[derive(Debug, Clone, Copy)]
enum Kind {
    Counter,
    Gauge,
}

struct Metric {
    name: String,
    kind: Kind,
    value: f64,
}

fn main() {
    let m = Metric {
        name: String::from("cpu_usage"),
        kind: Kind::Gauge,
        value: 91.5,
    };
    println!("{:?}", m);
}

放进 src/main.rs,cargo run 的输出是:

Metric { name: "cpu_usage", kind: Gauge, value: 91.5 }

这一步做了三个决定。name 用 String 而不是 &str,因为这条记录要活到上报结束,不能依赖调用方的字符串还在不在;kind 用枚举而不是字符串,因为「类型」只有两种,写错就是编译错误;#[derive(Debug)] 让 {:?} 能打印结构体,调试期很值。Kind 额外派生了 Clone 和 Copy,因为它是纯字段枚举,复制没有成本。

第二步:加一个输出目标。把「怎么输出」抽成 trait,具体实现各写各的。

trait Sink {
    fn write(&mut self, m: &Metric);

    fn flush(&mut self) {
        println!("flush 默认实现:什么也不做");
    }
}

struct StdoutSink;

impl Sink for StdoutSink {
    fn write(&mut self, m: &Metric) {
        println!("[{}] {} = {}", kind_str(m.kind), m.name, m.value);
    }
}

fn kind_str(k: Kind) -> &'static str {
    match k {
        Kind::Counter => "counter",
        Kind::Gauge => "gauge",
    }
}

fn report<S: Sink>(sink: &mut S, metrics: &[Metric]) {
    for m in metrics {
        sink.write(m);
    }
}

fn main() {
    let metrics = vec![
        Metric::new("requests_total", Kind::Counter, 1523.0),
        Metric::new("cpu_usage", Kind::Gauge, 91.5),
    ];
    let mut out = StdoutSink;
    report(&mut out, &metrics);
    out.flush();
}

cargo run 实测输出:

[counter] requests_total = 1523
[gauge] cpu_usage = 91.5
flush 默认实现:什么也不做

Metric::new 是下面补的关联函数,本段省略了定义。注意 report 的签名:&mut S 是可变借用,因为 write 可能修改 sink 内部状态(比如往 Vec 里追加);&[Metric] 是不可变切片,函数只读指标。写清楚这两个修饰词,调用方一眼能看出哪些数据会被改。

指标从产生到落地
采集:生成 Metric
分发:report 遍历切片
落地:Sink 的 write

这个三段式结构就是后面所有讨论的地基:数据用结构体 + 枚举描述,行为用 trait 描述,中间的「分发」决定用泛型还是 dyn。

结构体:字段、方法与所有权

结构体本身很简单,难点全在字段的所有权。上面 name: String 意味着结构体拥有这个字符串;谁创建了它,谁就负责释放。如果写成 name: &str,结构体就得带生命周期参数,变成 struct Metric<'a>,所有用到它的函数签名都要跟着改。这是上一篇讲过的取舍:想让记录独立存在,就用 String;只在一次调用内临时用,才考虑借用。

方法分三种,区别只看第一个参数:

写法拿到什么典型用途
fn new(...) -> Self没有 self,是关联函数构造、工厂方法,用 Metric::new 调用
fn describe(&self)不可变借用只读查询、格式化输出
fn bump(&mut self)可变借用修改字段,如计数器加一
fn into_line(self)拿走所有权把结构体转换成另一种类型,调用后原值失效

字段默认私有,只有同模块和子模块能访问。想给外部用,就写 pub。但把所有字段都标 pub 等于放弃了约束:外部可以绕过 new 直接构造一个 value: -1.0 的计数器。newtype 和私有字段加访问方法是更稳的写法,第五篇还会用到。

局部更新用结构体更新语法,配合 Default 很省事:

#[derive(Default)]
struct Config {
    host: String,
    port: u16,
    retries: u32,
}

fn main() {
    let c = Config {
        host: String::from("127.0.0.1"),
        port: 8080,
        ..Default::default()
    };
    println!("{}:{} retries={}", c.host, c.port, c.retries);
}
127.0.0.1:8080 retries=0

..Default::default() 会为剩下的字段填入默认值。注意它是「移动」而不是「复制」:如果被填的字段是 String,那个默认值的所有权也一起搬过来了。

最容易踩的坑是「部分移动」。下面这段是有意写错的:

struct Event {
    level: Level,
    message: String,
}

fn main() {
    let e = Event {
        level: Level::Warn,
        message: String::from("disk 91%"),
    };
    let msg = e.message;          // 把 message 移走
    println!("{:?} {}", e.level, msg);
    println!("{}", e.message);    // 再读整体,失败
}
error[E0382]: borrow of moved value: `e.message`
   |
18 |     let msg = e.message;
   |               --------- value moved here
...
20 |     println!("{}", e.message);
   |                    ^^^^^^^^^ value borrowed here after move
   |
   = note: move occurs because `e.message` has type `String`,
           which does not implement the `Copy` trait

人话版:String 背后是一块堆内存,把它赋给 msg 之后,msg 成了新的所有者,e.message 只剩一个空壳。编译器不允许你从空壳里读数据,因为读到的是已移交的内存。改法三条:改成 &e.message 借用;改成 e.message.clone() 复制;或者直接解构整个结构体,一次把字段都拿走。

字段还能单独移动,这一点和 Vec 不同:结构体的字段是各自独立的槽位,所以「移走一个字段、继续用另一个字段」是合法的,报错只在你想继续用被移走的那个字段、或者用整个结构体时才出现。

枚举:把「只有这几种」写进类型

上面 Kind 只用它来格式化输出,还没体现价值。真正的差别在加了第三种类型的时候:如果有人把 kind_str 的 match 漏了 Histogram,编译器会拒绝,而不是运行时打印出 unknown。这就是第四篇讲过的穷尽性,枚举让它变成编译期检查。

Rust 的枚举比其他语言强的地方是每个变体可以带数据,而且不同变体带的数据可以不同:

enum Command {
    Inc { name: String, delta: f64 },
    Set { name: String, value: f64 },
    Reset,
}

fn apply(cmd: Command) {
    match cmd {
        Command::Inc { name, delta } => println!("{name} += {delta}"),
        Command::Set { name, value } => println!("{name} = {value}"),
        Command::Reset => println!("全部清零"),
    }
}

这三条命令需要的字段并不一样,用三个结构体也行,但调用方就得自己判断「这条数据该塞进哪个结构体」,而且没有类型能表示「这三者之一」。枚举把「互斥的几种情况」打包成一个类型,match 再把它拆开,中间不会出现「既不是 A 也不是 B」的非法状态。

一个常见疑问:为什么不用字符串表示类型,比如 kind: "gauge"?因为字符串拼错要到运行时才暴露,而且没有穷尽性,新增类型时没有任何提示。枚举的代价是新增变体要改所有 match——但这是好事,编译器会把你带到每一处需要判断的地方。

还有一点要认识清楚:Option 和 Result 都是标准库里的枚举,Some/None、Ok/Err 就是变体。所以上一篇讲的「用 match 处理 None」,和这里讲的是同一套机制,不是两个知识点。

trait:行为的契约

trait Sink 声明的不是数据,而是能力:「任何实现了 Sink 的类型,都保证有一个 write(&mut self, &Metric) 方法」。具体怎么实现由各类型自己决定,调用方只需要知道有这个能力。

默认方法让常见实现只写差异部分。flush 在内存 sink 里可能什么都不用做,在 HTTP sink 里要发一次请求;给一个空默认实现,前者就不用写了。默认方法里可以调用 trait 的其他方法,所以能写出「模板方法」式的逻辑。

trait 还能加约束,让实现方必须满足某些条件,比如 trait Sink: Send 表示「实现 Sink 的类型还必须能跨线程传递」。这在第九篇讲并发时会成为关键约束。

两个常见报错,先看「忘了实现」:

fn print_report<T: Report>(r: T) {
    println!("{}", r.name());
}

fn main() {
    print_report(Disk);   // Disk 没有 impl Report
}
error[E0277]: the trait bound `Disk: Report` is not satisfied
  |
19 |     print_report(Disk);
   |     ------------ ^^^^ unsatisfied trait bound
   |
help: the trait `Report` is not implemented for `Disk`
help: the trait `Report` is implemented for `Cpu`

人话版:函数要求「传进来的东西必须会 report」,Disk 不会。注意编译器顺手告诉你「Cpu 倒是实现了」,这是它在猜你想传哪个类型——通常意味着你复制粘贴时改漏了一处。

再看「实现了但方法找不到」:trait 定义在子模块里,调用处忘了 use。

mod repr {
    pub trait Format {
        fn render(&self) -> String;
    }
    // ... impl Format for Line 略
}

fn main() {
    let l = repr::Line;
    println!("{}", l.render());
}
error[E0599]: no method named `render` found for struct `Line` in the current scope
   |
 3 |         fn render(&self) -> String;
   |            ------ the method is available for `Line` here
   |
   = help: items from traits can only be used if the trait is in scope
help: trait `Format` which provides `render` is implemented but not in scope;
      perhaps you want to import it
   |
 1 + use crate::repr::Format;

这条报错非常容易误判成「方法没实现」。实际实现是有的,只是 trait 不在当前作用域,方法查找根本看不到它。C++ 里方法属于类,Rust 里方法可能属于 trait,这是两种模型最直观的差别。看到 items from traits can only be used if the trait is in scope,直接加 use 就好。

最后一条规则值得记住:孤儿规则。你只能为自己定义的类型实现 trait,或者为本地 trait 实现任意类型,但不能「给外来类型实现外来 trait」。目的是防止两个库各自实现同一组合,导致下游编译时冲突。想绕过就用 newtype,把外来类型包一层再实现。

泛型还是 dyn:两种分发的代价

上面 report 用的是泛型。同一个需求也能写成 trait 对象:

fn report(sink: &mut dyn Sink, metrics: &[Metric]) {
    for m in metrics {
        sink.write(m);
    }
}

两者都能跑,区别在编译后发生什么。泛型的写法,编译器会为每个实际类型各生成一份 report 代码,这叫单态化:调用是直接调用,能内联,没有运行时代价,但类型多时代码体积会涨。dyn 的写法只生成一份代码,运行时通过虚表(vtable)查「这个对象的 write 在哪里」,代价是一次间接调用,通常无法内联。

泛型 S: Sink

编译期确定具体类型,零成本抽象,适合内部实现、性能敏感路径。缺点是每个类型一份代码,编译变慢,而且泛型约束会把类型信息一路传进签名。

trait 对象 dyn Sink

运行期决定,一份代码支持任意实现,适合插件式、配置驱动的场景(比如按配置选 stdout 还是 HTTP)。代价是间接调用和一堆 dyn 兼容性限制。

dyn 不是随便什么 trait 都能用。下面这段有意失败的代码,trait 方法带泛型参数:

trait Store {
    fn put<T: ToString>(&mut self, key: &str, value: T);
}

fn main() {
    let mut s: Box<dyn Store> = Box::new(Memory);
    s.put("cpu", 91);
}
error[E0038]: the trait `Store` is not dyn compatible
  |
14 |     let mut s: Box<dyn Store> = Box::new(Memory);
   |                        ^^^^^ `Store` is not dyn compatible
   |
note: for a trait to be dyn compatible it needs to allow building a vtable
  |
 2 |     fn put<T: ToString>(&mut self, key: &str, value: T);
   |        ^^^ ...because method `put` has generic type parameters
   = help: consider moving `put` to another trait

为什么不行:虚表是一张「方法名到地址」的表,每个方法一行。泛型方法对每个 T 都有一份不同实现,表里放不下无限多行。同理,返回 Self、把 Self 当参数的方法也不行。dyn 兼容的 trait 要求方法签名在编译期就固定下来。

解决办法是把泛型方法从 trait 里挪走,改成接受具体类型,比如 value: &dyn ToString,或者干脆拆成两个 trait。报错的 help 就给了这个建议。注意「dyn compatible」是较新的说法,老版本和很多博客里叫「object safe」,指的是同一件事。

选型经验:模块内部的实现用泛型,跨模块的接口、需要运行期替换的地方用 dyn。不要一上来就 Box<dyn Trait>,那会把编译期的类型检查换成运行期的间接调用,还丢掉内联机会。

现象对照

现象真实原因第一步查什么
missing field `value` in initializer of `Metric`结构体字面量漏了字段,Rust 没有「自动默认值」补齐字段,或加 ..Default::default()
borrow of moved value: `e.message`字段已移动到别的变量,原结构体只剩空壳找 value moved here 那行,改成借用或 clone,或整体解构
no method named `render` found ... in the current scopetrait 没 use 进来,方法查找看不到看报错末尾的 perhaps you want to import it,补 use
the trait bound `Disk: Report` is not satisfied该类型没有实现所需 trait确认类型名是否写错;真没实现就补 impl
the trait `Store` is not dyn compatibletrait 里有泛型方法、Self 返回值等,无法建虚表看 note 里点名的那个方法,把它移出 trait 或改签名
non-exhaustive patterns: `Reset` not covered枚举新增变体,match 没跟上补分支,别用 _ 掩盖,否则以后新增变体也不会提醒
cannot move out of `self.field` behind a shared reference在 &self 方法里试图拿走字段所有权改 &mut self/self,或用 clone/take
type annotations needed / cannot infer type泛型或 collect 的目标类型没有线索给变量或返回值加显式类型

边界与代价

结构体的第一层代价是「字段可见性要设计」。全 pub 写着省事,但外部随时能构造出非法状态,new 里的校验形同虚设。反过来全私有、每个字段配一对 getter/setter,又变成 Java 式的样板代码。判断标准:字段之间有没有必须一起满足的约束(比如 value 不能为负、start 必须早于 end),有就收起来,只暴露操作;没有就 pub。

第二层代价是 trait 容易被滥用。见过把每个结构体都套一个 trait 的项目,最后 dyn 满天飞,调用链断了内联,性能还不如直接写死。trait 的价值在「有多个实现且需要替换」,只有一个实现时,先写具体类型,等第二个实现出现再抽。

第三层代价是 dyn 的间接性。虚表调用本身不贵,贵在它阻止内联和跨 crate 优化,热点循环里每个元素一次虚调用,差别就出来了。压测时如果发现某个泛型改成 dyn 后 QPS 掉了,先怀疑这里。

第四层是 derive 的隐含语义。#[derive(PartialEq)] 对含 f64 的结构体也会照常生成,但 NaN != NaN,用它做测试断言会莫名其妙失败;#[derive(Hash)] 配合 f64 根本编译不过,因为 f64 没实现 Hash。派生出来的行为要看一眼,别默认「等于我想要的」。

最后,枚举不是越多变体越好。十几个变体、每个带一堆字段的枚举,本质是一个没拆开的联合体,match 会长得吓人。按「谁会处理它」来拆:不同消费者关心的变体,本来就应该分到不同枚举或不同层级。

小结

结构体描述数据形状,枚举描述互斥的几种情况,trait 描述行为能力,三者拼起来就是 Rust 的建模语言。写代码时先问「这是一条记录还是一组选择」,再问「这个行为是内部实现还是对外契约」,类型基本就定了。

泛型和 dyn 是同一件事的两种分发:泛型把类型信息交给编译期,换来零成本和内联;dyn 把选择推到运行期,换来一份代码支持多实现。选错的典型症状是「为了抽象而抽象」,或者「泛型参数污染了整个调用链」。

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

  1. 给 Kind 加一个 Histogram 变体,只改枚举不跑 cargo build 看编辑器/编译器指出哪些 match 要改,体会穷尽性的作用。
  2. 写一个 MemorySink 保存 Vec<Metric>,用 report(&mut mem, &metrics) 调用后断言长度,验证 trait 对象的写法。
  3. 把 report 从泛型改成 &mut dyn Sink,再用 cargo bench 或简单计时比较两者在十万条指标上的差异(未做严格基准,只做量级观察)。
  4. 给 Metric 实现 Display,然后 println!("{m}"),比较和 Debug 输出的区别。
  5. 故意在 trait Sink 里加一个 fn put<T: ToString>(...),把 Box<dyn Sink> 用起来,读一遍 E0038 的 note。

下一篇讲错误处理:Result、? 与 panic 的边界。这一篇里 Sink::write 返回 (),等于假设「写一定成功」;一旦要推远端,网络会超时、连接会断,这个假设就不成立了。错误该用什么类型表达、什么时候用 ? 往上抛、什么时候该 panic,是下一篇的主题。