• 函数必须修饰：所有供 C 侧调用的 Rust 函数必须声明为 pub extern "C"，以强迫 Rust 编译器采用标准的 C 语言调用约定（Calling Convention）。
• 符号必须保活：必须附加 #[no_mangle] 属性，阻止 Rust 编译器混淆函数名，确保 cbindgen 能够识别并生成同名的 C 语言函数声明。
• 布局必须强制：所有跨 FFI 传递的结构体，必须附加 #[repr(C)] 属性。这保证了 Rust 结构体中字段的内存顺序、对齐方式（Alignment）与 C 语言的 struct 严格保持 100% 一致。

• 谁申请，谁释放：在 Rust 侧通过 Box::new() 申请的堆内存，如果转换成裸指针 *mut c_void 传给 C 侧，C 侧绝对不能调用 free() 去释放它。必须在生命周期结束时，将指针传回 Rust 侧，通过 Box::from_raw() 重新收回所有权并触发 Rust 的自动析构（Drop）。
• 严禁跨边界解引用返回：在导出函数中，如果框架要求返回指针，严禁写成 return &mut *cntx。必须通过指针级联强转（如 cntx as *mut _ as *mut c_void）或使用 Box::into_raw() 传递纯粹的内存地址。

• 签名保持 Safe：向 Rust 内部框架挂载的回调函数，定义上不要写 pub unsafe extern "C" fn。这会导致外部强类型检查失败。
• 体内实施 Unsafe：正确的姿势是去掉签名的 unsafe，将其声明为普通的 pub extern "C" fn。仅在函数体内部需要处理 C 指针、执行 transmute 或解引用时，才开启 unsafe { ... } 代码块。
• 入参非空引用：若 C 侧框架能确保传入的指针绝对不为 NULL，在 Rust 侧的回调定义中可以直接用 &mut SpaceShipState 代替 *mut _。Rust 框架会在入口处自动完成转换，使你在函数内部无需编写任何指针判空代码，直接享受 Safe Rust 的开发体验。

• 指针 + 长度 $\rightarrow$ 视图：当 C 侧将数据流通过 const uint8_t *input 和 uint32_t input_len 传给 Rust 时，Rust 侧严禁将其分配（Allocate）到新的 Vec<u8> 中。
• 利用 Slice 宏：必须立即使用类似 slice::from_raw_parts将其打包为 Rust 的切片 &[u8]。这只是创建了一个内存视窗（Window），开销为零，却能直接调用 Rust 强大的模式匹配和解析工具（如 nom 框架）。

参考实现：

#[macro_export]
macro_rules! build_slice {
    ($buf:ident, $len:expr) => {
        if $buf.is_null() && $len == 0 {
            &[]
        } else {
            unsafe { std::slice::from_raw_parts($buf, $len) }
        }
    };
}

• 别名抹平冲突：当 Rust 侧要求 *const QuantumContext 而 C 侧老代码写死要求 QuantumContext * 时，不要强行修改任何一侧。在 Rust 侧声明一个别名 type QuantumContextPtr = *const core::QuantumContext;。
• 配置文件欺骗：在 cbindgen.toml 中配置 [export.rename] "QuantumContextPtr" = "QuantumContext *"。这样既满足了 Rust 侧的强类型回调注册，又强行让 cbindgen 在 C 头文件中吐出不带 const 的干净指针，实现了对既有老 C 代码的零侵入、零破坏。

注意：

如果 C 侧调用该函数时传入的是普通指针（*），而导出的头文件里声明的是常量指针（*const），这种情况下确实完全不需要使用类型别名去抹平冲突。