对于位域（bitfield），Rust 没有语法支持，需要手动用位操作实现。这正是 bindgen 能自动处理的部分。

2.4 数组与指针

// C 数组参数本质就是指针
extern "C" {
    fn process_array(data: *const i32, length: usize) -> i32;
    fn get_version(buf: *mut u8, buf_size: usize) -> i32;
}

// 安全封装
fn safe_process_array(data: &[i32]) -> Option {
    unsafe {
        let result = process_array(data.as_ptr(), data.len());
        if result >= 0 { Some(result) } else { None }
    }
}

// 为 C 端提供可写的缓冲区
fn get_version_string() -> Option {
    let mut buf = vec![0u8; 256];
    let len = unsafe {
        get_version(buf.as_mut_ptr(), buf.len())
    };
    if len > 0 {
        buf.truncate(len as usize);
        String::from_utf8(buf).ok()
    } else {
        None
    }
}

第三章：所有权——跨生命周期的资源管理

3.1 谁拥有谁释放

FFI 中最关键的规则是：谁分配谁释放。C 的 malloc 必须由 free 释放，Rust 的 Box 必须由 Rust 释放。跨边界传递所有权需要明确协议。

// 模式1：Rust 创建，转移所有权给 C
struct DatabaseHandle {
    connection: *mut sqlite3,
}

impl DatabaseHandle {
    fn open(path: &str) -> Result {
        let cpath = CString::new(path)?;
        let mut handle: *mut sqlite3 = std::ptr::null_mut();
        let rc = unsafe {
            sqlite3_open(cpath.as_ptr(), &mut handle)
        };
        if rc == SQLITE_OK && !handle.is_null() {
            Ok(Self { connection: handle })
        } else {
            Err(DbError::OpenFailed(rc))
        }
    }
}

impl Drop for DatabaseHandle {
    fn drop(&mut self) {
        unsafe {
            sqlite3_close(self.connection);
        }
    }
}

// 使用 RAII 确保安全释放
{
    let db = DatabaseHandle::open("data.db")?;
    // 使用 db...
} // 即使 panic，sqlite3_close 也会被调用

3.2 into_raw / from_raw 惯用法

当你需要"解冻"Rust 所有权给 C 端时，使用 owned 类型的 into_raw 和 from_raw：

// CString::into_raw: Rust 放弃所有权，C 端可以使用该指针
// 但 C 端完成后必须将指针传回给 Rust，由 Rust 重新索取所有权并释放

#[no_mangle]
pub extern "C" fn create_resource() -> *mut c_void {
    let resource = Box::new(MyResource::new());
    Box::into_raw(resource) as *mut c_void
}

#[no_mangle]
pub extern "C" fn use_resource(ptr: *mut c_void) {
    if let Some(res) = unsafe { (ptr as *mut MyResource).as_mut() } {
        res.do_work();
        // 不释放——所有权仍然在 C 端
    }
}

#[no_mangle]
pub extern "C" fn destroy_resource(ptr: *mut c_void) {
    if !ptr.is_null() {
        unsafe {
            drop(Box::from_raw(ptr as *mut MyResource));
        }
    }
}

3.3 MaybeUninit 与安全初始化

当 C 函数通过指针输出参数（如 int get_size(int*)）时，MaybeUninit 是最佳实践：

extern "C" {
    fn compute_result(input: i32, output: *mut i32) -> i32; // 返回 0 表示成功
}

fn safe_compute(input: i32) -> Result {
    let mut output = std::mem::MaybeUninit::::uninit();
    let status = unsafe {
        compute_result(input, output.as_mut_ptr())
    };
    if status == 0 {
        Ok(unsafe { output.assume_init() })
    } else {
        Err("compute_result failed")
    }
}

// Rust 1.73+ 也可以这样写：
fn safe_compute_v2(input: i32) -> Result {
    let mut output = unsafe { std::mem::zeroed() }; // 比 uninit 更快（对小类型）
    let status = unsafe {
        compute_result(input, &mut output)
    };
    if status == 0 { Ok(output) } else { Err("failed") }
}

