CXX 桥接中的 C++ 异常处理：Comprehensive Rust 课程 Android 互操作实战指南

在 Google Android 团队的 Rust 课程（Comprehensive Rust，本仓库）中，Android 互操作章节专门讲解了如何借助 CXX crate 在 Rust 与 C++ 之间安全互操作。本指南聚焦其中 C++ Error Handling 一节，系统讲解：当 C++ 函数抛异常时，CXX 桥如何将其转换为 Rust 侧的 Result；反之，未声明 Result 返回值的 C++ 函数抛异常时又会发生什么。读完本文，你将掌握 CXX 桥接层异常语义的完整规则、正确的声明方式与规避进程终止的实战写法。

一、问题背景：CXX 桥如何连接 Rust 与 C++ 的错误模型

Rust 与 C++ 拥有两套截然不同的错误处理模型：

• Rust：以 Result<T, E> 值作为一等公民，错误是显式传播的返回值，不依赖运行时机制；
• C++：错误通常通过异常（exception）抛出，异常沿调用栈隐式传播。

当两类代码通过 CXX 桥互相调用时，两套模型无法直接对应。CXX 桥提供的关键转换规则是：

• C++ 抛出的异常，可以在 Rust 侧以 Err 值接收；
• Rust 返回的 Result，可以在 C++ 侧以 rust::Error 异常接收。

这一双向转换正是本文要展开的核心机制。CXX 的总体架构可参见 cpp.md 中引用的架构图（overview.svg）：桥接声明（#[cxx::bridge]）会同时生成 Rust 侧与 C++ 侧的两份绑定代码，异常语义的转换正是在这层生成的胶水代码中完成的。

二、核心机制一：声明返回 Result 的 C++ 函数自动捕获异常

2.1 规则原文

原文档 明确给出两条行为规则，这是理解整个机制的基石：

• C++ functions declared to return a Result will catch any thrown exception on the C++ side and return it as an Err value to the calling Rust function.
• 声明为返回 Result 的 C++ 函数，会捕获 C++ 侧抛出的任何异常，并以 Err 值返回给调用它的 Rust 函数。

也就是说，只要你把 C++ 函数的签名声明为返回 Result<T>，CXX 生成的桥接代码就会在 C++ 侧包裹一层 try/catch：C++ 实现内部无论抛出何种异常，都会被捕获并转换为 Rust 侧可匹配的 Err。

2.2 配套代码示例

原文档通过课程内的代码片段（源文件为 third_party/cxx/book/snippets.rs 中的 cpp_exception 锚点）给出可运行示例：

#[cxx::bridge]
mod ffi {
    unsafe extern "C++" {
        include!("example/include/example.h");
        fn fallible(depth: usize) -> Result<String>;
    }
}

fn main() {
    if let Err(err) = ffi::fallible(99) {
        eprintln!("Error: {}", err);
        process::exit(1);
    }
}

要点拆解：

• unsafe extern "C++" 块用于声明 C++ 侧的函数与类型。根据课程 C++ Bridge Declarations 一节的说明，unsafe extern 块允许声明“从 Rust 侧调用是安全的”C++ 函数；同时 CXX 会在编译期对签名做静态断言，确保你声明的签名与 C++ 头文件中的真实声明严格一致。
• 关键声明 fn fallible(depth: usize) -> Result<String> 表明该 C++ 函数返回 Result<String>。正是这一返回类型声明，触发了 CXX 生成异常捕获胶水。
• 调用侧使用 if let Err(err) = ... 模式匹配：当 C++ 侧抛异常时，这里拿到的就是 Err(err)，err 的 Display 输出即错误信息。
• 代码片段来自课程书稿，独立编译时需自行补全缺失的导入（如 use std::process;）。

2.3 错误信息从哪来

值得强调的是，Err 中包含的错误信息字符串来自 C++ 异常对象的 what() 消息。课程配套的 Rust Error Handling 一节从反向印证了这一点：Rust 侧 Result 的错误消息取自错误类型的 Display impl，而在 C++ 侧转换为异常时统一为 rust::Error 类型，主要暴露获取错误消息字符串的接口。两条规则合在一起，构成完整的双向消息传递闭环：

方向	转换结果	错误信息载体
C++ 异常 → Rust	捕获为 Err 值	C++ 异常对象的 what()
Rust Result → C++	抛出 rust::Error 异常	Rust 错误类型的 Display 输出

三、核心机制二：未声明 Result 时抛异常将终止进程

3.1 规则原文

