AI 可能出错，请核对原文 在独立页面打开
问文档
目录

struct 与 trait

11 分钟
本页目录

struct 描述数据与类型身份，trait 描述可要求的行为以及关联类型、常量。Rust 通过 impl 把行为与类型连接起来，不需要以类继承树组织所有复用关系。

三种结构与新类型

具名字段适合需要字段含义的数据；元组结构适合位置明确的包装；单元结构不带字段，可作为标记或无状态策略。type Meters = f64 只是别名，struct Meters(f64) 才是不同类型。

外部原始输入例如 f64 米数1构造函数验证拒绝 NaN、无穷与负数2私有字段的 Meters方法可以依赖构造时建立的不变量3仅改类型名字不够；若公开任意写入字段，调用方仍能绕开验证。新类型通过受控入口维护语义 
mod units {
    #[derive(Debug, Clone, Copy, PartialEq)]
    pub struct Meters(f64);
    impl Meters {
        pub fn new(value: f64) -> Option<Self> {
            if value.is_finite() && value >= 0.0 { Some(Self(value)) } else { None }
        }
        pub fn value(self) -> f64 { self.0 }
    }
}
fn main() {
    let distance = units::Meters::new(12.5).unwrap();
    assert_eq!(distance.value(), 12.5);
    assert!(units::Meters::new(-1.0).is_none());
    assert!(units::Meters::new(f64::NAN).is_none());
}

模块外不能直接构造或修改私有字段，因而只能通过指定入口建立值。新类型阻止把 Feet 直接当作 Meters 传参，但若暴露原始字段后随意相加，单位错误仍可能发生。

单字段包装不自动承诺与内部类型相同 ABI；需要满足相应布局约束时可研究 repr(transparent)，而不是把“零成本”当作所有表示细节的保证。

新类型的不变量要覆盖所有修改入口

Meters::new 拒绝负数、NaN 和无穷，建立的是“当前值有限且非负”的不变量。如果后续添加 add 方法并直接执行 f64 加法，两个有限值的和仍可能溢出为无穷，因此方法也应重新验证结果。

是否提供 DerefMut<Target = f64> 同样影响封装：它会允许调用者直接写入任意 f64，绕过构造验证。序列化反序列化、From/TryFrom、默认值和算术 trait 也都是创建或修改入口；不是私有字段一写就自动完成整个不变量证明。

下面用有限整数范围说明“先验证、后赋值”的失败行为。set 返回错误时保留旧值，调用者不必猜失败后对象是否已被部分修改。

mod limits {
    #[derive(Debug, PartialEq)]
    pub struct Percent(u8);
    impl TryFrom<u16> for Percent {
        type Error = &'static str;
        fn try_from(value: u16) -> Result<Self, Self::Error> {
            if value <= 100 { Ok(Self(value as u8)) } else { Err("out of range") }
        }
    }
    impl Percent {
        pub fn value(&self) -> u8 { self.0 }
        pub fn set(&mut self, value: u16) -> Result<(), &'static str> {
            let checked = Self::try_from(value)?;
            *self = checked;
            Ok(())
        }
    }
}
fn main() {
    let mut value = limits::Percent::try_from(40).unwrap();
    assert_eq!(value.set(101), Err("out of range"));
    assert_eq!(value.value(), 40);
    value.set(100).unwrap();
    assert_eq!(value.value(), 100);
}

From 适合无失败且符合转换语义的情况，TryFrom 把可能失败明确写进类型；不要为了方便 .into() 就把非法值静默截断成另一含义。这里 as u8 放在已经检查 ≤100 的分支内，安全范围由前置条件建立。TryFrom

结构更新语法并不调用 Clone

Config { retries: 5, ..old } 只从 old 取得没有显式提供的字段：Copy 字段复制，其他字段移动。它不是克隆整个对象，也不是继承另一个实例。

struct Config { endpoint: String, retries: u8 }
fn main() {
    let old = Config { endpoint: "localhost".into(), retries: 2 };
    let next = Config { retries: 5, ..old };
    assert_eq!(next.endpoint, "localhost");
    assert_eq!(next.retries, 5);
    // endpoint 已移走，但 retries 没有被移走，可以单独读取。
    assert_eq!(old.retries, 2);
}

此后不能再借用整个 old 来打印或调用依赖完整对象的方法。更新语法还受字段可见性和 Drop 等规则影响；模块外不能通过 ..old 绕过私有字段来构造对象。Struct update