第四章：bindgen——自动化绑定生成

4.1 从头文件生成 Rust 绑定

手动翻译 C 头文件既繁琐又容易出错。bindgen 是一个工具，它使用 libclang 解析 C/C++ 头文件并自动生成对应的 Rust 代码。

在 Cargo.toml 中添加构建依赖：

[build-dependencies]
bindgen = "0.69"

编译器指令（build.rs）：

// build.rs
use std::env;
use std::path::PathBuf;

fn main() {
    // 告诉 cargo 当头文件变化时重新编译
    println!("cargo:rerun-if-changed=wrapper.h");

    let bindings = bindgen::Builder::default()
        .header("wrapper.h")
        .parse_callbacks(Box::new(bindgen::CargoCallbacks::new()))
        // 生成 Rust 风格类型
        .generate_comments(true)
        // 对 C++ 类型使用新样式
        .use_core()
        // 如果有 C++ 代码，需要链接标准库
        .clang_args(&["-x", "c++", "-std=c++17"])
        // 为某个特定前缀只生成
        // .allowlist_function("mylib_.*")
        // .allowlist_type("mylib_.*")
        // 设置特定类型的布局
        .size_t_is_usize(true)
        .generate()
        .expect("Unable to generate bindings");

    let out_path = PathBuf::from(env::var("OUT_DIR").unwrap());
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("Couldn't write bindings!");
}

4.2 封装生成的不安全绑定

bindgen 生成的代码是 100% 不安全的（所有函数都是 unsafe extern "C" 的）。最佳实践是用安全的 Rust API 包裹它们：

// 原始绑定（bindgen 生成，放在单独模块中）
mod ffi {
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}

// 安全封装层
pub struct ffi::MyLibContext {
    handle: *mut ffi::mylib_ctx_t,
}

impl MyLibContext {
    pub fn new(config: &Config) -> Result {
        let c_config = ffi::mylib_config_t {
            max_connections: config.max_connections as u32,
            timeout_ms: config.timeout.as_millis() as u64,
            // ... 映射所有字段
        };
        let mut handle: *mut ffi::mylib_ctx_t = std::ptr::null_mut();
        let rc = unsafe {
            ffi::mylib_ctx_new(&c_config, &mut handle)
        };
        if rc == 0 && !handle.is_null() {
            Ok(Self { handle })
        } else {
            Err(MyLibError::from_code(rc))
        }
    }

    pub fn process(&self, data: &[u8]) -> Result, MyLibError> {
        let mut output: *mut u8 = std::ptr::null_mut();
        let mut output_len: usize = 0;
        let rc = unsafe {
            ffi::mylib_process(
                self.handle,
                data.as_ptr(),
                data.len(),
                &mut output,
                &mut output_len,
            )
        };
        if rc == 0 {
            let result = unsafe {
                Vec::from_raw_parts(output, output_len, output_len)
            };
            Ok(result)
        } else {
            Err(MyLibError::from_code(rc))
        }
    }
}

impl Drop for MyLibContext {
    fn drop(&mut self) {
        unsafe { ffi::mylib_ctx_free(self.handle) };
    }
}

// 禁止线程间传递（除非你知道它是线程安全的）
impl !Send for MyLibContext {}
impl !Sync for MyLibContext {}

4.3 处理 C++ 类型与回调

bindgen 对 C++ 的支持有限——它不能处理模板（模板类必须在 C++ 侧提前实例化为具体类型）。常见的做法是在 C 头文件中用前置声明和具体化解决：

// wrapper.h （混合 C/C++）
#ifdef __cplusplus
extern "C" {
#endif

// C 兼容的函数接口（即使内部使用 C++ 实现）
typedef struct mylib_string_t mylib_string_t;

mylib_string_t* mylib_string_new(const char* data, size_t len);
void mylib_string_free(mylib_string_t* s);
const char* mylib_string_data(const mylib_string_t* s);
size_t mylib_string_len(const mylib_string_t* s);

// 回调函数类型
typedef void (*mylib_callback_t)(int event, const void* data, size_t len, void* user_data);
void mylib_set_callback(mylib_callback_t cb, void* user_data);

#ifdef __cplusplus
}
#endif

