Rust 常用 Trait：从 prelude 到 std 的工程选型

trait 不是只在写泛型时才会遇到。#[derive]、==、for、?、+、println!、文件读写与线程边界，背后都是标准库 trait 的约定。本篇按工程中实际遇到的顺序整理 prelude 与 std 的高频 trait：先知道哪些名称已在作用域，再根据数据语义、API 边界和资源行为选择实现。

本文是标准库 trait 的统一参考。泛型与 trait 讲抽象边界、静态分发与 dyn Trait；Unsafe 讲 unsafe 与 Send / Sync 的安全契约。

先建立地图：prelude 不等于全部标准库 trait

prelude 是编译器自动放入每个模块作用域的一组名称。它让常用 trait 的方法可直接解析，但不代表所有标准库 trait 都无需 use。例如 Clone、Iterator、From 已在 prelude；Display、Read、Write、Add 和 Error 仍需从对应模块显式导入。

来源	高频 trait	主要出现的位置
prelude：数据与比较	`Clone`、`Copy`、`Debug`、`Default`、`PartialEq`、`Eq`、`PartialOrd`、`Ord`	`derive`、比较、排序、调试
prelude：转换与遍历	`From`、`Into`、`TryFrom`、`TryInto`、`AsRef`、`AsMut`、`ToOwned`、`ToString`、`Iterator`、`IntoIterator`	API 参数、`for`、`collect`
prelude：编译器边界	`Sized`、`Send`、`Sync`、`Unpin`、`Drop`、`Fn`、`FnMut`、`FnOnce`	泛型 bound、闭包、并发、析构
`std::fmt` / `std::ops`	`Display`、`Write`、`Add`、`Index`、`Deref`、`Drop`	格式化、运算符、智能指针
`std::borrow` / `std::convert`	`Borrow`、`BorrowMut`、`From`、`TryFrom`	异构查找、边界转换
`std::io` / `std::error`	`Read`、`BufRead`、`Write`、`Seek`、`Error`	文件、网络、错误链
`std::future`	`Future`	`async` / `.await` 的异步计算协议

阅读和设计时先问三件事：这个 trait 是在描述数据本身的语义、函数所需的能力，还是编译器必须相信的安全性质？三类约定的实现成本和错误后果完全不同。

领域类型：先从可派生 trait 开始

大多数领域类型不需要手写很多 trait。先根据真实用途派生最小集合；只有字段比较规则、文本格式或默认状态具有额外业务语义时，才手写 impl。

use std::collections::{BTreeSet, HashSet};

#[derive(
  Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash,
)]
struct JobId(u64);

fn main() {
  let first = JobId(7);
  let second = first; // Copy 后 first 仍可用。
  assert_eq!(first, second);

  let mut hash_ids = HashSet::new();
  hash_ids.insert(first); // 需要 Eq + Hash。

  let mut tree_ids = BTreeSet::new();
  tree_ids.insert(first); // 需要 Ord。
}

trait	承诺的语义	默认建议
`Debug`	面向开发者的结构化诊断输出	几乎总是 `derive`。
`Clone`	显式复制一个独立值	复制有业务意义时实现；它可能分配并复制堆数据。
`Copy`	赋值、传参时可隐式按位复制	仅用于小型、无资源所有权的纯值；它要求同时是 `Clone`。
`PartialEq` / `Eq`	相等比较；`Eq` 还承诺自反、对称、传递	需要比较时派生；含 `f32` / `f64` 的类型通常只能是 `PartialEq`。
`PartialOrd` / `Ord`	排序；`Ord` 要求任意两个值都可比较	作为 `BTreeMap` / `BTreeSet` 键时需要 `Ord`。
`Hash`	写入哈希状态	作为 `HashMap` / `HashSet` 键时与 `Eq` 一起派生。

`Debug`、`Display` 与 `ToString`

Debug 的输出服务日志、断言失败和临时诊断，格式不应被当作稳定协议。Display 则服务面向用户的文本、CLI 或错误信息，通常要手写。实现了 Display 后，标准库的 blanket impl 会自动提供 ToString；不要再为同一类型手写 ToString。

use std::fmt;

#[derive(Debug)]
struct JobId(u64);

impl fmt::Display for JobId {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    write!(f, "job-{}", self.0)
  }
}

fn main() {
  let id = JobId(7);
  assert_eq!(format!("{id:?}"), "JobId(7)");
  assert_eq!(id.to_string(), "job-7");
}

