Newshot

如何绕过 Rust 的孤儿规则

Translation(model translation, not the source's own text)

如何绕过 Rust 的 Orphan Rule

  • Orphan Rule 实际上在防范什么?
  • 为什么两种常见的变通方案都不够 1. 把它内置到库中2. 自己用 NewType 包装
  • 1. 把它内置到库中
  • 2. 自己用 NewType 包装
  • 给 Trait 增加一个泛型槽位
  • 本地类型的位置很重要
  • 一个真正独立的 models Crate
  • 真实案例:这在 Kova 中如何运作

写 Rust 写得足够久,你必然会遇到 error[E0117]。

设想一个简单的日常场景。你引入了一个定义 ToJson trait 的序列化库,以及一个像 uuid 这样的第三方类型库。你想把 uuid::Uuid 转成 JSON,于是你很自然地写下:


        impl ToJson for uuid::Uuid {
    fn to_json(&self) -> String {
        format!("\"{}\"", self)
    }
}
      

然后编译器立刻拦住了你:


        error[E0117]: only traits defined in the current crate can be implemented for types defined outside of the crate
      

这就是 Rust 众所周知的 Orphan Rule。人们撞上这堵墙后,通常会抱怨编译器太死板,或者老老实实地把类型包进一个 NewType。但如果你仔细看看 Orphan Rule 实际是怎么运作的,它并不是死路。按设计,它留了一扇相当宽的门。

Orphan Rule 实际上在防范什么?

先抛开术语,Orphan Rule 背后的逻辑很简单:如果你想让一个类型实现某个 trait,那么这两样东西(类型或 trait)中至少有一个必须属于你自己的 crate。说白了,你不能替别人的类型制定规则。

假设 crate A 为 uuid::Uuid 实现了 ToJson,并输出带连字符的 UUID 字符串,而 crate B 也为 uuid::Uuid 实现了 ToJson,并输出不带连字符的 32 个原始十六进制字符。如果一个项目同时依赖 A 和 B,编译器在遇到 uuid.to_json() 时就有麻烦了:它该选哪个实现?

为了防止这种全局冲突,Rust 会强制执行 coherence,而 Orphan Rule 就是执行它的方式。规则本身没有错。随着依赖树增长,它可以防止 Rust 生态变得一团糟。问题在于,现实中的项目经常遇到一种非常常见的需求:让一个第三方类型实现另一个第三方 crate 中的 trait。类型和 trait 都不是你的,但像这样把库粘合在一起的情况一直都在发生。那么你能做什么呢?

为什么两种常见的变通方案都不够

目前,Rust 生态主要依赖两种变通方案。两者表面上似乎都能解决问题,但因为都没有触及根本原因,所以很快就会变得很别扭。

1. 把它内置到库中

许多基础 crate 都走这条路:既然用户自己不能写 impl,那就由 crate 在内部提供。因为 ToJson 定义在 crate 内部,所以为任何外部类型实现它都满足 Orphan Rule。打开这些 crate 中某一个的 Cargo.toml,你会看到一长串 feature flags:with-uuid、with-chrono、with-time、with-jiff、with-url、with-rust-decimal,等等。

乍一看这很有帮助,但它试图在一个 crate 内部枚举一个开放且不断变化的生态。这种做法有明显的局限,缺点很快就会显现:

  • 你永远不可能支持所有东西。今天社区偏爱 chrono,明天人们转向 jiff,下周你的团队又构建了自己的内部 Money 类型。如果库没有内置支持,你就只能等着发版,或者自己开一个 PR。
  • 版本锁定。当某个第三方类型 crate 提升主版本号时,你的整个依赖树都会被卡住,直到 trait crate 发布匹配的更新。
  • 硬编码行为。也许库默认把 DateTime<Utc> 序列化为 ISO-8601 字符串,而你的 API 规范要求使用以毫秒为单位的整数时间戳。因为实现位于库内部,你没有办法改变它。

2. 自己用 NewType 包一层

当库没有内置支持,或者它的默认行为不符合你的需求时,你就退回到熟悉的 NewType 模式:


        pub struct MyUuid(pub uuid::Uuid);

impl ToJson for MyUuid {
    fn to_json(&self) -> String {
        format!("\"{}\"", self.0)
    }
}
      

包一两个类型没什么问题。麻烦始于一个中等复杂度的领域模型同时混用了 Uuid、Url、DateTime、HashMap 和自定义领域类型。一旦你把所有东西都包成 MyUuid、MyUrl 和 MyDateTime,业务逻辑里就到处散落着 .0,你的时间都花在不停地包装和解包值上。很快就会让人厌烦。

NewType 在 Rust 里确实是个有用的模式,可以用来表达领域含义、隐藏内部实现或强制不变量。问题在于,当你只是为了安抚 Orphan Rule 而去包装那些本来根本不需要包装的类型时,代码很快就会膨胀。

那么,有没有办法让用户自行决定第三方类型如何实现某个 trait,而不必把所有东西都包进 NewType 里呢?

给 Trait 加一个泛型槽位

让我们回到那条规则:类型或 trait 必须有一个属于当前 crate。

许多开发者以为编译器在 impl Trait for Type 里只看 Trait 和 Type。事实上,在 Rust 的 Orphan Rule(RFC 2451)下,trait 自身的泛型类型参数也属于检查范围。

简单来说,在 impl Trait<P> for Type 中,只要 trait 的泛型参数里出现了一个本地类型,并且它之前没有未被覆盖的类型参数,编译器就知道这个实现专属于当前 crate。其他 crate 无法与之冲突,所以编译器会放行。

看这个例子:


        impl ToJson<MyApp> for uuid::Uuid {
    // ...
}
      

ToJson 是外部 trait,Uuid 是外部类型,但 MyApp 定义在当前 crate 中。由于它位于 trait 的泛型参数位置,这个 impl 满足 Orphan Rule。

沿着这个思路,库作者在设计 trait 时只需要多走一步:在 trait 上留一个泛型参数,作为给用户的扩展点。

例如:


        pub trait ToJson<Ctx = ()> {
    fn to_json(&self) -> String;
}
      

注意 Ctx = () 带有一个默认类型。当库为 i32、String 这类基础类型实现 ToJson 时,会把这些实现做成对任意 Ctx 都泛型:


        impl<Ctx> ToJson<Ctx> for i32 {
    fn to_json(&self) -> String {
        self.to_string()
    }
}

impl<Ctx> ToJson<Ctx> for String {
    fn to_json(&self) -> String {
        format!("\"{}\"", self)
    }
}
      

这样一来,普通用户甚至根本不会注意到 Ctx 的存在。一切行为都和以前完全一样,默认上下文是 ()。

当你确实需要接入第三方类型时,只需在你自己的 crate 里定义一个空的标记结构体:


        pub struct MyApp;
      

然后你就可以为你想要的任何第三方类型编写实现:


        impl ToJson<MyApp> for uuid::Uuid {
    fn to_json(&self) -> String {
        format!("\"{}\"", self)
    }
}

impl ToJson<MyApp> for chrono::DateTime<chrono::Utc> {
    fn to_json(&self) -> String {
        self.timestamp_millis().to_string()
    }
}
      

编译器看到这些会这样判断:ToJson 是外部的,Uuid 和 DateTime 是外部的,但 MyApp 是你 crate 本地的。其他 crate 无法用你的 MyApp 写出冲突的实现,所以全局一致性完全安全。代码直接就能编译通过。

你可以把这套转换设置想成一张关系网,以你本地的 MyApp 类型为根。一个形象的比喻是一串葡萄,MyApp 就是那根梗。一旦你抓住那根梗,上面挂着多少第三方类型(Uuid、Url、DateTime、HashMap 等等)都无所谓。你一提就是整串,编译器会把它们全部当作本地实现接受。

更好的是,你可以在同一个项目中定义多个 stem。例如,你的 HTTP API 层可以使用 ApiCtx 将时间戳格式化为字符串,而内部 RPC 层使用 RpcCtx 将它们格式化为整数时间戳。两套规则分别位于不同的上下文之下,在编译时完全隔离,零冲突。

需要注意的一个细节:local 类型必须是真正新定义的类型。为外部类型创建类型别名是行不通的。

Local 类型的位置很重要

此时,你可能认为只要把 local 类型 MyApp 放到 trait 泛型列表中的任何位置,就能一劳永逸地解决 Orphan Rule。大多数情况下确实如此。但如果你的 trait 有多个泛型参数,或者你想编写泛型 impl,就会遇到一个容易被忽视的顺序限制。

当编译器执行 Orphan Rule 检查时,它会按固定顺序扫描类型:首先是 Self 类型,然后是 trait 的第 1 个泛型参数,然后是第 2 个,依此类推。规则可以概括为一句话:在第一个 local 类型出现之前,不能出现裸泛型类型参数 T。

代码最能说明问题。假设某个外部 crate 定义了 ForeignTrait<A, B> 和 ForeignType,而你在本地定义了 MyApp:


        // ✅ Allowed: scans ForeignType, then hits local MyApp first; the trailing T is unrestricted
impl<T> ForeignTrait<MyApp, T> for ForeignType {}

// ❌ Error: hits a bare T before seeing MyApp
impl<T> ForeignTrait<T, MyApp> for ForeignType {}

// ❌ Error: hits a bare T right away in Self, before MyApp gets a chance
impl<T> ForeignTrait<MyApp, String> for T {}
      

这里唯一需要留意的词是 "bare"。在 Rust 术语中,这被称为未覆盖的类型参数(uncovered type parameter)。一个普通的 T 是未覆盖的。如果它被包裹在像 Vec<T> 这样的非基础具体类型中(像 &T 和 Box<T> 这样的内置基础类型不算),它就不再是未覆盖的,因此不会阻止其后出现的 local MyApp:


        // ✅ Allowed: T is covered by Vec, so it is not an uncovered type parameter
impl<T> ForeignTrait<Vec<T>, MyApp> for ForeignType {}
      

从库作者的角度来看,这意味着仅仅添加一个泛型槽位是不够的;你还需要把它放在正确的位置。如果你的 trait 有多个泛型参数,并且没有其他强有力的理由,请把上下文 Ctx 放在第一个类型参数的位置。这样,下游用户编写泛型实现时就可以避免大多数令人意外的 Orphan Rule 错误。

真正独立的 models Crate

一旦理解了这个机制,你就会发现它还解决了大型 Rust 代码库中一个顽固的架构难题。

随着项目增长,它通常会被拆分为一个 Cargo workspace:可能包含一个 API gateway crate、几个业务服务 crate,以及一个后台 worker crate。这些模块往往共享相同的数据结构,因此自然的做法是把这些 struct 提取到一个独立的 models crate 中。

传统上,在 Rust 中这样做很痛苦。假设 models 定义了一个包含 Uuid、Url 和 DateTime 字段的 Product 结构体。如果你的序列化库或 ORM 期望这些字段类型已经在 models 内部实现了其 trait,你就只剩下两个糟糕的选择:

  • 在 models 内部用 NewTypes 包装一切,并随之引入序列化库、数据库驱动以及其他重型依赖。本应只包含普通数据结构的 crate 最终却拥有了工作区中最重的依赖树。
  • 放弃拆分,把 models 和业务逻辑塞进同一个 crate。这在早期节省时间,但随着项目增长,依赖边界和编译时间会越来越难以管理。

有了泛型 Ctx 参数,这个结就解开了。在你独立的 models crate 内部,只需用原生类型定义 struct:


        // crate: models
pub struct Product {
    pub id: uuid::Uuid,
    pub created_at: chrono::DateTime<chrono::Utc>,
}
      

接着,你为 Product 写一个对任意 Ctx 开放的泛型实现(或者让 derive 宏生成它):


        impl<Ctx> ToJson<Ctx> for Product
    where
        uuid::Uuid: ToJson<Ctx>,
        chrono::DateTime<chrono::Utc>: ToJson<Ctx> {
    fn to_json(&self) -> String {
        format!(
            "{{\"id\":{},\"created_at\":{}}}",
            ToJson::<Ctx>::to_json(&self.id),
            ToJson::<Ctx>::to_json(&self.created_at),
        )
    }
}
      

注意这里的微妙之处:在 models crate 内部,Uuid 和 DateTime 尚未实现 ToJson,而这段代码仍然可以编译。

这是因为 models 只是声明了一份延迟契约:“后续无论谁使用它,只要你的上下文 Ctx 知道如何处理 Uuid 和 DateTime,Product 就会在你的上下文下自动支持 ToJson。”因此,models 保持完全轻量,不携带任何具体转换逻辑,并且编译得非常快。实际的转换被推迟到下游 service crate 中,每个服务用自己的本地上下文接上所需的东西。

对于大型 workspace,这能让依赖边界保持清晰。Models 可以独立演进,而不同服务仍可自由选择它们需要的任何存储格式或 API 表示。

真实世界示例:这在 Kova 中如何工作

上面的 ToJson 代码片段已经尽可能精简。把这个想法带进一个真实、更复杂的项目时,它仍然成立吗?

在构建我自己的 Rust ORM——Kova——时,我把这种模式应用到了整个类型系统中。这是一个很好的具体示例,展示了它在实践中如何发挥作用。

ORM 正是 Orphan Rule 伤害最大的地方。一张表常常混合 Uuid、Url、DateTime、HashMap 和自定义领域类型。Kova 的核心 Encode 和 Decode trait 使用的正是我们刚刚走过的泛型槽位设计:


        pub trait Encode<'a, X = ()> {
    fn encode(self) -> Result<Value<'a>>;
}