第五章：回调函数与函数指针

5.1 C 到 Rust 的回调注册

最常见的 FFI 模式是注册回调——C 库在特定事件发生时调用 Rust 函数：

extern "C" {
    fn register_callback(
        callback: extern "C" fn(event: i32, data: *const u8, len: usize),
        user_data: *mut c_void,
    ) -> i32;
}

// Rust 回调必须是 extern "C" 函数
extern "C" fn on_event(event: i32, data: *const u8, len: usize) {
    if !data.is_null() && len > 0 {
        let payload = unsafe { std::slice::from_raw_parts(data, len) };
        println!("Event {}: {:?}", event, payload);
    }
}

// 注册
unsafe {
    register_callback(on_event, std::ptr::null_mut());
}

5.2 捕获上下文的回调（闭包模式）

裸函数指针无法携带上下文——你需要通过 user_data 指针传递状态：

use std::sync::{Arc, Mutex};

// 回调要修改的状态
struct CallbackState {
    call_count: usize,
    last_event: i32,
}

// 指针回调 + user_data 模式
extern "C" fn on_event_with_context(
    event: i32,
    data: *const u8,
    len: usize,
    user_data: *mut c_void,
) {
    let state = unsafe { &mut *(user_data as *mut CallbackState) };
    state.call_count += 1;
    state.last_event = event;

    if !data.is_null() && len > 0 {
        let payload = unsafe { std::slice::from_raw_parts(data, len) };
        state.process_payload(payload);
    }
}

// 注册带上下文的回调
fn setup_with_state() {
    let state = Arc::new(Mutex::new(CallbackState::new()));
    let leaked: *mut Arc> = Box::into_raw(Box::new(state));

    unsafe {
        register_callback_with_ud(
            on_event_with_context,
            leaked as *mut c_void,
        );
    }
    // 注意：需要在适当时机释放 leaked 指针
}

5.3 C 到 Rust 的异步回调

当 C 回调在不同于 Rust 异步运行时的线程中触发时，需要特殊的同步机制：

> = OnceCell::new();

extern "C" fn async_callback(result: i32) {
    if let Some(tx) = RESULT_CHANNEL.get() {
        let _ = tx.send(result);
    }
}

// Rust 异步端接收
async fn wait_for_result(timeout: Duration) -> Option {
    let rx = /* 从通道接收 */;
    timeout(timeout, rx).await.ok()?
}

第六章：构建混合语言项目

6.1 使用 build.rs 编译外部 C 代码

// build.rs
fn main() {
    // 方法1：使用 cc crate 编译 C 代码
    cc::Build::new()
        .file("src/native/compress.c")
        .file("src/native/crypto.c")
        .include("src/native/include")
        .define("NDEBUG", None)
        .flag("-O3")
        .compile("native");

    // 方法2：链接系统库
    println!("cargo:rustc-link-lib=z");        // libz
    println!("cargo:rustc-link-lib=ssl");      // OpenSSL
    println!("cargo:rustc-link-lib=dylib=mylib"); // 动态库

    // 方法3：指定库搜索路径
    println!("cargo:rustc-link-search=native=/usr/local/lib");
    println!("cargo:rustc-link-search=native=./lib");
}

Cargo.toml 的构建依赖：

[build-dependencies]
cc = "1.0"
bindgen = "0.69"

6.2 使用 CMake 构建复杂 C++ 项目

对于复杂的 C++ 项目，可以在 build.rs 中调用 cmake：

// build.rs
fn main() {
    let dst = cmake::Config::new("cpp-lib")
        .define("BUILD_SHARED_LIBS", "OFF")
        .define("CMAKE_BUILD_TYPE", "Release")
        .build();

    println!("cargo:rustc-link-search=native={}/lib", dst.display());
    println!("cargo:rustc-link-lib=static=mylib");
    println!("cargo:rustc-link-lib=dylib=stdc++"); // Linux
    // 或 cargo:rustc-link-lib=dylib=c++       // macOS
}