原文档给出了第二条同样重要的行为规则：

• If an exception is thrown from an extern "C++" function that is not declared by the CXX bridge to return Result, the program calls C++'s std::terminate. The behavior is equivalent to the same exception being thrown through a noexcept C++ function.
• 如果异常从一个未被 CXX 桥声明为返回 Result 的 extern "C++" 函数中抛出，程序会调用 C++ 的 std::terminate。其行为等价于该异常穿过一个 noexcept C++ 函数。

3.2 为什么必须终止

这条规则的含义是：异常必须被“圈养”在桥接层声明的 Result 边界内。如果你漏写了 Result 返回类型，CXX 生成的桥接代码不会为这次调用生成 try/catch 包装，异常就会沿着调用栈向上逃逸——一旦穿过由 C 风格 ABI 构成的 FFI 边界，就进入了未定义行为（UB）地带。为此 CXX 选择调用 std::terminate 直接终止进程，这正是 C++ 中 noexcept 函数抛出异常时的标准结局。

对开发者来说，这是一条需要时刻警惕的硬约束：

• 症状：程序运行时直接终止，不会给你任何错误处理机会；
• 根因：C++ 函数签名声明中缺少 Result<T> 返回类型；
• 修复：在 #[cxx::bridge] 的 extern "C++" 块中，为该函数补上 Result<...> 返回类型声明。

四、在真实示例工程中观察 C++ 侧实现

课程的 CXX 示例工程位于 third_party/cxx/blobstore，其 C++ 头文件 blobstore.h 展示了典型的桥接 C++ 类定义。结合该示例可以看到声明风格的完整形态：

#[cxx::bridge(namespace = "org::blobstore")]
mod ffi {
    struct BlobMetadata {
        size: usize,
        tags: Vec<String>,
    }

    extern "Rust" {
        type MultiBuf;
        fn next_chunk(buf: &mut MultiBuf) -> &[u8];
    }

    unsafe extern "C++" {
        include!("include/blobstore.h");

        type BlobstoreClient;
        fn new_blobstore_client() -> UniquePtr<BlobstoreClient>;
        fn put(self: Pin<&mut BlobstoreClient>, parts: &mut MultiBuf) -> u64;
        fn tag(self: Pin<&mut BlobstoreClient>, blobid: u64, tag: &str);
        fn metadata(&self, blobid: u64) -> BlobMetadata;
    }
}

实际接入异常处理时，只需把可能抛异常的成员函数（如 put）的返回类型改为 Result<u64>，CXX 就会自动生成捕获逻辑。注意 type-mapping.md 中的类型映射表：u64、String、Vec<T> 等类型都有对应的桥接映射（如 Rust String 对应 C++ rust::String，Rust Vec<T> 对应 C++ rust::Vec<T>），Result<T, E> 同样遵循这套映射规则参与签名声明。

五、实战要点与最佳实践

综合原文档两条规则与课程配套内容，在 Android 项目中落地 CXX 异常处理时，建议遵循以下实践：

1. 统一用 Result 圈定可失败边界：凡 C++ 实现可能抛异常的函数，一律在桥接声明中声明为返回 Result<T>，让错误以 Err 值显式流入 Rust 侧，交由调用方处理。
2. 保持签名严格一致：CXX 会对签名做静态断言（见 cpp-bridge.md），Result 声明必须与 C++ 头文件的真实函数签名匹配，改动 C++ 侧后需同步更新桥接声明。
3. 在调用方主动匹配错误：使用 if let Err(err) = ... 或 ? 运算符处理 Err，并确保日志输出 err 的 Display 信息以便排查。
4. 牢记终止语义：未声明 Result 的 C++ 函数抛异常 = std::terminate = 进程终止，等价于 C++ 的 noexcept 违约。不要把任何“可能失败”的调用建立在未声明 Result 的桥接函数上。
5. 配合 Rust 侧规则使用：Rust 函数返回 Result 会被转换为 C++ 侧的 rust::Error 异常；而 Rust panic 越过 C++ 边界时同样会立即终止进程（见 rust-result.md），因此桥接函数内部也应力求不 panic。

六、延伸阅读

• C++ Error Handling（本文主题文档）
• Rust Error Handling（反向方向：Result → 异常）
• C++ Bridge Declarations（unsafe extern 与静态断言）
• Additional Types（桥接类型映射表）
• With C++（CXX 互操作总览与架构图）
• CXX 示例工程源码 与 C++ 头文件
• 课程片段源文件（含 cpp_exception 锚点代码）