1 / 4概念
Feature: Interop
unsafe 不是关闭检查,而是把证明责任从编译器转给开发者:代码必须满足别名、对齐、初始化和有效性等不变量。判断标准不是“能不能写”,而是能否写出不变量、调用方义务和验证它的测试。
1 概念
1.1 一句话定义
unsafe 块允许五种操作:解引用裸指针、调用 unsafe 函数、读写可变静态变量、实现 unsafe trait、访问 union 字段。FFI 通过 extern "C" 与 #[unsafe(no_mangle)] 暴露稳定的二进制接口;跨语言边界没有 Rust 的借用检查,所有契约都要用文档和测试固定。
1.2 它解决什么问题
- 操作系统接口、硬件寄存器和零拷贝缓冲区必须直接操作地址。
- 已有 C/C++ 库无法重写时,需要稳定的调用边界。
- 某些数据结构与算法需要突破借用检查的表达能力。
- 性能敏感的代码需要显式控制布局、对齐与分配。
Rust 把 unsafe 缩小到最小块,并要求用安全抽象包住它;代价是每个 unsafe 块都要人工证明。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 所有权与借用规则 | Ownership and Borrowing |
| trait、泛型与错误类型 | Traits, Generics, and Errors |
async、执行器与 Send/Sync | Async and Concurrency |
| Cargo 依赖与构建产物 | Cargo and Quality Gates |
| 虚拟内存与页表 | Memory Management |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
unsafe | 由开发者承担不变量的代码块 | 不是“关闭所有检查” |
| UB | 未定义行为,编译器可任意假设 | 不是“崩溃” |
| 裸指针 | *const T 与 *mut T | 可以是空或悬垂 |
| 别名 | 多个指针指向同一内存 | 与 &mut T 互斥 |
| 对齐 | 地址必须满足类型要求 | 不是字节大小 |
| provenance | 指针的来源与可访问范围 | 不是单纯整数地址 |
MaybeUninit | 可能未初始化的值 | 不能用 assume_init 猜 |
transmute | 按位重解释类型 | 长度与有效性都不检查 |
repr(C) | C 兼容的内存布局 | Rust 默认布局不保证 |
extern "C" | C 调用约定 | 不保证 panic 安全 |
catch_unwind | 捕获展开的 panic | 不能捕获 abort |
| Miri | 解释执行并检测 UB 的工具 | 只覆盖执行的路径 |
2 机制
2.1 心智模型
安全 Rust 是编译器替开发者签合同:它保证引用有效、别名不冲突、值已初始化。unsafe 是把合同改成“开发者签名”,编译器仍然会优化,并且会假设合同成立。一旦合同被违反,行为不再有保证,错误可能出现在很远的地方。
2.2 机制拆解
- 五种能力:解引用裸指针、调用
unsafe函数、读写static mut、实现unsafetrait、访问 union 字段;只有这五种操作需要unsafe。 - 有效性:
bool只能是 0 或 1,char必须是合法标量值,枚举判别式必须落在变体内,引用必须非空且对齐。 - 别名规则:
&mut T存在期间不能有其他读写路径;&T存在期间不能有写入;违反即 UB,即使没有实际崩溃。 - 初始化:
MaybeUninit<T>允许未初始化;读取前必须确认已写入,assume_init由调用方负责。 - 布局:
repr(C)固定字段顺序与对齐;repr(transparent)只包裹一个字段;默认repr(Rust)不保证顺序。 - panic 边界:panic 跨过
extern "C"是 UB;要么catch_unwind,要么panic = "abort",要么使用extern "C-unwind"。 - 所有权跨边界:
Box::into_raw交出裸指针,Box::from_raw收回;分配与释放必须使用同一个分配器。 Send/Sync:unsafe impl Send是承诺类型可以安全转移;实现者要自行证明内部状态没有数据竞争。
2.3 完整枚举
unsafe 的完整操作集合:
| 操作 | 例子 | 必须证明 |
|---|---|---|
| 解引用裸指针 | *ptr | 指针有效、对齐、已初始化、不别名 |
调用 unsafe 函数 | from_raw_parts(...) | 该函数文档列出的全部前置条件 |
| 读写可变静态 | static mut COUNTER | 无并发访问或已同步 |
实现 unsafe trait | unsafe impl Send for T | 类型满足 trait 的安全契约 |
| 访问 union 字段 | union.field | 当前位模式对应所读类型 |
FFI 边界的完整形式:
| 形式 | 用途 | 注意 |
|---|---|---|
extern "C" fn | 导出函数给 C 调用 | 参数与返回值必须 C 兼容 |
unsafe extern "C" { ... } | 声明外部函数 | 调用方要满足外部契约 |
#[unsafe(no_mangle)] | 保持符号名 | Rust 2024 起需 unsafe(...) |
#[repr(C)] | 结构体布局兼容 C | 字段顺序与对齐固定 |
bindgen | 从 C 头文件生成声明 | 生成代码仍是 unsafe |
cbindgen | 从 Rust 生成 C 头文件 | 检查生成结果的 ABI |
Box::into_raw / from_raw | 跨边界转移堆内存 | 分配器必须一致 |
CString / CStr | 处理 NUL 结尾字符串 | 生命周期与所有权 |
wasm-bindgen | 导出到 WebAssembly | JS 侧类型映射 |
PyO3 / napi-rs | 导出到 Python / Node | 运行时与 GC 交互 |
未定义行为的完整类别:
| 类别 | 例子 | 后果 |
|---|---|---|
| 悬垂访问 | 释放后解引用 | 读到旧数据或崩溃 |
| 别名违反 | 同时持有 &mut 与读指针 | 优化后结果错误 |
| 对齐错误 | 用 u8 指针读 u64 | 平台相关崩溃或慢路径 |
| 无效值 | bool 为 2、枚举判别式越界 | 分支不可预测 |
| 数据竞争 | 多线程无同步写同一位置 | 读写撕裂 |
| 重复释放 | 两个所有权指向同一分配 | 堆损坏 |
| 未初始化读取 | assume_init 早于写入 | 随机值传播 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
Option<&T> 大小 | 1 个指针 | niche 优化 |
Option<NonNull<T>> 大小 | 1 个指针 | 空指针保留给 None |
| Miri 运行速度 | 慢 10 到 100 倍 | 只适合小用例 |
| FFI 调用开销 | 纳秒级 | 接近普通函数调用 |
| 对齐要求 | 通常等于类型大小 | 不保证时用 align |
| unsafe 代码占比 | 越低越好 | cargo geiger 可统计 |
3 实践
3.1 最小示例
一个导出给 C 的校验函数,用安全包装隔离不安全的前置条件:
use std::slice;
/// # Safety
///
/// `ptr` must be non-null and valid for `len` reads of `u8`.
#[unsafe(no_mangle)]
pub unsafe extern "C" fn checksum(ptr: *const u8, len: usize) -> u32 {
if ptr.is_null() || len == 0 {
return 0;
}
// SAFETY: the caller guarantees a valid, readable region of `len` bytes.
let bytes = unsafe { slice::from_raw_parts(ptr, len) };
bytes
.iter()
.fold(0u32, |sum, byte| sum.wrapping_add(u32::from(*byte)))
}
pub fn checksum_bytes(bytes: &[u8]) -> u32 {
// SAFETY: a slice always has a non-null, aligned, initialized pointer.
unsafe { checksum(bytes.as_ptr(), bytes.len()) }
}
追踪一次调用:checksum_bytes 接收安全切片,指针与长度由切片保证有效。checksum 先排除空指针与零长度,再构造同样长度的只读切片,最后用 wrapping_add 避免调试构建的溢出 panic。C 调用方必须自行满足 # Safety 段;Rust 调用方应只使用安全包装。
3.2 常用操作与参数
| 操作 | 写法 | 说明 |
|---|---|---|
| 解引用 | unsafe { *ptr } | 指针必须有效 |
| 构造切片 | slice::from_raw_parts(ptr, len) | 非空、对齐、初始化 |
| 可写切片 | slice::from_raw_parts_mut(ptr, len) | 额外要求无别名 |
| 未初始化 | MaybeUninit::<T>::uninit() | 写入后再 assume_init |
| 类型重解释 | ptr.cast::<U>() | 检查大小与对齐 |
| 位重解释 | transmute::<A, B>(a) | 最后手段,先证明布局 |
| 导出符号 | #[unsafe(no_mangle)] | 检查命名冲突 |
| 声明外部 | unsafe extern "C" { fn f(); } | 调用处仍需 unsafe |
| 捕获 panic | catch_unwind(AssertUnwindSafe(...)) | 边界处使用 |
| 转移所有权 | Box::into_raw(b) | 配套 Box::from_raw |
| 静态可变 | static mut | 优先 AtomicUsize 或 OnceLock |
| 检查 UB | cargo miri test | 覆盖不到的路径仍需审查 |
3.3 标准流程
- 先问能否用安全 Rust 表达;只有明确收益时才引入
unsafe。 - 写出安全不变量:指针有效性、别名、对齐、初始化、所有权。
- 把
unsafe缩到最小块,块前写// SAFETY:说明。 - 用安全 API 包住
unsafe,让调用方不需要理解内部不变量。 - 为每条不变量写测试,再用 Miri、sanitizer 或 fuzz 验证。
- 在 FFI 边界固定 ABI:
repr(C)、调用约定、panic 策略与分配器。 - 用
cargo geiger统计 unsafe 面积,并逐个审查。
3.4 与相邻技术的组合
- C/C++:
bindgen与cbindgen维护头文件契约;跨边界用返回码而非异常。 - WASM:
wasm-bindgen把 Rust 编译成浏览器模块,注意线性内存与 JS 类型映射。 - Python:
PyO3处理引用计数与 GIL,跨语言错误要转成 Python 异常。 - Node:
napi-rs生成原生扩展,注意事件循环与线程安全。 - 操作系统:
libc与nix封装系统调用,错误码要转成io::Error。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 是否必须 unsafe | 否 / 少量 / 大量 | 审查与测试成本 |
| 边界形式 | 纯 Rust / C ABI / WASM / 宿主 | 生命周期与所有权规则 |
| panic 策略 | unwind / abort | 跨边界是否安全 |
| 分配器 | 系统 / 自定义 / 跨语言 | 释放责任归属 |
| 移植性 | 单平台 / 多平台 | 布局、对齐、字节序 |
| 验证手段 | Miri / sanitizer / fuzz | 覆盖不到的路径 |
3.6 决策规则
- 安全 Rust 能表达时不要用
unsafe。 - 每个
unsafe块都应有一句能验证的// SAFETY:理由。 - 跨 FFI 边界禁止 panic,错误用返回码或 out 参数。
- 跨边界传递的结构体应使用
repr(C)并固定字段布局。 - 释放跨边界内存时,分配与释放必须由同一侧、同一分配器完成。
transmute只用于布局已证明且无更安全替代的场景。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| 纯安全 Rust | 无 UB 证明负担 | 某些结构难表达 | 大多数应用 |
小范围 unsafe | 性能与表达力 | 需人工证明 | 容器、解析器 |
| C ABI FFI | 复用成熟库 | 构建与 ABI 风险 | 系统集成 |
| WASM | 沙箱、跨平台 | 边界与内存拷贝 | 浏览器、插件 |
| 子进程 | 隔离强、语言无关 | 启动与 IPC 成本 | 工具、隔离任务 |
| 重写为 Rust | 单一工具链 | 时间与正确性成本 | 核心依赖 |
3.8 何时不该用
- 只是为了绕过借用检查时,不要用
unsafe。 - 团队没有 UB 与内存模型经验时,不安全代码应交给专家审查。
- 跨语言调用只发生一两次且性能不敏感时,子进程或 HTTP 更简单。
- 需要多平台二进制兼容时,先确认 ABI、对齐与调用约定。
- 不能用 Miri 或 sanitizer 覆盖的路径,宁可不用
unsafe。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 段错误 | 空指针、悬垂指针、越界 | 校验指针与长度,用 Miri 复现 |
| 结果随优化等级变化 | 别名或未初始化 UB | 审查 &mut 与裸指针共存 |
| 平台相关崩溃 | 未对齐访问或布局假设 | 用 repr(C) 与对齐检查 |
| 跨 FFI 直接 abort | panic 越过 extern "C" | catch_unwind 或 panic = "abort" |
| 堆损坏 | 两侧分配器不同或重复释放 | 统一分配与释放责任 |
| 字符串乱码 | 缺少 NUL 结尾或编码不符 | 用 CString/CStr 并校验 |
| 多线程偶发错误 | static mut 或手写 Send | 用原子、锁或重新证明 |
| 调试构建 panic、发布构建错误 | 溢出或边界检查差异 | 显式使用 wrapping/checked |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
用 unsafe 绕过借用检查 | UB 且难以定位 | 改数据结构或缩小借用 |
无注释的 unsafe 块 | 后续维护者无法验证 | 写 // SAFETY: 与测试 |
用 transmute 做类型转换 | 布局或有效性错误 | From、TryFrom 或 cast |
static mut 共享状态 | 数据竞争 | Atomic*、Mutex、OnceLock |
| 把 Rust 结构体按值传给 C | 布局不一致 | repr(C) 或只传不透明指针 |
Box::into_raw 后忘记回收 | 泄漏 | RAII 包装或明确释放函数 |
4.3 可观测信号
Miri 检测未定义行为,慢但能定位到具体操作。ASan、TSan、MSan 与 UBSan 覆盖 FFI 与并发路径。cargo geiger 统计 unsafe 面积。loom 穷举并发交错。Fuzz 用随机输入触发边界条件。生产侧看崩溃转储、信号类型与版本相关性。
4.4 安全 / 性能 / 一致性边界
- 安全:编译器假设不变量成立;违反后任何优化结果都可能出现。
- 性能:unsafe 不自动变快;收益来自消除检查、拷贝或间接调用。
- 一致性:FFI 契约不受 Rust 编译器检查,版本与平台变化都可能破坏它。
- 可维护性:每个 unsafe 块都是长期债务;面积越小,审查越可靠。