6.3 条件编译与平台差异

// 处理不同平台的库名称
#[cfg(target_os = "linux")]
const NATIVE_LIB: &str = "libmylib.so";

#[cfg(target_os = "macos")]
const NATIVE_LIB: &str = "libmylib.dylib";

#[cfg(target_os = "windows")]
const NATIVE_LIB: &str = "mylib.dll";

// 处理 Windows 上的 stdcall 调用约定
#[cfg(target_os = "windows")]
extern "stdcall" {
    fn WindowsSpecificFunc(arg: i32) -> i32;
}

#[cfg(not(target_os = "windows"))]
extern "C" {
    fn UnixSpecificFunc(arg: i32) -> i32;
}

第七章：实战案例——封装 libzstd 压缩库

让我们通过一个完整案例来整合前面所有知识：封装 Facebook 的 Zstandard 压缩库。

mod ffi {
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}

pub struct ZstdCompressor {
    cctx: *mut ffi::ZSTD_CCtx,
}

impl ZstdCompressor {
    pub fn new(level: i32) -> Result {
        let cctx = unsafe { ffi::ZSTD_createCCtx() };
        if cctx.is_null() {
            return Err(ZstdError::OOM);
        }
        unsafe {
            ffi::ZSTD_CCtx_setParameter(cctx, ffi::ZSTD_c_compressionLevel, level);
            ffi::ZSTD_CCtx_setParameter(cctx, ffi::ZSTD_checksumFlag, 1);
        }
        Ok(Self { cctx })
    }

    pub fn compress(&self, input: &[u8]) -> Result, ZstdError> {
        let max_size = unsafe { ffi::ZSTD_compressBound(input.len()) };
        let mut output = Vec::with_capacity(max_size);
        let compressed_size = unsafe {
            ffi::ZSTD_compress2(
                self.cctx,
                output.as_mut_ptr() as *mut c_void,
                output.capacity(),
                input.as_ptr() as *const c_void,
                input.len(),
            )
        };
        if unsafe { ffi::ZSTD_isError(compressed_size) } != 0 {
            return Err(ZstdError::CompressFailed(unsafe {
                ffi::ZSTD_getErrorName(compressed_size)
            }));
        }
        unsafe { output.set_len(compressed_size); }
        Ok(output)
    }
}

impl Drop for ZstdCompressor {
    fn drop(&mut self) {
        unsafe { ffi::ZSTD_freeCCtx(self.cctx) };
    }
}

// 错误类型
#[derive(Debug)]
pub enum ZstdError {
    OOM,
    CompressFailed(*const std::os::raw::c_char),
}

impl std::fmt::Display for ZstdError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::OOM => write!(f, "FFI 内存分配失败"),
            Self::CompressFailed(name) => {
                let name = unsafe { CStr::from_ptr(*name) };
                write!(f, "压缩失败: {}", name.to_string_lossy())
            }
        }
    }
}

impl std::error::Error for ZstdError {}

// 使用示例
fn main() {
    let compressor = ZstdCompressor::new(3).unwrap();
    let input = b"Rust FFI 深度实战 — 安全高效地与 C/C++ 互操作";
    let compressed = compressor.compress(input).unwrap();
    println!("{} 字节 -> {} 字节 (压缩率 {:.1}%)",
        input.len(), compressed.len(),
        100.0 * compressed.len() as f64 / input.len() as f64
    );
}

关键设计决策：

• 内部持有裸指针 (*mut ZSTD_CCtx)，不暴露给 API 使用者
• RAII 管理资源——Drop 中释放上下文
• 所有unsafe操作封装在安全方法中
• 错误类型使用原生 Rust 的 Result + Error trait
• 无需暴露 FFI 细节的纯净 API

第八章：性能分析与优化

