Rust 的 `PhantomData`：零成本把“语义信息”交给编译器

在写底层 Rust（尤其是 unsafe / 裸指针 / FFI）时，你会遇到一种常见矛盾：

运行时 ：你手里可能只有一个 *const T / *mut T / *mut c_void（比如外部库返回的句柄），结构体里并没有真正存放某个引用或某个类型的值。
编译期 ：你又希望编译器知道"我这个类型和某个生命周期/类型绑定 "，从而帮你做借用检查、推导 Send/Sync、避免错误混用等。

std::marker::PhantomData<T> 就是为了解决这个问题而存在的工具。官方文档的核心定义是：

PhantomData<T> 是一个 零大小类型 （ZST），用于标记你的类型"行为上像是拥有/包含 一个 T"，尽管你实际上并没有存储 T。这会影响编译器计算一些安全相关属性。

也因此，它常被称为"只在编译期生效的零成本抽象"。

size_of::<PhantomData<T>>() == 0
align_of::<PhantomData<T>>() == 1

下面用两个最典型的场景来科普：

绑定生命周期（防悬垂）
绑定类型参数（防混用）

1. 绑定生命周期：裸指针不带生命周期，需要用 `PhantomData<&'a T>` 把借用关系"说清楚"

假设你想实现一个 slice/数组的迭代器或视图，内部用裸指针表示范围：

rust 复制代码

struct Slice<T> {
    start: *const T,
    end: *const T,
}

如果这些指针来自某个外部数据（比如 Vec<T> / &[T]），为了避免悬垂指针，你的真实意图是：

Slice 不能活得比原始数据更久

但问题是：*const T 不携带生命周期，编译器无法从字段中推导"它借用了谁、借用了多久"。于是你会想加生命周期参数：

rust 复制代码

struct Slice<'a, T> {
    start: *const T,
    end: *const T,
}

这会立刻遇到编译器抱怨：'a 没有被使用（unused lifetime parameter）。更重要的是：即使你强行让它通过，编译器也仍然不知道 'a 和哪些数据有关。

正确写法：加一个"假装持有引用"的标记字段

rust 复制代码

use std::marker::PhantomData;

struct Slice<'a, T> {
    start: *const T,
    end: *const T,
    _marker: PhantomData<&'a T>,
}

PhantomData<&'a T> 的含义可以直译为：

"请把我当成好像内部存了一个 &'a T 引用。"

于是类型系统就会把 Slice<'a, T> 当成"借用了 'a 的 T"，从而强制它不能活过 'a。

坏例子：没有生命周期绑定，能编译，但可能产生悬垂指针（UB）

下面这段代码演示了"裸指针 + 没有 'a"的危险：它能把指向局部 Vec 的指针带出函数。

注意：这段代码可能触发未定义行为（UB） ，请不要在真实项目里这么写。

rust 复制代码

struct SliceIterBad<T> {
    ptr: *const T,
    len: usize,
}

fn raw_from_vec_bad<T>(v: &Vec<T>) -> SliceIterBad<T> {
    SliceIterBad {
        ptr: v.as_ptr(),
        len: v.len(),
    }
}

// ❌ 能编译，但返回的 ptr 指向已释放的内存
fn bad() -> SliceIterBad<i32> {
    let v = vec![1, 2, 3];
    raw_from_vec_bad(&v) // v 在这里被 drop，但指针被带出去了
}

这就是典型的"类型系统没被告知借用关系 → 编译器无法阻止悬垂"。

好例子：用 `PhantomData<&'a T>` 绑定借用，错误在编译期暴露

rust 复制代码

use std::marker::PhantomData;

struct SliceIter<'a, T> {
    ptr: *const T,
    len: usize,
    _marker: PhantomData<&'a T>,
}

fn raw_from_vec<'a, T>(v: &'a Vec<T>) -> SliceIter<'a, T> {
    SliceIter {
        ptr: v.as_ptr(),
        len: v.len(),
        _marker: PhantomData,
    }
}

// ❌ 这次会直接编译失败：你试图返回一个借用了局部变量 v 的值
fn good_but_wont_compile() -> SliceIter<'static, i32> {
    let v = vec![1, 2, 3];
    raw_from_vec(&v)
}

你会得到类似这样的错误（不同版本文案略有差异）：

sql 复制代码

error[E0515]: cannot return value referencing local variable `v`
  returns a value referencing data owned by the current function

这就达到了目的：把潜在的悬垂指针风险提前变成编译错误。

正确使用方式是：让迭代器不超过数据的作用域，例如：

rust 复制代码

fn ok_usage() {
    let v = vec![1, 2, 3];
    let it = raw_from_vec(&v);
    // 在 v 的生命周期内使用 it
    let _ = it.len;
}

2. 绑定类型参数：FFI 句柄是 `*mut ()`，用 `PhantomData<R>` 防止把 A 当 B 用

