Rust 编译器 E0118 错误详解：为什么 impl 必须作用于命名类型（nominal type）

本文基于 Rust 仓库中的官方错误码文档 E0118.md，讲解错误 E0118: no nominal type found for inherent implementation 的触发条件、两种官方修复方案（trait 实现与新类型封装），并结合 coherence/inherent_impls.rs 中的源码检查逻辑，说明编译器是如何判定一个 impl 的 self 类型是否"合法"的，以及它与 E0390、E0116 等相关错误的边界区别。

一、E0118 是什么：impl 只能挂在"命名类型"上

E0118 的完整诊断信息为：

error[E0118]: no nominal type found for inherent implementation
  = note: either implement a trait on it or create a newtype to wrap it instead

根据 E0118.md 的定义，该错误出现在**你为"不是 struct、enum、union 或 trait object 的类型"定义了 inherent implementation（固有 impl，即 impl X { ... } 形式）**时。最典型的触发场景是为类型参数 T 直接写 impl：

impl<T> T { // error: no nominal type found for inherent implementation
    fn get_state(&self) -> String {
        // ...
    }
}

这条错误码对应的 UI 测试用例 tests/ui/error-codes/E0118.rs 与预期输出 E0118.stderr 精确复现了上面的场景，编译器输出的诊断如下：

error[E0118]: no nominal type found for inherent implementation
  --> E0118.rs:1:1
  |