8.1 FFI 调用的开销来源

FFI 调用本身有一定开销——每次跨越语言边界时，编译器无法进行内联优化，且需要保存/恢复寄存器状态。主要开销来源包括：

• 调用约定转换：寄存器/栈布局的适配（通常 1-5 ns）
• 安全检查：如 Rust 对裸指针的操作、C 的参数校验
• 边界处的数据拷贝：字符串转换、结构体复制
• 失去优化机会：跨边界无法内联、无法向量化、LTO 失效

8.2 减少 FFI 调用次数的策略

// 差：每个元素一次 FFI 调用
for item in items.iter() {
    unsafe { lib_process_single(item) };  // N 次调用
}

// 好：批量处理，一次 FFI 调用
unsafe {
    lib_process_batch(items.as_ptr(), items.len());  // 1 次调用
}

// 避免不必要的字符串转换
// 差：每次调用都分配 C 字符串
for name in names.iter() {
    let cname = CString::new(name.as_bytes()).unwrap();
    unsafe { lib_register(cname.as_ptr()) };
}

// 好：缓存 C 字符串
let cnames: Vec = names.iter()
    .map(|n| CString::new(n.as_bytes()).unwrap())
    .collect();
for cname in cnames.iter() {
    unsafe { lib_register(cname.as_ptr()) };
}

8.3 性能基准

以下是不同 FFI 模式的典型开销对比（x86_64 Linux，ns/次）：

第九章：安全与错误的边界处理

9.1 Panic 安全

跨 FFI 边界的 panic 是未定义行为！如果 Rust 代码在回调中 panic 并展开到 C 帧中，后果可能是灾难性的：

// ❌ 危险：panic 可能跨越 FFI 边界
#[no_mangle]
pub extern "C" unsafe fn process(data: *const u8, len: usize) -> i32 {
    let slice = std::slice::from_raw_parts(data, len);
    let value = slice[100];  // 如果 len < 100，panic！
    value as i32
}

// ✅ 正确：用 catch_unwind 捕获 panic
#[no_mangle]
pub extern "C" fn safe_process(data: *const u8, len: usize) -> i32 {
    let result = std::panic::catch_unwind(|| {
        if data.is_null() || len == 0 { return -1i32; }
        let slice = unsafe { std::slice::from_raw_parts(data, len) };
        slice.get(100).copied().unwrap_or(-1) as i32
    });
    result.unwrap_or(-1)
}

// 更优雅的模式：边界处统一使用 catch_unwind
macro_rules! ffi_guard {
    ($body:expr) => {
        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| $body)) {
            Ok(result) => result,
            Err(_) => -1, // panic 时返回错误码
        }
    };
}

生产环境的最佳实践：在 Cargo.toml 中设置 panic = "abort"，这样 panic 直接终止进程，不会展开（也避免展开导致 UB）：

[profile.release]
panic = "abort"

9.2 空指针与前置条件

// 明确文档化的前置条件
/// # Safety
/// `ptr` 必须是一个有效的、由 C 端分配的非空指针。
/// 本函数将接管该指针的所有权并在完成时释放。
pub unsafe fn consume_buffer(ptr: *mut u8, len: usize) {
    assert!(!ptr.is_null(), "consume_buffer: ptr 为空");
    assert!(len > 0, "consume_buffer: len 为 0");
    // 转换为 Rust 的 Vec 并让自动管理内存
    drop(Vec::from_raw_parts(ptr, len, len));
}

// 或者对公 API 使用 Option 包装
pub fn safe_consume_buffer(ptr: *mut u8, len: usize) -> Result<(), FfiError> {
    if ptr.is_null() { return Err(FfiError::NullPointer); }
    if len == 0 { return Err(FfiError::InvalidLength); }
    unsafe { drop(Vec::from_raw_parts(ptr, len, len)); }
    Ok(())
}

9.3 线程安全标记

Send 和 Sync trait 是 Rust 线程安全的核心保证。FFI 类型默认不实现它们，你需要根据 C 库的实际行为手动声明：