trait 声明能力，impl 提供实现

trait 方法可以有默认实现，关联类型通常由实现指定；默认方法能使用 trait 已承诺的能力。&self 借用、&mut self 独占借用、self 消费值，都是接口行为的重要组成部分。

trait Summary {
    fn summary(&self) -> String;
    fn decorated(&self) -> String { format!("[{}]", self.summary()) }
}
struct Point { x: i32, y: i32 }
impl Summary for Point {
    fn summary(&self) -> String { format!("{},{}", self.x, self.y) }
}
fn render<T: Summary>(item: &T) -> String { item.decorated() }
fn main() {
    assert_eq!(render(&Point { x: 2, y: 3 }), "[2,3]");
}

编译器能检查签名与类型要求，不会证明所有业务约定。比如某个方法承诺结果有序，或 Eq/Hash 必须一致，这些语义仍由实现者维护。trait 不是只能列出一组函数名字。Traits

接收者也是资源生命周期设计

&self：借出共享访问可读取接口允许的数据；内部可变性另有规则&mut self：借出独占访问方法负责维护不变量；返回前可以检查后再提交修改self：交出这个值方法接收者决定调用者交出什么适合 finish / into_inner；消费后不能继续按原值使用接收者约束属于接口；能通过编译并不证明方法遵守排序、等价或错误恢复等语义。

借用和消费并不是写法偏好。finish(self) 表示对象进入最终阶段，调用方交出所有权；finish(&mut self) 则需要定义完成后对象还处于什么可用状态。对于可重复使用的缓冲，后者可能合适；对于不能重复提交的构建器，前者更易表达意图。

共享引用也不绝对等于“方法没有任何修改”：Cell、RefCell、Mutex 等内部可变性允许按各自规则改变内部状态。trait 的文档应补充线程、重入、错误后状态和副作用约束，不能仅凭 &self 推断纯函数。

相同方法名：用完全限定写法消除歧义