pub trait Decode<X = ()>: Sized {
    fn decode(value: Value<'_>) -> Result<Self>;
}
      

因为 Kova 把扩展点交给用户,它只需要内置支持基本的数据库原语:整数、浮点数、布尔值、字符串和字节数组。它的 Cargo.toml 不必为 uuid、chrono、jiff、url 等维护一堆可选依赖和 feature flag。

在真实应用中,工作流看起来就像前面的示例。

首先,在一个独立的 models crate 中用原生类型定义你的表结构体,并加上 #[derive(Model)]:


        // crate: models (no database driver or codec code needed)
#[derive(Model)]
pub struct Product {
    pub id: Uuid,
    pub price: Decimal,
    pub vendor_url: Url,
    pub created_at: DateTime<Utc>,
}
      

#[derive(Model)] 会展开成一份开放契约,例如 impl<X> Model<Engine, X> for Product where ...,因此 models 可以完全独立编译,而不必把自己绑定到任何具体的 codec 实现上。

接下来,在你的下游 service crate 中定义一个本地标记结构体 pub struct AppCodec;,并实现与你的存储布局匹配的零拷贝转换:


        pub struct AppCodec;

// Store Uuid as 16 raw bytes, borrowing directly with zero copies
impl<'a, 'b: 'a> Encode<'a, AppCodec> for &'b Uuid {
    fn encode(self) -> Result<Value<'a>> {
        Ok(Value::Blob(Cow::Borrowed(self.as_bytes())))
    }
}

