需求:给服务加一个指标上报模块。采集到的指标要能打到终端,方便本地调试;也要能存进内存,方便单元测试断言;将来还要推给远端。同一份数据,三个去处。
第一版写得很自然:一个结构体存一条指标,一个函数负责打印。加第二个去处时就卡住了——打印函数把「输出到终端」写死在里面,想换目标只能复制一份再改。这类「同一份数据、多种处理方式」的需求,正好对应 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] 是不可变切片,函数只读指标。写清楚这两个修饰词,调用方一眼能看出哪些数据会被改。
这个三段式结构就是后面所有讨论的地基:数据用结构体 + 枚举描述,行为用 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 scope | trait 没 use 进来,方法查找看不到 | 看报错末尾的 perhaps you want to import it,补 use |
the trait bound `Disk: Report` is not satisfied | 该类型没有实现所需 trait | 确认类型名是否写错;真没实现就补 impl |
the trait `Store` is not dyn compatible | trait 里有泛型方法、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 把选择推到运行期,换来一份代码支持多实现。选错的典型症状是「为了抽象而抽象」,或者「泛型参数污染了整个调用链」。
当天可以自己验证的练习:
- 给
Kind加一个Histogram变体,只改枚举不跑cargo build看编辑器/编译器指出哪些match要改,体会穷尽性的作用。 - 写一个
MemorySink保存Vec<Metric>,用report(&mut mem, &metrics)调用后断言长度,验证 trait 对象的写法。 - 把
report从泛型改成&mut dyn Sink,再用cargo bench或简单计时比较两者在十万条指标上的差异(未做严格基准,只做量级观察)。 - 给
Metric实现Display,然后println!("{m}"),比较和Debug输出的区别。 - 故意在
trait Sink里加一个fn put<T: ToString>(...),把Box<dyn Sink>用起来,读一遍 E0038 的 note。
下一篇讲错误处理:Result、? 与 panic 的边界。这一篇里 Sink::write 返回 (),等于假设「写一定成功」;一旦要推远端,网络会超时、连接会断,这个假设就不成立了。错误该用什么类型表达、什么时候用 ? 往上抛、什么时候该 panic,是下一篇的主题。