不要因为某个类型“可以打印”就实现 Display。例如包含密钥、二进制载荷或内部状态的类型，Debug 也许应脱敏，Display 则可能根本不应存在。

`Default`：默认值必须可直接使用

Default 不是“所有字段取零值”，而是类型的自然、安全初始状态。配置对象通常适合；已验证的 ID、金额、连接或文件句柄通常不适合。

use std::time::Duration;

#[derive(Debug)]
struct RetryPolicy {
  max_attempts: u8,
  delay: Duration,
}

impl Default for RetryPolicy {
  fn default() -> Self {
    Self {
      max_attempts: 3,
      delay: Duration::from_secs(1),
    }
  }
}

..Default::default() 只应覆盖确实可省略的配置字段。若默认值会掩盖业务遗漏，让构造函数要求调用方显式传入更安全。

相等、排序与哈希必须彼此一致

Eq 是 PartialEq 的更强承诺，Ord 是 PartialOrd 的更强承诺。浮点 NaN != NaN，且与任何值都不可排序，因此浮点类型不能直接实现 Eq / Ord。需要用浮点作集合键或确定排序时，应先定义清楚 NaN 的业务规则，再用专用包装类型或显式比较器。

Hash 与 Eq 有硬约束：若 a == b，则二者必须写入相同的哈希序列。所以自定义相等规则时，Hash 也必须按同一组字段实现；不确定时，两个 trait 一起 derive 最稳妥。

转换与借用：区分拿走值和借出视图

转换 trait 的选择直接影响所有权、分配与错误路径。不要只因调用写起来短，就把不同语义混在一起。

trait	做什么	实现建议
`From<T>` / `Into<U>`	消耗或移动值，构造另一类型	实现 `From`；对应 `Into` 会自动获得。
`TryFrom<T>` / `TryInto<U>`	校验或窄化后转换	用关联类型 `Error` 返回失败原因。
`AsRef<T>` / `AsMut<T>`	借出廉价的共享 / 可变视图	泛型参数边界常用，不转移所有权。
`Borrow<T>` / `BorrowMut<T>`	借出且保持比较、排序、哈希等价	主要用于 `HashMap` / `BTreeMap` 异构查找。
`ToOwned`	从借用创建拥有值	`str::to_owned()`、切片转 `Vec` 等标准模式。

`From` 与 `TryFrom`

实现端优先选 From 或 TryFrom，而不是 Into 或 TryInto：标准库会通过 blanket impl 补上反向调用接口。From 应是无条件、语义明确的转换；需要校验、会截断或可能失败时使用 TryFrom。

#[derive(Debug, PartialEq, Eq)]
struct Port(u16);

impl TryFrom<u16> for Port {
  type Error = &'static str;

  fn try_from(value: u16) -> Result<Self, Self::Error> {
    if value == 0 {
      Err("port must not be zero")
    } else {
      Ok(Self(value))
    }
  }
}

fn main() {
  assert_eq!(Port::try_from(8080), Ok(Port(8080)));
  assert!(Port::try_from(0).is_err());
}

不要在 From 中连接网络、读文件或 panic。它应只描述值到值的确定转换；有副作用的初始化应命名为 connect、load 或 try_new。

`AsRef` 与 `Borrow` 不可互换

文件 API 常接受 impl AsRef<Path>，从而兼容 &str、String、&Path 与 PathBuf。调用方仍拥有原值，函数只临时借用路径。

use std::path::Path;

fn is_log_file(path: impl AsRef<Path>) -> bool {
  path.as_ref().extension().is_some_and(|ext| ext == "log")
}

fn main() {
  assert!(is_log_file("logs/app.log"));
}

Borrow 更严格：借出的视图必须和原类型拥有相同的 Eq、Ord、Hash 语义。正因如此，HashMap<String, V> 可以用 &str 查找而不用临时分配 String。

use std::collections::HashMap;

fn main() {
  let mut ports = HashMap::new();
  ports.insert(String::from("http"), 80);

  assert_eq!(ports.get("http"), Some(&80));
}

`Deref` 不是通用转换 trait

Deref / DerefMut 支持解引用和借用强转，是 Box<T>、Rc<T>、Arc<T> 等智能指针的核心能力。它会让目标类型的方法自动可见，因此只在包装类型确实应该像指针一样透明访问目标时实现。

不要给 UserId(String)、Money(Decimal) 这类 newtype 实现 Deref 来少写 .0：这会泄漏内部类型的整套方法，破坏本应用 newtype 建立的语义边界。