LL | impl<T> T {
  | ^^^^^^^^^ impl requires a nominal type
  |
  = note: either implement a trait on it or create a newtype to wrap it instead

这里的关键概念是 nominal type（名义/命名类型）。从源码结构看，一个合法的 inherent impl 的 self 类型必须能在 impls_map 中注册到一个具体的类型定义 ID（DefId）上——因为编译器查询某个类型有哪些固有方法时，走的是 tcx.inherent_impls(def_id) 这条以类型 DefId 为键的路径（见 inherent_impls.rs 的 inherent_impls 函数）。而泛型参数 T、trait 投影 <T as Tr>::Assoc 这类类型根本没有自己的 DefId，无法进入这张映射表，所以编译器直接拒绝，这正是 "no nominal type found" 的字面含义。

为什么这么设计

inherent impl 是"类型自身"的一部分，它的查找优先级高于 trait 方法（写 obj.method() 时编译器先看固有方法再看 trait 方法）。如果把 impl<T> T 这样的写法放开，意味着任意 crate 都能给任意类型"凭空"添加方法，这些方法会静默地遮蔽同名 trait 方法，破坏名称解析的确定性。因此语言层面规定：固有 impl 必须落在一个具体的命名类型上，跨 crate 还受孤儿规则（orphan rules）约束。

二、官方修复方案一：实现一个 trait

E0118.md 给出的第一种修复方式，是不要直接给 T 写固有 impl，而是定义一个 trait 并在 T 上实现它：

// we create a trait here
trait LiveLongAndProsper {
    fn get_state(&self) -> String;
}

// and now you can implement it on T
impl<T> LiveLongAndProsper for T {
    fn get_state(&self) -> String {
        "He's dead, Jim!".to_owned()
    }
}

注意 impl<T> LiveLongAndProsper for T 与 impl<T> T 的本质区别：前者实现的目标是 trait，trait 解析遵循 Rust 的方法查找规则（按 T: LiveLongAndProsper 约束生效），不存在"给类型凭空添加固有成员"的问题。实际使用中常见的变体是为 T 加上约束，例如 impl<T: AsRef<str>> MyTrait for T，这属于 trait impl 的正常用法。

三、官方修复方案二：newtype（新类型封装）

文档给出的第二种修复方式是 newtype 包装——用一个单字段元组结构体把目标类型包起来，然后在包装类型上定义固有方法。文档原话：newtype 是一个 wrapping tuple-struct，例如 struct NewType(Foo) 中 NewType 就是 Foo 的 newtype。

struct TypeWrapper<T>(T);

impl<T> TypeWrapper<T> {
    fn get_state(&self) -> String {
        "Fascinating!".to_owned()
    }
}

TypeWrapper<T> 是一个真正的 struct（有 DefId），因此 impl<T> TypeWrapper<T> { ... } 完全合法，其固有方法会按正常的固有方法查找路径被注册和解析。newtype 包装同时也是绕过孤儿规则（E0116）处理外部类型时的标准手法：编译器在 diagnostics.rs 中给出的 E0116 帮助信息正是 consider defining a trait and implementing it for the type or using a newtype wrapper like struct MyType(ExternalType); and implement it——两种思路与 E0118 的 note 建议完全一致。

两种方案如何选择

• 需要把方法挂到调用方可见的原始类型上（调用 t.get_state() 时 t 本身是 T）：用 trait 方案。
• 方法只服务于内部表示、可以接受多一层包装：用 newtype 方案，它还附带了类型区分（TypeWrapper<T> 与 T 不是同一类型，防止误用）和 ABI 不变（零成本包装）的优点。

四、编译器源码视角：E0118 在哪里被触发

E0118 的诊断定义位于 diagnostics.rs：

#[derive(Diagnostic)]
#[diag("no nominal type found for inherent implementation", code = E0118)]
#[note("either implement a trait on it or create a newtype to wrap it instead")]
pub(crate) struct InherentNominal {
    #[primary_span]
    #[label("impl requires a nominal type")]
    pub span: Span,
}

触发它的检查逻辑在 inherent_impls.rs 的 crate_inherent_impls 查询中：该查询遍历当前 crate 的所有顶层项（tcx.hir_free_items()），对每个 DefKind::Impl { of_trait: false } 的固有 impl 调用 check_item（第 168 行起），按 self 类型的种类（self_ty.kind()）分派：

self 类型种类	处理路径	结果
ty::Adt（struct/enum/union）、ty::Foreign	check_def_id	合法，注册进 impls_map.inherent_impls
ty::Dynamic 且含 principal trait	check_def_id	trait object 合法
ty::Dynamic 仅 auto trait	直接报错	InherentDyn（E0785）
基本类型（Bool/Int/Ref/Tuple 等）	check_primitive_impl	非 core 中报 E0390
投影/固有别名/Opaque、类型参数 ty::Param	直接报错	InherentNominal（E0118）
FnDef/闭包/协程等	bug!	理论上不会在 impl 头出现

关键分支见 inherent_impls.rs 第 206-215 行：

ty::Alias(_, ty::AliasTy { kind: ty::Projection { .. } | ty::Inherent { .. } | ty::Opaque { .. }, .. })
| ty::Param(_) => {
    Err(self.tcx.dcx().emit_err(diagnostics::InherentNominal { span: item_span }))
}

即：泛型参数（ty::Param）和 <_>::Assoc 类别名（ty::Alias 中的 Projection/Inherent/Opaque）统一触发 E0118。这也解释了为何 impl<T> T { ... } 和 impl<T: Tr> <T as Tr>::Item { ... } 都会得到同一条错误——它们都不是 nominal type。

五、与相关错误的区分

阅读源码后可以清晰划出 E0118 与三个相邻错误的边界，避免混淆：

• E0390（不能为基本类型定义固有 impl）：impl i32 { ... }、impl &str { ... } 这类基本类型 impl 走的是 check_primitive_impl 分支，只有 core 等系统 crate（带 rustc_coherence_is_core 属性）可以写。普通用户会得到 "cannot define inherent impl for primitive types" 并建议"使用 extension trait"（E0390 诊断定义）。
• E0116（孤儿规则 / 跨 crate 固有 impl）：为别的 crate 定义的类型写固有 impl，走 check_def_id 中 ty_def_id.as_local() 为 None 的分支，报 "cannot define inherent impl for a type outside of the crate where the type is defined"，修复建议同样是 trait 或 newtype（第 1250-1264 行）。
• E0785（不能为 dyn auto trait 定义固有 impl）：impl dyn Send { ... } 这种只有 auto trait 的 trait object 触发 InherentDyn（第 1303-1310 行）。

一句话总结三者的判定顺序：先看 self 类型是不是 nominal type（不是则 E0118）；是 nominal 但属于基本类型则 E0390；是外部 crate 的类型则 E0116。

六、小结

• E0118 的本质是：固有 impl 的 self 类型必须是 struct、enum、union 或 trait object 这类有定义 ID 的命名类型；泛型参数 T、关联类型投影等匿名类型没有注册位置，编译器直接拒绝。
• 官方给出的两条修复路径：实现 trait（保留对原类型的调用方式）或 newtype 元组结构体包装（获得独立的命名类型）。
• 触发点源码位于 rustc_hir_analysis 的 coherence 检查，诊断文本定义于 rustc_hir_analysis/src/diagnostics.rs；官方错误码文档见 E0118.md，回归测试见 tests/ui/error-codes/E0118.rs。

当你遇到 no nominal type found for inherent implementation 时，对照本文的判定表和两种修复模式，基本可以一次改对。