unsafe 关键字 ​

核心概念 ​

unsafe 是 Rust 中用于标记"编译器无法静态验证其安全性"的代码区域的关键字。Rust 的安全保证建立在编译器的静态分析之上,但有些操作(如解引用裸指针、调用 C 函数)超出了编译器的验证能力。unsafe 并不意味着代码一定有问题,而是告诉编译器"这段代码的安全性由程序员自己负责"。使用 unsafe 时,编译器仍然会检查借用规则、类型系统等,只是放开了五种特定操作的限制。

unsafe 可以出现在四个位置:unsafe 块、unsafe 函数、unsafe trait、unsafe impl。

rust
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 能做的五件事 ​

rust
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 traitunsafe impl Trait for Type必须满足 trait 的安全契约
访问 union 字段读取 union 的非活跃字段类型不匹配导致未定义行为

unsafe 不能做的事 ​

rust
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 注释规范 ​

rust
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 范围 ​

rust
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 在不同场景中的正确使用:

rust
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,而是表示安全性由程序员负责保证。