// 如果 ctx 的内部状态不受多线程并发访问保护：
impl !Send for MyLibContext {}
impl !Sync for MyLibContext {}

// 如果 ctx 有内部同步（互斥锁）：
unsafe impl Send for MyLibContext {}
unsafe impl Sync for MyLibContext {}

// 对于引用计数式共享的 C 对象，使用原子操作实现 Sync
struct SharedCObject {
    ptr: *mut ffi::shared_t,
}
unsafe impl Send for SharedCObject {}
unsafe impl Sync for SharedCObject {}  // 假设 lib 有内部原子引用计数

第十章：调试与工具链

10.1 使用 Valgrind/ASan 检测内存问题

FFI 代码是内存错误的温床。使用 AddressSanitizer 可以检测到大多数问题：

# 编译时启用 ASan
RUSTFLAGS="-Z sanitizer=address" cargo build --target x86_64-unknown-linux-gnu

# 对于 C 代码，同时启用
CFLAGS="-fsanitize=address -fno-omit-frame-pointer" cmake ..

10.2 验证类型布局一致性

在集成测试中验证 Rust 和 C 的类型布局：

#[test]
fn verify_layout_compatibility() {
    // 使用与 bindgen 相同的 clang 标志
    let c_layout = get_c_layout::();
    let rust_layout = get_rust_layout::();
    assert_eq!(c_layout.size, rust_layout.size, "大小不匹配");
    assert_eq!(c_layout.align, rust_layout.align, "对齐不匹配");
    assert_eq!(c_layout.field_offsets, rust_layout.field_offsets, "字段偏移不匹配");
}

10.3 常见错误清单

• ABI 不匹配：使用 extern "C" 而不仅仅是 extern；确保结构体使用 #[repr(C)]
• 悬空指针：C 端保存了 Rust 分配的指针，但 Rust 侧已释放——使用 Box::into_raw + 显式释放函数
• 编码错误：C 字符串非 UTF-8 时使用 to_str() 导致 panic——使用 to_string_lossy() 或 to_str()?
• 忘记释放：CString::into_raw 后未配对调用 from_raw——始终提供对应的释放函数
• 生命周期错误：将对临时值的引用传递给 C——
• 未对齐访问：#[packed] 结构体的字段可能不对齐——使用 read_unaligned
• 混用分配器：Rust 的 Box 用 C 的 free 释放——始终谁分配谁释放

第十一章：高级主题

11.1 与 C++ 虚函数表互操作

// C++ 类的虚函数表在头部有一个 vptr
#[repr(C)]
struct CppVtable {
    destroy: unsafe extern "C" fn(*mut c_void),
    process: unsafe extern "C" fn(*mut c_void, *const u8, usize) -> i32,
    get_name: unsafe extern "C" fn(*const c_void) -> *const c_char,
}

#[repr(C)]
struct CppObject {
    vtable: *const CppVtable,
}

impl CppObject {
    pub unsafe fn process(&self, data: &[u8]) -> i32 {
        ((*self.vtable).process)(self as *const _ as *mut c_void, data.as_ptr(), data.len())
    }
}

11.2 与 Objective-C 和 Swift 互操作

macOS/iOS 开发中需要与 Objective-C Runtime 交互。虽然生态不如 Swift 官方 toolchain 丰富，但 objc crate 提供了基础支持：

#[no_mangle]
#[cfg(target_os = "windows")]
pub unsafe extern "system" fn ProcessData(
    data: *const u8,
    len: u32,
    output_len: *mut u32,
) -> i32 {
    if data.is_null() || output_len.is_null() { return -1; }
    let input = std::slice::from_raw_parts(data, len as usize);
    let result = process_in_rust(input);
    *output_len = result.len() as u32;
    // 使用 CoTaskMemAlloc 以便 .NET 端 Marshal.FreeCoTaskMem 释放
    let leaked = result.leak();
    leaked.as_ptr() as i32  // 简化示例，实际需正确处理指针
}