Rust 编译器错误 E0562：`impl Trait` 为什么只能在函数签名中书写——从 rustc 源码看匿名类型的位置约束

在编写 Rust 代码时，一旦在变量绑定、结构体字段或路径等非预期位置写 impl Trait，编译器就会报出错误 E0562："impl Trait is only allowed as a function return and argument type"。本文基于 rustc 错误码文档 E0562.md 展开，先给出触发该错误的最小复现案例与标准修复方式，再结合 rustc 源码（rustc_ast_lowering 的降维诊断逻辑与 rustc_feature 的功能门控表）深入解释：编译器究竟在哪些语法位置禁止 impl Trait，为什么这样设计，以及哪些相关位置目前仍由不稳定 feature 门控。读完后你将能够准确判断 impl Trait 的合法书写范围，并能读懂该错误诊断背后的实现。

一、错误现场：在变量绑定中写 impl Iterator 会触发 E0562

原文档给出的触发案例非常简洁——在 let 绑定上标注 impl Trait 类型：

fn main() {
    let count_to_ten: impl Iterator<Item=usize> = 0..10;
    // error: `impl Trait` not allowed outside of function and inherent method
    //        return types
    for i in count_to_ten {
        println!("{}", i);
    }
}

这段代码的意图很自然：0..10 是一个范围迭代器，我希望能用一个匿名的类型标注它。但编译器会拒绝，并给出 E0562 错误。错误的核心语义是：impl Trait 是一种"类型遮蔽"（type ascription）语法，它只被语言规则允许出现在函数与固有方法（inherent method）的实参类型和返回类型位置，而变量绑定（variable binding）不属于这些位置。

修复方式：让 impl Trait 出现在函数签名里

文档给出的正确写法是，把匿名类型放到函数的返回位置，调用方不再关心具体类型：

fn count_to_n(n: usize) -> impl Iterator<Item=usize> {
    0..n
}

fn main() {
    for i in count_to_n(10) {  // ok!
        println!("{}", i);
    }
}

这里的 -> impl Iterator<Item=usize> 是一个不透明类型（opaque type）：编译器在函数内部知道它是 std::ops::Range<usize>，但对 main 只暴露"它实现了 Iterator<Item=usize>"这一契约。这正是 impl Trait 的设计目的——在不引入 dyn Trait（动态分发 + 堆分配/胖指针）的前提下，让 API 暴露"满足某 trait 的某类型"而不泄漏具体类型名。对于文档中"变量需要匿名类型"的场景，实际可用的替代手段是：

• 用 type_alias / 明确的类型名：let count_to_ten: std::ops::Range<usize> = 0..10;
• 把产生该值的逻辑封装进一个返回 impl Trait 的函数，如上面的 count_to_n。

二、源码级剖析：rustc 如何判定"impl Trait 出现在非法位置"

E0562 的诊断并不来自类型检查阶段，而是在 AST 向 HIR 降维（lowering）阶段就已被拦截。诊断结构体定义在 rustc_ast_lowering/src/diagnostics.rs：

#[derive(Diagnostic)]
#[diag("`impl Trait` is not allowed in {$position}", code = E0562)]
#[note("`impl Trait` is only allowed in arguments and return types of functions and methods")]
pub(crate) struct MisplacedImplTrait<'a> {
    #[primary_span]
    pub span: Span,
    pub position: DiagArgFromDisplay<'a>,
}

注意这里与原文档注释文案的差异：当前版本的诊断消息是"impl Trait is not allowed in {position}"，{position} 会被替换为具体的位置描述（例如 "the type of variable bindings"、"paths" 等）。也就是说，新版 rustc 的报错比文档示例中笼统的 "not allowed outside of function and inherent method return types" 更加精确地指出你究竟把 impl Trait 写错了什么地方。

ImplTraitContext：每个语法位置携带一份"是否允许 impl Trait"的上下文

触发点位于 rustc_ast_lowering/src/lib.rs。降维器在解析每个类型表达式时都会传入一个 ImplTraitContext，当上下文是"禁止"状态且遇到 TyKind::ImplTrait 时，就发出 MisplacedImplTrait：

ImplTraitContext::FeatureGated(position, feature) => {
    let guar = self
        .tcx
        .sess
        .create_feature_err(
            MisplacedImplTrait {
                span: t.span,
                position: DiagArgFromDisplay(&position),
            },
            feature,
        )
        .emit();
    hir::TyKind::Err(guar)
}
ImplTraitContext::Disallowed(position) => {
    let guar = self.dcx().emit_err(MisplacedImplTrait {
        span: t.span,
        position: DiagArgFromDisplay(&position),
    });
    hir::TyKind::Err(guar)
}

从源码结构看，这个上下文分两类处理，值得区分：

1. Disallowed(position)：该位置目前完全不允许 impl Trait，直接报 E0562；
2. FeatureGated(position, feature)：该位置尚未稳定，需要启用某个 unstable feature 才可用——同样报 E0562，但错误文案会附带"该功能受 #![feature(...)] 门控"的提示。

而 ImplTraitContext 的完整定义与 ImplTraitPosition 的展示文案在 rustc_ast_lowering/src/lib.rs。从 ImplTraitPosition 的 Display 实现可以读出一份编译器认可的"非法位置清单"，包括（摘选）：

