Rust 编译错误 E0802 深度解析：`derive(CoercePointee)` 派生宏的合法目标类型约束

Rust 编译错误 E0802 深度解析：derive(CoercePointee)派生宏的合法目标类型约束

【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust

本文基于 rustc 编译器错误码文档 E0802.md 展开，系统讲解当#[derive(CoercePointee)]应用于不满足约束的目标类型时，编译器报告 E0802 错误的全部触发场景、底层判定逻辑与正确的修复写法。读完本文，你将掌握CoercePointee派生宏对目标类型的完整要求（必须是带#[repr(transparent)]布局、至少含一个数据字段、至少拥有一个泛型类型参数的结构体），并能精准规避六类典型误用。

背景：CoercePointee派生宏是什么

CoercePointee是标准库中定义在内置宏集里的派生宏，声明位于 library/core/src/marker.rs，是一个rustc_builtin_macro，允许附带#[pointee]属性：

#[rustc_builtin_macro(CoercePointee, attributes(pointee))] #[allow_internal_unstable(dispatch_from_dyn, coerce_unsized, unsize, coerce_pointee_validated)] #[rustc_diagnostic_item = "CoercePointee"] #[unstable(feature = "derive_coerce_pointee", issue = "123430")] pub macro CoercePointee($item:item) { /* compiler built-in */ }

它的用途是让用户自定义的智能指针类型（如自定义Rc、MySmartPointer）能够参与“非尺寸化强制转换”（unsizing coercion），即让MySmartPointer<T>被自动强转为MySmartPointer<dyn Trait>，从而支持 trait object 动态分派。其派生实现会为类型自动生成core::ops::DispatchFromDyn与core::ops::CoerceUnsized的impl块（见 compiler/rustc_builtin_macros/src/deriving/coerce_pointee.rs），同时还生成一个core::marker::CoercePointeeValidated的实现用于后续在rustc_hir_analysis中校验派生合法性（library/core/src/marker.rs）。

由于派生宏对目标类型的要求比手写impl更严格，编译器会在宏展开阶段与类型检查阶段分别进行多项检查；任何一项不满足，都会报出 E0802 错误。

E0802 错误总览：目标类型“规格不合格”

E0802 的诊断信息为：The target of derive(CoercePointee) macro has inadmissible specification for a meaningful use.（derive(CoercePointee)宏的目标类型规格不符合有意义的使用要求）。它由编译器的多个检查点共同抛出，对应的诊断结构体定义在 compiler/rustc_hir_analysis/src/diagnostics.rs 和 compiler/rustc_builtin_macros/src/deriving/coerce_pointee.rs 中，包括：

以下逐一结合官方错误码文档中的compile_fail示例说明每个场景。

场景一：目标类型不是结构体

CoercePointee只能派生在结构体上。将派生宏应用于枚举（enum）会直接触发 E0802：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] enum NotStruct<'a, T: ?Sized> { Variant(&'a T), }

从实现上看，coerce_pointee.rs 在宏展开时对item做模式匹配，只有ItemKind::Struct分支会被接受；命中其他ItemKind（枚举、联合体、trait 等）时直接调用RequireTransparent报告 E0802 并中止展开。类型检查阶段还有一道兜底检查，对应CoercePointeeNotStruct诊断（rustc_hir_analysis/src/diagnostics.rs），消息为`derive(CoercePointee)` is only applicable to `struct`, instead of `{$kind}`。

场景二：目标结构体缺少#[repr(transparent)]透明布局

结构体的内存布局必须是透明的，即单一非零尺寸字段承载实际数据。缺少该属性会报错：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] struct NotTransparent<'a, #[pointee] T: ?Sized> { ptr: &'a T, }

原因在于：只有repr(transparent)才能保证“智能指针结构体的布局与内层指针字段完全一致”，这是CoerceUnsized/DispatchFromDyn能够安全地把T换成dyn Trait而不改变结构体 ABI 的前提。宏展开阶段会直接检查struct_data形态（coerce_pointee.rs），类型检查阶段的CoercePointeeNotTransparent（diagnostics.rs）也会再次确认透明布局这一事实。测试用例 tests/ui/derives/coercepointee/deriving-coerce-pointee-neg.rs 中即覆盖了这一反例。

场景三：结构体没有任何数据字段