运算、调用与析构：语言语法背后的 trait

std::ops 中的 trait 会被运算符语法调用。实现它们是在给类型增加一种新的语言级表达式，应让表达式读起来符合领域直觉，而非仅仅“能编译”。

表达式	trait	何时适合
`a + b`、`a += b`	`Add`、`AddAssign`	两值相加有明确且无歧义的领域含义。
`a[i]`、`a[i] = v`	`Index`、`IndexMut`	索引必然有效或越界应当是编程错误。
`-a`、`!a`	`Neg`、`Not`	语义与数学负号、逻辑非一致。
`f()`	`Fn`、`FnMut`、`FnOnce`	闭包和可调用对象的调用能力。

use std::ops::Add;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Bytes(u64);

impl Add for Bytes {
  type Output = Self;

  fn add(self, rhs: Self) -> Self::Output {
    Self(self.0 + rhs.0)
  }
}

fn main() {
  assert_eq!(Bytes(3) + Bytes(5), Bytes(8));
}

Index 返回引用且允许越界 panic；若“找不到”是正常输入，应提供 get 返回 Option，不要只为了下标语法而隐藏失败路径。

`Fn`、`FnMut`、`FnOnce`

闭包根据捕获方式自动实现一个或多个调用 trait。它们的能力层级是 Fn: FnMut: FnOnce：可多次不可变调用的闭包最强，消耗捕获值的闭包只能调用一次。设计泛型 API 时应选择函数体真正需要的最弱 bound。

fn run_once<F>(job: F) -> String
where
  F: FnOnce() -> String,
{
  job()
}

fn apply_twice<F>(mut f: F, value: i32) -> i32
where
  F: FnMut(i32) -> i32,
{
  let next = f(value);
  f(next)
}

若 API 只调用一次，就写 FnOnce，它也能接收 Fn 与 FnMut 闭包；不应无理由要求 Fn，否则会拒绝需要 move 捕获资源的合法调用者。

`Drop`：只做不会失败的释放

Drop::drop 在值离开作用域时自动执行，用于归还句柄、释放堆内存等。不能直接调用 .drop()，需要提前销毁时写 std::mem::drop(value)。

Drop 没有返回 Result 的位置，因此文件 flush、事务提交、网络关闭等可能失败的操作必须暴露为显式 flush、commit 或 close 方法；Drop 只做兜底释放，并避免 panic。

迭代：`for` 与 `collect` 的协议

Iterator 只要求实现 next，大量适配器和消费方法由默认实现提供。IntoIterator 决定一个值、共享借用或可变借用如何进入 for 循环；FromIterator 则是 collect() 构造目标集合的基础。

fn main() {
  let ids = vec![1, 2, 3];

  for id in &ids {
    assert!(*id > 0); // 借用元素，ids 仍可用。
  }

  let doubled: Vec<_> = ids.into_iter().map(|id| id * 2).collect();
  assert_eq!(doubled, vec![2, 4, 6]);
}

trait	作用
`Iterator`	产出 `Item`；`map`、`filter`、`sum` 等建立在 `next` 上。
`IntoIterator`	`for value in collection` 的入口；要区分 `T`、`&T`、`&mut T` 三种消费方式。
`FromIterator`	`collect::<Vec<_>>()`、`collect::<HashSet<_>>()` 的目标构造协议。
`Extend`	把一个迭代器的元素原地追加到既有集合。
`DoubleEndedIterator` / `ExactSizeIterator`	提供反向迭代、精确长度等额外能力；只在承诺可实现时标注。

自定义容器通常应实现三份 IntoIterator：T 产出拥有值，&T 产出共享引用，&mut T 产出可变引用。具体实现与生命周期边界见迭代器与闭包。

I/O 与错误：用最小能力描述边界

std::io 的核心是按字节读取的 Read 与写入的 Write。读取文本行时，使用带内部缓冲的 BufRead；需要移动流位置时增加 Seek bound。它们都不在 prelude，签名中或调用处需要显式 use。

use std::io::{self, Read, Write};

fn copy_all<R, W>(mut input: R, mut output: W) -> io::Result<()>
where
  R: Read,
  W: Write,
{
  io::copy(&mut input, &mut output)?;
  output.flush()
}