另一类常见场景来自 FFI：外部库可能用统一的 void*（Rust 里常见 *mut () 或 *mut c_void）当作"资源句柄"。运行时只有一个指针，但它背后可能对应不同资源类型。

如果你只写成"无类型句柄包装"，编译器分不清"这是 Foo 资源还是 Bar 资源"，于是非常容易混用。

坏例子：句柄不带类型信息，混用能编译，运行时才爆炸

下面用 assert! 模拟"用错句柄就炸"（真实 FFI 里可能是崩溃/数据错乱/UB）：

rust 复制代码

use std::ffi::c_void;

mod foreign_lib {
    use super::c_void;

    struct Raw {
        tag: u32, // 1 => Foo, 2 => Bar
    }

    pub unsafe fn new(tag: u32) -> *mut c_void {
        Box::into_raw(Box::new(Raw { tag })) as *mut c_void
    }

    pub unsafe fn do_foo(handle: *mut c_void) {
        let raw = handle as *mut Raw;
        assert!((*raw).tag == 1, "expected Foo handle, got tag={}", (*raw).tag);
    }

    pub unsafe fn do_bar(handle: *mut c_void) {
        let raw = handle as *mut Raw;
        assert!((*raw).tag == 2, "expected Bar handle, got tag={}", (*raw).tag);
    }

    pub unsafe fn free(handle: *mut c_void) {
        drop(Box::from_raw(handle as *mut Raw));
    }
}

struct ExternalResourceBad {
    handle: *mut c_void,
}

impl ExternalResourceBad {
    fn new_foo() -> Self {
        Self { handle: unsafe { foreign_lib::new(1) } }
    }
    fn new_bar() -> Self {
        Self { handle: unsafe { foreign_lib::new(2) } }
    }

    fn do_foo(&self) { unsafe { foreign_lib::do_foo(self.handle) } }
    fn do_bar(&self) { unsafe { foreign_lib::do_bar(self.handle) } }
}

impl Drop for ExternalResourceBad {
    fn drop(&mut self) {
        unsafe { foreign_lib::free(self.handle) }
    }
}

fn main() {
    let r = ExternalResourceBad::new_bar();

    // ❌ 逻辑错误：拿 Bar 的句柄去当 Foo 用
    // 编译器看不出来（类型都一样），但运行时可能 panic/崩溃
    r.do_foo();
}

好例子：用 `PhantomData<R>` 把句柄"绑定到类型"，混用直接编译错误

rust 复制代码

use std::{ffi::c_void, marker::PhantomData};

struct Foo;
struct Bar;

trait ResType { const TAG: u32; }
impl ResType for Foo { const TAG: u32 = 1; }
impl ResType for Bar { const TAG: u32 = 2; }

struct ExternalResource<R> {
    handle: *mut c_void,
    _type: PhantomData<R>,
}

impl<R: ResType> ExternalResource<R> {
    fn new() -> Self {
        Self {
            handle: unsafe { foreign_lib::new(R::TAG) },
            _type: PhantomData,
        }
    }
}

impl<R> Drop for ExternalResource<R> {
    fn drop(&mut self) {
        unsafe { foreign_lib::free(self.handle) }
    }
}

fn takes_foo(_: ExternalResource<Foo>) {}

fn main() {
    let foo = ExternalResource::<Foo>::new();
    let bar = ExternalResource::<Bar>::new();

    takes_foo(foo); // ✅ OK

    // takes_foo(bar);
    // ❌ 编译期报错：
    // expected `ExternalResource<Foo>`, found `ExternalResource<Bar>`
}

这就是文档里"未使用类型参数"的核心意义：哪怕结构体里根本没有存 R ，你仍然可以用 PhantomData<R> 让类型系统记住并区分它，从而把很多"本来只能靠人肉保证的约定"变成编译器可检查的约束。 from Pomelo_刘金，转载请注明原文链接。感谢！

Rust 的 `PhantomData`：零成本把“语义信息”交给编译器

1. 绑定生命周期：裸指针不带生命周期，需要用 PhantomData<&'a T> 把借用关系"说清楚"

正确写法：加一个"假装持有引用"的标记字段

坏例子：没有生命周期绑定，能编译，但可能产生悬垂指针（UB）

好例子：用 PhantomData<&'a T> 绑定借用，错误在编译期暴露

2. 绑定类型参数：FFI 句柄是 *mut ()，用 PhantomData<R> 防止把 A 当 B 用

坏例子：句柄不带类型信息，混用能编译，运行时才爆炸

好例子：用 PhantomData<R> 把句柄"绑定到类型"，混用直接编译错误

1. 绑定生命周期：裸指针不带生命周期，需要用 `PhantomData<&'a T>` 把借用关系"说清楚"

好例子：用 `PhantomData<&'a T>` 绑定借用，错误在编译期暴露

2. 绑定类型参数：FFI 句柄是 `*mut ()`，用 `PhantomData<R>` 防止把 A 当 B 用

好例子：用 `PhantomData<R>` 把句柄"绑定到类型"，混用直接编译错误