即使加上了#[repr(transparent)]，一个空壳结构体（单元结构体或没有字段的命名/元组结构体）也无法派生：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] #[repr(transparent)] struct NoField<'a, #[pointee] T: ?Sized> {}

对应的展开期检查是：只接受VariantData::Struct（字段非空）或VariantData::Tuple（字段非空）两种形态，fields.is_empty()时报告RequireOneField（coerce_pointee.rs）。测试 deriving-coerce-pointee-neg.rs 同时验证了struct NoField {}与元组形态struct NoFieldUnit();两种空字段反例。

场景四：结构体没有任何泛型类型参数

CoercePointee的意义在于对“被指向的类型参数”做动态分派，因此结构体必须至少拥有一个泛型类型参数：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] #[repr(transparent)] struct NoGeneric<'a>(&'a u8);

上面的结构体只有生命周期参数'a，没有泛型类型参数。展开期代码通过统计GenericParamKind::Type的数量来判定：type_params.is_empty()时调用RequireOneGeneric（coerce_pointee.rs）。

场景五：有多个泛型类型参数，但未指定哪个是 pointee

当结构体拥有多个泛型类型参数时，必须显式用#[pointee]标注出用于强制转换的那一个：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] #[repr(transparent)] struct AmbiguousPointee<'a, T1: ?Sized, T2: ?Sized> { a: (&'a T1, &'a T2), }

编译器无法猜测T1与T2哪个才是“被指向的类型”，因此报 E0802（RequireOnePointee）。注意区分两个分支逻辑（coerce_pointee.rs）：

• 仅有一个泛型类型参数时：无论是否标记#[pointee]，都直接以它作为 pointee（标记是可选的、不强制）；
• 有多个泛型类型参数时：必须恰好有一个被#[pointee]标记，零个或多个都会报错。

场景六：多个泛型类型参数同时被标记为#[pointee]

与场景五相反，如果多个泛型类型参数都被打上了#[pointee]，同样触发 E0802：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] #[repr(transparent)] struct TooManyPointees< 'a, #[pointee] A: ?Sized, #[pointee] B: ?Sized> ((&'a A, &'a B));

实现中通过迭代器取前两个 pointee 候选：恰好一个则采用，零个报RequireOnePointee，两个及以上报TooManyPointees（coerce_pointee.rs）。TooManyPointees还会用#[label]标出“第二个被标记的#[pointee]”位置（coerce_pointee.rs），帮助定位多余标注。该反例同样出现在 deriving-coerce-pointee-neg.rs。

场景七：被标记的 pointee 泛型参数未声明?Sized

最后一项要求：被选为 pointee 的泛型类型参数（无论是唯一泛型参数还是显式#[pointee]标记的参数）必须用?Sized放宽尺寸约束，因为 trait object 本身是动态尺寸类型：

#![feature(coerce_pointee)] use std::marker::CoercePointee; #[derive(CoercePointee)] #[repr(transparent)] struct NoMaybeSized<'a, #[pointee] T> { ptr: &'a T, }

展开期会检查 pointee 参数的内联边界或where子句中是否存在?Sized（contains_maybe_sized_bound与contains_maybe_sized_bound_on_pointee两个辅助函数，coerce_pointee.rs），缺失时报告RequiresMaybeSized（coerce_pointee.rs）。需要说明的是，?Sized约束既可以写在泛型参数声明处（#[pointee] T: ?Sized），也可以写在where T: ?Sized子句中，两者均被认可。

合法用法：满足全部约束的正确写法

综合 E0802 文档末尾的总结（E0802.md），CoercePointee派生宏对目标类型的要求可归纳为五条：

1. 必须是结构体（struct），不能是枚举等其余 ADT；
2. 必须采用#[repr(transparent)]透明布局；
3. 必须至少含有一个数据字段；
4. 必须至少有一个泛型类型参数；若不止一个，则须用#[pointee]恰好标记其中一个；
5. 作为 pointee 的那个泛型参数必须标记为?Sized。

一个完全合法的最小示例（来自 library/core/src/marker.rs 的文档示例）：