trait	最小能力	常见误区
`Read`	从字节源读取	单次 `read` 不保证填满缓冲；需要填满时用 `read_exact`。
`BufRead`	带缓冲的读取	逐行读取应使用 `BufReader`，避免频繁系统调用。
`Write`	写入字节并 flush	单次 `write` 可能只写部分数据；完整写入用 `write_all`。
`Seek`	移动字节流游标	仅当业务确实依赖随机访问时要求它。
`fmt::Write`	向文本缓冲格式化写入	与 `io::Write` 不同；前者面向 UTF-8 文本，后者面向字节。

std::error::Error 表示可向上报告的错误类型；它要求 Debug 与 Display，并可通过 source() 暴露底层原因。库的错误枚举通常实现 From<io::Error> 等转换，让 ? 能将底层错误映射到本领域错误。

use std::error::Error;
use std::fmt;

#[derive(Debug)]
enum AppError {
  Io(std::io::Error),
}

impl fmt::Display for AppError {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    match self {
      Self::Io(error) => write!(f, "I/O error: {error}"),
    }
  }
}

impl Error for AppError {
  fn source(&self) -> Option<&(dyn Error + 'static)> {
    match self {
      Self::Io(error) => Some(error),
    }
  }
}

impl From<std::io::Error> for AppError {
  fn from(error: std::io::Error) -> Self {
    Self::Io(error)
  }
}

应用可用 thiserror 减少这些样板；库接口仍应明确每个错误变体与 source 链的语义。详见错误处理。

编译器与并发边界：不要轻易手写 marker trait

Sized、Send、Sync、Unpin 多数是 auto trait：编译器根据字段递归推导。它们并非普通的业务能力标签，而是类型布局、线程安全和地址稳定性的安全承诺。

trait	含义	日常写法
`Sized`	编译期知道大小	泛型默认包含 `T: Sized`；只在接收 DST 借用时写 `T: ?Sized`。
`Send`	值可安全转移到另一线程	由字段自动推导；线程任务常要求 `Send + 'static`。
`Sync`	`&T` 可安全跨线程共享	`Mutex<T>`、`RwLock<T>` 等用同步原语维护共享可变状态。
`Unpin`	被 `Pin` 包装后仍可移动	异步状态机和自引用类型的专门边界，通常无需手写。

unsafe impl Send 或 unsafe impl Sync 是在向所有调用者承诺不存在数据竞争、悬垂访问和错误别名。除非能写出并审查完整的不变量证明，否则应让编译器自动推导，或通过 Arc、Mutex、消息传递表达同步。

Future 不在 prelude。async fn、async 块会由编译器生成对应的状态机，日常业务代码通常返回 async fn 的结果并使用 .await，而不是手写 Future::poll；只有实现运行时、协议适配器或底层库时才需要直接处理它。异步取消、Pin 与轮询边界见并发与异步。

blanket impl、孤儿规则与实现清单

标准库会为“一整类满足条件的类型”提供 blanket impl。例如实现了 Display 的类型会自动获得 ToString，目标类型实现 From<T> 后，T 自动可 .into()。因此实现“源头 trait”比重复实现派生能力更好。

但不能为“外部 trait + 外部类型”写实现；这是孤儿规则，用来避免两个 crate 提供冲突实现。需要为 Vec<u8> 定义十六进制展示等本地语义时，定义 struct HexBytes(Vec<u8>); 这样的 newtype，再为它实现 Display。

为新领域类型选择 trait 时，按下面清单核对：

诊断需要：Debug。
复制需要：仅在复制语义明确时加 Clone；仅在隐式复制仍廉价时加 Copy。
集合键需要：哈希键派生 PartialEq + Eq + Hash；有序键再派生 Ord。
默认构造需要：默认值确实安全、可直接使用时才实现 Default。
文本协议需要：人类可读且稳定的文本才实现 Display。
边界转换需要：无条件用 From，有校验用 TryFrom，只借用用 AsRef。
并发需要：让字段决定 Send / Sync；不要以 unsafe impl 消除报错。

自测

为什么实现 Display 后不应再手写 ToString？
HashMap 的键为什么通常同时需要 Eq 与 Hash？
哪些情况应使用 TryFrom 而不是 From？
AsRef<Path> 与 Borrow<str> 的约束为什么不同？
一个只调用回调一次的函数为何应接收 FnOnce？
为什么 Index 不适合表示用户输入造成的“可能找不到”？
Read::read 与 Write::write 分别为什么不能承诺一次完成？
为什么不能为了跨线程编译通过就写 unsafe impl Send？

先建立地图：prelude 不等于全部标准库 trait

领域类型：先从可派生 trait 开始

Debug、Display 与 ToString

Default：默认值必须可直接使用