// Store DateTime<Utc> as an integer millisecond timestamp
impl<'a> Encode<'a, AppCodec> for DateTime<Utc> {
    fn encode(self) -> Result<Value<'a>> {
        Ok(Value::Int8(self.timestamp_millis()))
    }
}
      

最后,在需要时切换客户端的上下文标记:


        // Default client using the () codec
let client = Options::from(conn_str).build()?;

// Switch to the local AppCodec at zero runtime cost
let client = client.codec::<AppCodec>();
      

切换类型不会带来任何运行时开销;底层只是把 Client 上的 PhantomData 标记从 () 换成 AppCodec。而在构建 Kova 的过程中,还显现出另一个好处:一旦有了像 AppCodec 这样的本地类型,除了编码和解码之外,还可以把更多东西挂到它上面。

例如,假设你在某个 ORM 中为 url::Url 实现了 Encode。如果你仍然无法对 Url 列执行 LIKE 查询,或者无法把 Url 列直接与 &str 比较,那么这个类型在查询中仍然像是二等公民。

因此,Kova 在其 SQL 能力 trait 和类型兼容规则上放了同样的泛型扩展槽,例如 CanString<X>、CanMath<X> 和 Compatible<Target, X>。用户可以在自己的 AppCodec 下添加几行简短声明:


        // Give Url string capabilities (enabling methods like `like` and `ilike`)