trait HumanLabel { fn label(&self) -> &'static str; }
trait MachineLabel { fn label(&self) -> &'static str; }
struct Device;
impl HumanLabel for Device { fn label(&self) -> &'static str { "device" } }
impl MachineLabel for Device { fn label(&self) -> &'static str { "dev-7" } }
fn main() {
    let value = Device;
    assert_eq!(<Device as HumanLabel>::label(&value), "device");
    assert_eq!(<Device as MachineLabel>::label(&value), "dev-7");
}

方法调用会结合自动解引用、自动借用和作用域内可见 trait 搜索候选；“永远先选固有方法”是过度简化，因为不同接收者候选有先后顺序。存在歧义时，明确类型、trait 和接收者比盲目添加 clone 更有帮助。方法查找

derive：生成实现，也引入约束

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
struct GridPoint { x: i32, y: i32 }

fn main() {
    let point = GridPoint { x: 1, y: 2 };
    assert_eq!(point, point);
    let mut points = std::collections::HashSet::new();
    points.insert(point);
    assert!(points.contains(&point));
}

换成 f64 字段后，直接 derive Eq、Hash 就不可用；NaN 等浮点语义需要明确处理，不能机械照搬整数类型的派生列表。derive Clone 也不是自动递归“深复制”：Arc 字段的 clone 仍只增加共享所有者。

derive 是宏机制：标准库提供一组内建派生，Serialize 等来自第三方过程宏。自动生成的泛型约束有时比手工实现保守，必要时应查看实际约束并手写实现，而不是给所有泛型参数随意加 Clone。

派生约束可能比字段真正所需的约束更强

例如 Arc<T> 可以在 T 不实现 Clone 时 clone，因为复制的是共享所有权，不是 T 本身。为包含 Arc 的泛型包装直接 derive Clone，生成的实现可能要求 T: Clone；手写实现可以表达更准确的约束。

use std::sync::Arc;
struct Shared<T>(Arc<T>);
impl<T> Clone for Shared<T> {
    fn clone(&self) -> Self { Self(Arc::clone(&self.0)) }
}
struct NotClone { value: u32 }
fn main() {
    let a = Shared(Arc::new(NotClone { value: 7 }));
    let b = a.clone();
    assert!(Arc::ptr_eq(&a.0, &b.0));
    assert_eq!(b.0.value, 7);
    assert_eq!(Arc::strong_count(&a.0), 2);
}

这里没有对 NotClone 加 Clone，也没有复制底层对象。是否要共享、独立复制或禁止复制，取决于资源语义，不能把“derive 能生成”当作接口选择的理由。Clone 派生

Eq 与 Hash 是跨方法的共同契约

若 a == b，则它们必须得到相同 hash；反过来不成立，因为哈希碰撞允许存在。若只用 user_id 判断相等，却把可变 display_name 一起哈希，两个被判定相等的键可能落入不同查找路径，破坏 HashMap/HashSet 的使用假设。

希望的语义实现方向
所有字段参与值相等对满足条件的字段统一 derive PartialEq/Eq/Hash
只按稳定 ID 相等对比较和哈希使用同一组身份字段
大小写无关标识构造时规范化，或使用一致的比较/哈希规则
允许浮点特殊值先选择 NaN、±0 等语义，再选择包装和实现

键插入集合后，不应通过内部可变性改变决定 Eq/Hash 的内容。标准库将此类违反契约视为逻辑错误；一般 safe trait 的契约违反不应被 unsafe 代码直接假定为不可发生并据此制造内存不安全。Hash 契约、PartialEq 契约

相等的键为什么还可能查不到？

trait 的正确性有时跨越两个实现。让 Eq 忽略大小写、Hash 保留大小写，就可能把“相等”的键送往不同候选位置。下图故意允许这种错误组合，帮助区分“签名能编译”和“行为共同遵守契约”。哈希碰撞允许存在，反方向的要求才是关键。

正在呈现知识画面
相等的键为什么还可能查不到？

Eq 判定相等的键必须产生相同哈希；否则查找可能到达不同候选桶。

孤儿规则与实现重叠

trait 实现要同时满足孤儿规则与无冲突要求。粗略地说，trait 是本地定义的，或者涉及符合规则的本地类型；对泛型实现还有覆盖与参数顺序要求。检查发生在编译期的 trait 一致性规则中，不是等链接器随机挑一个实现。实现一致性

实现形态在当前 crate 中的典型结果
外部 trait for 本地 MyType可以，仍要避免重叠
本地 MyTrait for 外部 String可以，仍要避免重叠
外部 Display for 外部 String不允许
外部 Display for Vec不允许；Vec 不因内部含本地类型就成为本地类型

Box 等 fundamental 类型在规则中有特定处理，不能推广为“任意泛型容器只要参数本地就可以”。需要为外部容器提供自己的展示方式时，新类型通常清楚：

use std::fmt;
struct Numbers(Vec<i32>);
impl fmt::Display for Numbers {
    fn fmt(&self, output: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(output, "{:?}", self.0)
    }
}
fn main() {
    assert_eq!(Numbers(vec![1, 2]).to_string(), "[1, 2]");
}

即使 trait 是本地的，impl MyTrait for T 与某个更具体实现也可能重叠；孤儿规则通过不意味着随意覆盖合法。

约束把实现能力交给泛型调用方

T: Summary + Clone 表示同时要求两种能力，where 子句只是更适合复杂关系的书写方式。父 trait 表达前置能力，不是继承结构字段。关联类型的约束与 dyn 对象限制分别见 关联类型与 GAT 和 动态分发。

设计公共 trait：把可实现空间也当作 API

定义 trait 相当于允许调用者依赖它，也可能允许下游为自己的类型实现它。新增无默认实现的方法会让下游实现不完整；增加默认方法也可能带来名称冲突、行为变化或 dyn compatibility 变化，不能简单认定“有默认实现就无风险”。

覆盖式实现如 impl<T: Display> MyTrait for T 为一大类类型提供能力，也占用了这些类型再写特定 MyTrait 实现的空间。它不是运行时插件优先级规则，不能指望更具体的 impl 自动覆盖泛型 impl；稳定 Rust 的一致性检查会拒绝相应重叠。

如果只打算允许库自己实现，可以采用有意的 sealed trait 设计；若希望外部扩展，就应尽量让必需方法少而稳定，并把可组合的便利方法放在合理位置。封闭和开放各有用途，应通过文档说明哪些能力是承诺、哪些是扩展点。Cargo SemVer 与 trait 变更

struct 与 trait 的组合最有价值的地方，是将数据所有权、不变量和行为契约分开定义，再通过受控的 impl 接起来。一个接口即使类型检查通过，也仍要有一致的相等/哈希、失败后状态和演进约定，调用者才能可靠地依赖它。

链接预览

新窗口打开