ImplTraitPosition 变体	报错中显示的位置描述
Variable	the type of variable bindings（变量绑定的类型）
Path	paths（路径）
Trait	traits（trait 定义处）
Bound	bounds（trait bound 中）
Generic	generics（泛型参数声明处）
StaticTy	static types（static 的类型）
FieldTy	field types（结构体字段类型）
Cast	cast expression types（强制类型转换的目标类型）
ClosureParam / ClosureReturn	closure parameters / closure return types（闭包参数与返回类型）
PointerParam / PointerReturn	fn pointer parameters / return types（函数指针参数与返回类型）
AssocTy	associated types（关联类型定义处）
ImplSelf	impl headers（impl 头的自类型）
ConstTy	const types（常量类型）
OffsetOf	offset_of! parameters（宏参数）

这份清单解释了为什么文档示例中 let count_to_ten: impl Iterator<...> 会命中 E0562：lower_ty_alloc 在降维变量绑定的类型注解时传入的正是 ImplTraitPosition::Variable 上下文（见 rustc_ast_lowering/src/block.rs）。

合法的"允许"上下文在哪里？

与 Disallowed 相对，ImplTraitContext 还存在若干允许分支。在同一降维逻辑中：

• 函数/方法的返回位置与实参位置会走允许分支，生成 opaque 类型定义（opaque type）；
• ImplTraitContext::Universal 分支（lib.rs）处理 RPITIT——trait 中关联类型的 impl Trait 返回，它会为每个 trait 实现合成一个 TyParam；
• ImplTraitContext::InBinding 分支（lib.rs）则生成了 hir::TyKind::TraitAscription，即 let x: impl Trait 这种"绑定位置 trait 说明"的 HIR 表示——但注意，进入该分支的前提是 feature 已启用（见下文 FeatureGated 逻辑）。

三、与 E0562 相关的功能门控：哪些"扩展位置"还在路上

FeatureGated 分支的存在意味着：部分位置写 impl Trait 并不是语言设计上的死路，而是处于 unstable 阶段。功能门控表在 rustc_feature/src/unstable.rs 中可以查证：

(unstable, impl_trait_in_assoc_type, "1.70.0", Some(63063)),
(unstable, impl_trait_in_bindings, "1.64.0", Some(63065)),
(unstable, impl_trait_in_fn_trait_return, "1.64.0", Some(99697)),

• impl_trait_in_bindings：允许 let x: impl Trait = ...;。变量绑定位置的上下文由 block.rs 中的 impl_trait_in_bindings_ctxt 决定——feature 开启时进入 InBinding 分支，未开启时则落入 FeatureGated 分支并报 E0562。文档示例中那行 let count_to_ten: impl Iterator<Item=usize> = 0..10; 在 nightly 下加 #![feature(impl_trait_in_bindings)] 后即可通过编译；
• impl_trait_in_fn_trait_return：放宽 Fn trait bound 中返回位置的 impl Trait；
• impl_trait_in_assoc_type：关联类型位置的 impl Trait。

与之相对，RPITIT（return-position impl Trait in traits）已经接受（accepted），见 rustc_feature/src/accepted.rs：

(accepted, return_position_impl_trait_in_trait, "1.75.0", Some(91611)),

即自 1.75.0 起，trait 定义中关联函数返回 impl Trait 是稳定语法（如 trait Foo { fn f(&self) -> impl Bar; }），这是 impl Trait 目前合法位置中最新扩展的一族，相关实现遍布 rustc_hir_analysis（is_impl_trait_in_trait 判断、collect_return_position_impl_trait_in_trait_tys 查询）与 rustc_ty_utils/src/assoc.rs（为 RPITIT 合成关联类型）。

四、实战要点小结

1. E0562 的本质：impl Trait 是"该位置只能有一个被编译器选定的具体类型"的遮蔽语法，语言目前只承诺在函数与固有方法的参数/返回位置实现这一语义；变量绑定、字段、路径等其他位置写它会报 E0562。
2. 诊断信息可读性：当前版本的错误消息会动态给出具体位置（"is not allowed in the type of variable bindings" 等），定位比旧版示例文案更直接。
3. 替代方案：
   • 需要"某个实现了 Trait 的值"作为局部变量时，优先封装为返回 impl Trait 的函数（文档推荐路径），或写具体类型/使用 dyn Trait；
   • 在 nightly 上探索 let x: impl Trait 语法时，对应门控 feature 是 impl_trait_in_bindings（源自 unstable.rs 的门控表），使用前应确认目标项目允许 nightly 工具链。
4. 想深入了解合法位置的全集：阅读 rustc_ast_lowering/src/lib.rs 中 ImplTraitContext 与 ImplTraitPosition 的定义，是所有"允许 / 禁止 / 门控"三态的唯一事实来源。

综合而言，E0562 不是一句含糊的"不合法"，而是 rustc 在 AST 降维阶段对 impl Trait 书写位置做的白名单式检查：只有函数签名（及其已接受/受门控的扩展）能创建 opaque 类型，其余位置均会命中 diagnostics.rs 中定义的 MisplacedImplTrait 诊断。理解了这条白名单及其源码位置，就能在 API 设计中正确使用 impl Trait，并在看到 E0562 时快速判断该改写成函数封装、换成具体类型，还是（在 nightly 上）启用对应 feature。