impl CanString<AppCodec> for Url {}

// Allow passing &str directly to a Url column without calling Url::parse() every time
impl<'a> Compatible<Static<Url>, AppCodec> for Static<&'a str> {}
      

有了这些,第三方类型就能直接融入 ORM 的 DSL,行为与内置类型毫无二致:


        client
    .update::<Product>()
    .set(Product::vendor_url.set("https://rust-lang.org"))
    .filter(
        Product::id.eq(&target_uuid)
            & Product::vendor_url.ilike("https://%")
    )
    .execute()
    .await?;
      

将这种设计放进 Kova 这样的真实代码库中验证,确认了一件很实际的事:将类型转换和能力开放给用户定义的上下文,不仅仅是在纸面上绕过孤儿规则。即便在复杂框架中,它也能保持依赖边界清晰、编译速度快、日常使用舒适。

Rust 的孤儿规则并不是为了让生活变难。它的存在是为了防止全局实现冲突,避免各个 crate 在全局命名空间中互相踩踏。一旦不再争夺“全局唯一”的实现,而是让 trait 上留一个泛型槽,把唯一性限定在本地上下文中,绕过孤儿规则就完全不需要什么黑魔法。这只是一个简单的视角转变,却能让库设计和大型 workspace 边界都干净得多。

在下一篇文章中,我会讨论紧随这一设计而来的问题:一旦你的 trait 和查询构建器都携带泛型上下文参数,如何避免陷入泛型类型体操和单态化膨胀?这就引出了边界验证和类型擦除。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by Lobsters
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