unsafe 关键字
核心概念
unsafe 是 Rust 中用于标记"编译器无法静态验证其安全性"的代码区域的关键字。Rust 的安全保证建立在编译器的静态分析之上,但有些操作(如解引用裸指针、调用 C 函数)超出了编译器的验证能力。unsafe 并不意味着代码一定有问题,而是告诉编译器"这段代码的安全性由程序员自己负责"。使用 unsafe 时,编译器仍然会检查借用规则、类型系统等,只是放开了五种特定操作的限制。
unsafe 可以出现在四个位置:unsafe 块、unsafe 函数、unsafe trait、unsafe impl。
fn main() {
// unsafe 块:在安全函数中执行 unsafe 操作
let x = 42;
let ptr = &x as *const i32; // 创建裸指针是安全的
// 解引用裸指针需要 unsafe 块
unsafe {
println!("通过裸指针读取: {}", *ptr);
}
// unsafe 不会关闭借用检查器
// 以下代码即使在 unsafe 块中也不能编译:
// unsafe {
// let mut s = String::from("hello");
// let r1 = &s;
// let r2 = &mut s; // 编译错误:不能同时有不可变和可变引用
// println!("{}, {}", r1, r2);
// }
}unsafe 能做的五件事
use std::ffi::c_int;
// 声明外部函数(FFI)
extern "C" {
fn abs(input: c_int) -> c_int;
}
// unsafe trait
unsafe trait UnsafeTrait {
fn danger(&self);
}
struct MyType;
// unsafe impl
unsafe impl UnsafeTrait for MyType {
fn danger(&self) {
println!("实现了 unsafe trait");
}
}
// 可变静态变量
static mut COUNTER: u32 = 0;
// union
union IntOrFloat {
i: i32,
f: f32,
}
fn main() {
// === 1. 解引用裸指针 ===
let mut value = 10;
let ptr = &mut value as *mut i32;
unsafe {
*ptr = 20;
println!("1. 解引用裸指针: {}", *ptr);
}
// === 2. 调用 unsafe 函数或方法 ===
unsafe fn dangerous() {
println!("2. 这是一个 unsafe 函数");
}
unsafe {
dangerous();
}
// === 3. 访问或修改可变静态变量 ===
unsafe {
COUNTER += 1;
println!("3. 可变静态变量: {}", COUNTER);
}
// === 4. 实现 unsafe trait ===
let obj = MyType;
obj.danger();
println!("4. unsafe trait 已实现");
// === 5. 访问 union 的字段 ===
let u = IntOrFloat { i: 42 };
unsafe {
println!("5. union 字段: i={}", u.i);
}
// === 调用外部函数(FFI)===
unsafe {
println!("abs(-10) = {}", abs(-10));
}
}| unsafe 操作 | 说明 | 风险 |
|---|---|---|
| 解引用裸指针 | *const T / *mut T 的解引用 | 空指针、悬垂指针、未对齐 |
| 调用 unsafe 函数 | 函数声明为 unsafe fn | 调用者必须满足前置条件 |
| 访问可变静态变量 | static mut 的读写 | 数据竞争 |
| 实现 unsafe trait | unsafe impl Trait for Type | 必须满足 trait 的安全契约 |
| 访问 union 字段 | 读取 union 的非活跃字段 | 类型不匹配导致未定义行为 |
unsafe 不能做的事
fn main() {
// unsafe 不会关闭以下检查:
// 1. 借用检查器仍然工作
// let mut s = String::from("hello");
// unsafe {
// let r1 = &s;
// let r2 = &mut s; // 编译错误
// println!("{}, {}", r1, r2);
// }
// 2. 类型系统仍然工作
// unsafe {
// let x: i32 = "hello"; // 编译错误
// }
// 3. 生命周期检查仍然工作
// let r;
// unsafe {
// let x = 5;
// r = &x; // 编译错误
// }
// println!("{}", r);
// 4. 所有权规则仍然工作
// unsafe {
// let s = String::from("hello");
// let s2 = s;
// println!("{}", s); // 编译错误:use after move
// }
println!("unsafe 只放开五种特定操作的限制");
println!("其他安全检查(借用、类型、生命周期、所有权)不受影响");
}SAFETY 注释规范
fn main() {
let data = vec![1, 2, 3, 4, 5];
let ptr = data.as_ptr();
// 好的做法:每个 unsafe 块都写 SAFETY 注释
// 说明为什么这段 unsafe 代码是正确的
// SAFETY: ptr 来自 data.as_ptr(),data 在当前作用域有效,
// 所以 ptr 非空、对齐、指向有效内存。
// 我们只读取 data 的范围内的元素(索引 0-4)。
unsafe {
for i in 0..data.len() {
println!("data[{}] = {}", i, *ptr.add(i));
}
}
// 不好的做法:没有 SAFETY 注释
// unsafe {
// println!("{}", *ptr);
// }
// Clippy 的 #[deny(clippy::undocumented_unsafe_blocks)]
// 可以强制要求 SAFETY 注释
}最小化 unsafe 范围
fn main() {
let data = vec![10, 20, 30];
let ptr = data.as_ptr();
let len = data.len();
// 不好:unsafe 块太大,包含了安全操作
// unsafe {
// let mut sum = 0;
// for i in 0..len {
// let val = *ptr.add(i); // 这一行是 unsafe 的
// sum += val; // 这一行是安全的
// println!("item: {}", val); // 这一行也是安全的
// }
// println!("sum: {}", sum); // 这一行也是安全的
// }
// 好:unsafe 块只包含真正需要 unsafe 的操作
let mut sum = 0;
for i in 0..len {
// SAFETY: ptr 来自 data.as_ptr(),i 在 0..len 范围内,
// 所以 ptr.add(i) 指向 data 中有效的元素。
let val = unsafe { *ptr.add(i) };
sum += val;
println!("item: {}", val);
}
println!("sum: {}", sum);
}基本示例
展示 unsafe 在不同场景中的正确使用:
use std::slice;
// 用 unsafe 实现安全的公共 API
// 标准库中很多函数内部用了 unsafe,但对外暴露安全接口
fn split_at_mut(slice: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) {
let len = slice.len();
assert!(mid <= len, "mid 超出范围");
let ptr = slice.as_mut_ptr();
// SAFETY:
// - ptr 来自有效的切片,非空且对齐
// - mid <= len,所以 ptr.add(mid) 不会越界
// - 两个切片不重叠:[0..mid) 和 [mid..len)
// - 原始切片的生命周期覆盖返回的两个切片
unsafe {
(
slice::from_raw_parts_mut(ptr, mid),
slice::from_raw_parts_mut(ptr.add(mid), len - mid),
)
}
}
// unsafe 函数:调用者必须满足前置条件
/// 从裸指针读取指定数量的元素
///
/// # Safety
///
/// - `ptr` 必须非空且正确对齐
/// - `ptr` 指向的内存必须包含至少 `count` 个连续的 `T` 值
/// - 这些内存在返回的 Vec 生命周期内不能被修改
unsafe fn read_from_ptr<T: Copy>(ptr: *const T, count: usize) -> Vec<T> {
let mut result = Vec::with_capacity(count);
for i in 0..count {
// SAFETY: 由调用者保证 ptr.add(i) 指向有效的 T 值
result.push(*ptr.add(i));
}
result
}
fn main() {
// 使用安全包装的 split_at_mut
let mut data = vec![1, 2, 3, 4, 5, 6];
let (left, right) = split_at_mut(&mut data, 3);
println!("左半: {:?}", left); // [1, 2, 3]
println!("右半: {:?}", right); // [4, 5, 6]
// 修改不会互相影响
left[0] = 100;
right[0] = 400;
println!("修改后左半: {:?}", left);
println!("修改后右半: {:?}", right);
// 使用 unsafe 函数
let numbers = [10, 20, 30, 40, 50];
let ptr = numbers.as_ptr();
// SAFETY: ptr 来自 numbers 数组,非空、对齐,
// 且 numbers 包含 5 个 i32 元素,我们只读取 3 个。
let first_three = unsafe { read_from_ptr(ptr, 3) };
println!("\n前三个: {:?}", first_three);
// 安全抽象的例子:Vec::from_raw_parts
let mut v = Vec::with_capacity(10);
v.extend_from_slice(&[1, 2, 3]);
let ptr = v.as_mut_ptr();
let len = v.len();
let cap = v.capacity();
// 防止 v 的析构函数释放内存
std::mem::forget(v);
// SAFETY: ptr, len, cap 来自刚才的 Vec,
// 满足 Vec::from_raw_parts 的所有要求。
let rebuilt = unsafe { Vec::from_raw_parts(ptr, len, cap) };
println!("重建的 Vec: {:?}", rebuilt);
}常见问题
问题一:unsafe 代码就一定有 bug 吗?
不是。unsafe 只是表示编译器无法自动验证这段代码的安全性,需要程序员自己保证。标准库中大量使用了 unsafe(如 Vec、HashMap 的实现),这些代码经过了严格审查和测试。
问题二:什么时候应该用 unsafe?
只在以下情况使用:需要调用 C 库(FFI)、需要实现底层数据结构(如自定义分配器)、需要极致的性能优化且安全版本无法满足、标准库没有提供安全的 API 来完成你需要的操作。
问题三:unsafe 块中的所有代码都是 unsafe 的吗?
不是。unsafe 块中可以包含安全代码和 unsafe 操作。但应该尽量缩小 unsafe 块的范围,只包含真正需要 unsafe 的操作,这样更容易审查。
问题四:unsafe 和 C/C++ 有什么区别?
C/C++ 中所有代码都是"unsafe"的——编译器不检查内存安全。Rust 中 unsafe 是明确标记的、有边界的。unsafe 代码通常被封装在安全的 API 后面,使用者不需要关心内部的 unsafe 操作。
适用场景
- FFI:调用 C/C++ 库的函数
- 底层数据结构:实现链表、树等需要裸指针的结构
- 性能关键路径:跳过边界检查等安全开销
- 硬件交互:操作内存映射 IO、设备寄存器
注意事项
- unsafe 只放开五种操作的限制,不关闭借用检查器
- 每个 unsafe 块都应写 SAFETY 注释说明安全性
- 尽量缩小 unsafe 块的范围
- 优先使用标准库提供的安全 API
- unsafe 代码应该被封装在安全的公共接口后面
- 用
#[deny(clippy::undocumented_unsafe_blocks)]强制要求注释
总结
unsafe 关键字标记编译器无法静态验证安全性的代码区域。它允许五种操作:解引用裸指针、调用 unsafe 函数、访问可变静态变量、实现 unsafe trait、访问 union 字段。unsafe 不会关闭借用检查器、类型系统或生命周期检查——这些仍然在 unsafe 块中工作。使用 unsafe 时应遵循最小化原则:缩小 unsafe 块范围、写 SAFETY 注释、将 unsafe 封装在安全的公共 API 后面。unsafe 不意味着代码有 bug,而是表示安全性由程序员负责保证。