Rust 调用 C 库实战:使用 bindgen 和 FFI 把遗留代码包进安全接口

flowchart LR
    A["C 头文件\n(log_parser.h)\n定义函数签名和结构体"] --> B["bindgen 解析\n调用 libclang 分析 AST"]
    B --> C["自动生成 Rust 绑定\n(bindings.rs)\nunsafe extern \"C\" 声明"]
    C --> D["safe_wrapper.rs\n手动编写的安全外壳"]
    D --> D1["• 类型安全的方法签名\n(String 替代 *const c_char)"]
    D --> D2["• 自动资源管理\n(Drop trait 释放 C 对象)"]
    D --> D3["• 错误转换\n(原始 int → Result<>)"]
    D1 --> E["Rust 调用者\n像普通 Rust 库一样使用\n无需接触 unsafe"]
    D2 --> E
    D3 --> E

// log_parser.h — 我们需要封装的 C 库
typedef struct LogParser LogParser;  // 不透明指针
LogParser* log_parser_create(const char* pattern);
int log_parser_parse(LogParser* parser, const char* line, char* output, int output_len);
void log_parser_destroy(LogParser* parser);

// build.rs — 构建脚本, 在 cargo build 前自动运行
fn main() {
    // 告诉 cargo 需要链接的 C 库名称
    // 如果 C 库是静态编译的 (.a), 用 static 链接
    println!("cargo:rustc-link-lib=static=log_parser");
    // 如果 C 库依赖系统路径, 用 println 指定搜索目录
    println!("cargo:rustc-link-search=native=/usr/local/lib");
    // 用 bindgen 解析 C 头文件, 生成 Rust 绑定
    let bindings = bindgen::Builder::default()
        .header("vendor/log_parser.h")  // C 头文件路径
        .clang_arg("-Ivendor/")         // 传递 Clang 的 include 路径
        // 让生成的枚举和函数符合 Rust 命名规范
        .rustfmt_bindings(true)
        // 对于不透明类型, 使用更好的 Rust 表示
        .opaque_type("LogParser")
        // 禁止 derive Copy — C 结构体通常不应该随便 Copy
        .derive_copy(false)
        .generate()
        .expect("无法生成 bindgen 绑定");
    // 将生成的 Rust 代码写入 OUT_DIR 目录
    let out_path = std::path::PathBuf::from(
        std::env::var("OUT_DIR").unwrap()
    );
    bindings
        .write_to_file(out_path.join("bindings.rs"))
        .expect("无法写入绑定文件");
}

// safe_wrapper.rs — 手动封装的安全 API
use std::ffi::{CStr, CString};
use std::os::raw::c_int;
// 自动生成的绑定 — include! 宏动态引入
include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
/// 安全的日志解析器 — 包装 C 库的不透明指针
pub struct SafeLogParser {
    // 内层持有 C 的原始指针 — 外部用户完全看不到
    inner: *mut LogParser,
}
impl SafeLogParser {
    /// 创建解析器 — 错误类型明确, 不用 int 返回值
    pub fn new(pattern: &str) -> Result<Self, String> {
        // Rust String → C 的 null-terminated 字符串
        let c_pattern = CString::new(pattern)
            .map_err(|e| format!("模式字符串包含 null 字节: {}", e))?;
        // 调用 C 构造函数 — unsafe 在此处被隔离
        let ptr = unsafe { log_parser_create(c_pattern.as_ptr()) };
        if ptr.is_null() {
            Err("创建解析器失败: 可能是不支持的模式".into())
        } else {
            Ok(SafeLogParser { inner: ptr })
        }
    }
    /// 解析一行日志 — 返回 Rust String, 不是原始缓冲区
    pub fn parse(&self, line: &str) -> Result<String, String> {
        let c_line = CString::new(line)
            .map_err(|_| "输入包含 null 字节".to_string())?;
        // 预分配输出缓冲区 — Rust 管理, 不必手动 free
        let mut output_buf: Vec<u8> = vec![0u8; 4096];
        let len = output_buf.len() as c_int;
        // 调用 C 的解析函数 — unsafe 边界明确
        let result = unsafe {
            log_parser_parse(
                self.inner,
                c_line.as_ptr(),
                output_buf.as_mut_ptr() as *mut i8,
                len,
            )
        };
        if result < 0 {
            return Err(format!("解析失败, 错误码: {}", result));
        }
        // 从 C 字符串创建 Rust String — 正确处理 null 终止
        let c_output = unsafe { CStr::from_ptr(output_buf.as_ptr() as *const i8) };
        Ok(c_output.to_string_lossy().into_owned())
    }
}
// Drop trait: 自动释放 C 库分配的内存
impl Drop for SafeLogParser {
    fn drop(&mut self) {
        if !self.inner.is_null() {
            // unsafe: 调用 C 的销毁函数, 保证资源不泄漏
            unsafe { log_parser_destroy(self.inner); }
        }
    }
}
// 禁止 Send 和 Sync — C 库内部可能有全局状态
// 如果不确定 C 库是否线程安全, 就保持保守
// impl !Send for SafeLogParser {}
// impl !Sync for SafeLogParser {}

// main.rs — 使用者代码
mod safe_wrapper;
use safe_wrapper::SafeLogParser;
fn main() -> Result<(), String> {
    let parser = SafeLogParser::new(r"\d{4}-\d{2}-\d{2}")?;
    let result = parser.parse("2024-01-15 ERROR: 连接超时")?;
    println!("解析结果: {}", result); // parser 离开作用域自动释放
    Ok(())
}