#![feature(derive_coerce_pointee)] use std::marker::CoercePointee; use std::ops::Deref; #[derive(CoercePointee)] #[repr(transparent)] struct MySmartPointer<T: ?Sized>(Box<T>); impl<T: ?Sized> Deref for MySmartPointer<T> { type Target = T; fn deref(&self) -> &T { &self.0 } } trait MyTrait {} impl MyTrait for i32 {} fn main() { let ptr: MySmartPointer<i32> = MySmartPointer(Box::new(4)); // 没有 derive(CoercePointee) 时，这一行会报 E0308 类型不匹配 let ptr: MySmartPointer<dyn MyTrait> = ptr; }

多泛型参数时指定 pointee 的写法（library/core/src/marker.rs）：

#![feature(derive_coerce_pointee)] use std::marker::{CoercePointee, PhantomData}; #[derive(CoercePointee)] #[repr(transparent)] struct MySmartPointer<#[pointee] T: ?Sized, U> { ptr: Box<T>, _phantom: PhantomData<U>, }

注意：零尺寸字段若引用了泛型参数，必须使用PhantomData类型，这也是宏的硬性要求之一（library/core/src/marker.rs）。

底层原理：宏展开时做了什么

理解 E0802 的触发位置，有助于定位问题。整个#[derive(CoercePointee)]的处理入口是expand_deriving_coerce_pointee（coerce_pointee.rs），流程如下：

1. 前置遍历：DetectNonGenericPointeeAttr访问器扫描整个目标项，凡是在非泛型类型参数位置（如 const 泛型、关联类型、字段类型内部）出现#[pointee]属性，一律报NonGenericPointee错误（coerce_pointee.rs）——这是 E0802 家族里比较隐蔽的一类误用；
2. 形态检查：确认是struct且字段非空，否则报RequireTransparent/RequireOneField；
3. 泛型统计：确认至少一个泛型类型参数，并确定 pointee 参数下标，否则报RequireOneGeneric/RequireOnePointee/TooManyPointees；
4. ?Sized检查：确认 pointee 参数带?Sized，否则报RequiresMaybeSized；
5. 生成代码：把 pointee 类型参数在self类型中替换为__S（表示未知的 unsized 目标），为#[pointee]参数补上Unsize<__S>边界，重写其余泛型参数的边界与where子句（将涉及 pointee 的边界复制一份替换为__S版本），最后插入__S泛型参数并为DispatchFromDyn、CoerceUnsized各生成一个impl块。

展开完成后，CoercePointeeValidated的实现会在rustc_hir_analysis的类型检查阶段被再次校验（对应CoercePointeeNotStruct、CoercePointeeNotConcreteType、CoercePointeeNoUserValidityAssertion、CoercePointeeNotTransparent、CoercePointeeNoField等诊断，diagnostics.rs），防止用户绕开派生宏、在where子句或字段类型中做手脚。

相关测试与验证

编译器仓库在 tests/ui/derives/coercepointee/ 目录下提供了完整测试套件：

• deriving-coerce-pointee-neg.rs：本文所述各反例的集中回归测试，每条反例均通过//~^ ERROR:注释断言对应的 E0802 错误消息；其配套 deriving-coerce-pointee-neg.stderr 记录了精确的输出；
• deriving-coerce-pointee.rs 与 deriving-coerce-pointee-expanded.rs：验证合法结构体的派生成功与宏展开结果；
• coerce-pointee-bounds-issue-127647.rs：针对具体 issue 的边界场景测试。

如果你在本地用 nightly 工具链复现，注意 E0802 文档示例中使用的特性门是#![feature(coerce_pointee)]，而当前仓库 marker.rs 中登记的 unstable 特性为derive_coerce_pointee（issue #123430），不同版本可能有所差异，请以实际使用的工具链支持的特性名为准。

小结

E0802 是derive(CoercePointee)派生宏的“规格校验器”：它把自定义智能指针参与 trait object 强制转换的合法性前提，固化为一组可在编译期静态检查的形态约束（struct + 透明布局 + 至少一个数据字段 + 至少一个泛型类型参数 + 恰好一个#[pointee]标记 +?Sized）。掌握这六类反例及其判定逻辑，你就能在编写自定义智能指针（如仿Rc、仿Arc的薄封装）时一次性通过编译，并理解宏展开、DispatchFromDyn/CoerceUnsized生成与CoercePointeeValidated二次校验之间的完整链路。

【免费下载链接】rustEmpowering everyone to build reliable and efficient software.项目地址: https://gitcode.com/GitHub_Trending/ru/rust