unsafe 块 ​

核心概念 ​

unsafe { ... } 是 Rust 中执行 unsafe 操作的最基本语法结构。它是一个表达式,可以出现在任何表达式能出现的地方。unsafe 块的作用范围仅限于花括号内部——它不会影响块外的代码。在 unsafe 块中,你可以执行五种特殊操作(解引用裸指针、调用 unsafe 函数、访问可变静态变量、实现 unsafe trait、访问 union 字段),但借用检查器、类型系统等安全检查仍然有效。编写 unsafe 块时的核心原则是:范围越小越好,并且必须用 SAFETY 注释说明为什么这段代码是安全的。

rust
fn main() {
    let value = 42;
    let ptr = &value as *const i32;

    // unsafe 块:允许解引用裸指针
    // SAFETY: ptr 来自对 value 的引用,value 在当前作用域有效,
    // 所以 ptr 非空、对齐、指向有效的 i32。
    let result = unsafe { *ptr };
    println!("值: {}", result);

    // unsafe 块是一个表达式,有返回值
    let doubled = unsafe { *ptr * 2 };
    println!("翻倍: {}", doubled);
}

unsafe 块的作用域 ​

rust
fn main() {
    let mut data = [10, 20, 30, 40, 50];
    let ptr = data.as_mut_ptr();

    // unsafe 块只影响花括号内部
    // 块外的代码不受 unsafe 影响

    // SAFETY: ptr 来自 data.as_mut_ptr(),data 包含 5 个元素,
    // 索引 0 和 2 在有效范围内。
    unsafe {
        *ptr = 100;             // 修改第一个元素
        *ptr.add(2) = 300;     // 修改第三个元素
    }
    // 这里已经不在 unsafe 块中了
    println!("修改后: {:?}", data);

    // unsafe 块可以嵌套在各种语句中
    let sum: i32 = (0..data.len())
        .map(|i| {
            // SAFETY: i 在 0..data.len() 范围内,ptr 指向 data 的有效内存。
            unsafe { *ptr.add(i) }
        })
        .sum();
    println!("总和: {}", sum);

    // unsafe 块可以在 if、match 等控制流中
    let index = 3;
    if index < data.len() {
        // SAFETY: 已检查 index < data.len(),ptr.add(index) 不越界。
        let val = unsafe { *ptr.add(index) };
        println!("data[{}] = {}", index, val);
    }
}

unsafe 块作为表达式 ​

rust
fn main() {
    let numbers = [1, 2, 3, 4, 5];
    let ptr = numbers.as_ptr();

    // unsafe 块可以返回值
    // SAFETY: ptr 非空,指向 numbers 数组的第一个元素。
    let first = unsafe { *ptr };
    println!("第一个: {}", first);

    // 在 let 绑定中
    // SAFETY: ptr.add(4) 指向数组最后一个元素,在有效范围内。
    let last = unsafe { *ptr.add(4) };
    println!("最后一个: {}", last);

    // 在函数调用中
    // SAFETY: ptr.add(2) 在数组范围内。
    println!("中间的: {}", unsafe { *ptr.add(2) });

    // 在 match 中
    // SAFETY: ptr 指向有效数组元素。
    match unsafe { *ptr } {
        1 => println!("是 1"),
        _ => println!("不是 1"),
    }

    // 在闭包中
    let get_element = |i: usize| -> i32 {
        assert!(i < numbers.len());
        // SAFETY: 已通过 assert 检查 i 在有效范围内。
        unsafe { *ptr.add(i) }
    };
    println!("通过闭包: {}", get_element(3));
}

最小化 unsafe 块的范围 ​

rust
fn main() {
    let data = vec![10, 20, 30, 40, 50];
    let ptr = data.as_ptr();
    let len = data.len();

    // === 不推荐:unsafe 块太大 ===
    // unsafe {
    //     let mut total = 0;
    //     for i in 0..len {
    //         let val = *ptr.add(i);   // 只有这行需要 unsafe
    //         total += val;            // 安全操作
    //         if val > 25 {            // 安全操作
    //             println!("大于25: {}", val);  // 安全操作
    //         }
    //     }
    //     println!("总计: {}", total);  // 安全操作
    // }

    // === 推荐:只把需要 unsafe 的操作放在 unsafe 块中 ===
    let mut total = 0;
    for i in 0..len {
        // SAFETY: i 在 0..len 范围内,ptr 来自 data.as_ptr(),
        // data 有 len 个元素,所以 ptr.add(i) 有效。
        let val = unsafe { *ptr.add(i) };

        // 剩下的都是安全操作,不需要在 unsafe 块中
        total += val;
        if val > 25 {
            println!("大于25: {}", val);
        }
    }
    println!("总计: {}", total);
}

unsafe 块中调用 unsafe 函数 ​

rust
use std::slice;

unsafe fn dangerous_sum(ptr: *const i32, len: usize) -> i32 {
    let mut sum = 0;
    for i in 0..len {
        sum += *ptr.add(i);
    }
    sum
}

fn main() {
    let data = [1, 2, 3, 4, 5];

    // 调用 unsafe 函数必须在 unsafe 块中
    // SAFETY: data.as_ptr() 非空、对齐,data.len() 等于数组实际长度。
    let sum = unsafe { dangerous_sum(data.as_ptr(), data.len()) };
    println!("求和: {}", sum);

    // 从裸指针创建切片
    let ptr = data.as_ptr();
    // SAFETY: ptr 来自有效数组,5 不超过数组长度。
    let slice = unsafe { slice::from_raw_parts(ptr, 5) };
    println!("切片: {:?}", slice);

    // 多个 unsafe 操作可以放在同一个 unsafe 块中
    // 前提是它们的安全性前提相同
    // SAFETY: ptr 和 len 都来自同一个有效数组 data,
    // ptr 非空、对齐,len 不超过数组实际大小。
    unsafe {
        let first = *ptr;
        let last = *ptr.add(4);
        let total = dangerous_sum(ptr, 5);
        println!("首={}, 尾={}, 总={}", first, last, total);
    }
}

基本示例 ​

用 unsafe 块实现一个安全的字节缓冲区读写:

rust
use std::slice;

struct ByteBuffer {
    data: Vec<u8>,
}

impl ByteBuffer {
    fn new(size: usize) -> Self {
        ByteBuffer {
            data: vec![0; size],
        }
    }

    // 写入数据到指定偏移(安全接口)
    fn write(&mut self, offset: usize, bytes: &[u8]) -> Result<(), String> {
        if offset + bytes.len() > self.data.len() {
            return Err(format!(
                "写入越界: offset={}, len={}, capacity={}",
                offset, bytes.len(), self.data.len()
            ));
        }

        // 内部使用 unsafe 进行高效复制
        let dst = self.data.as_mut_ptr();

        // SAFETY:
        // - dst 来自 self.data.as_mut_ptr(),非空且对齐
        // - offset + bytes.len() <= self.data.len()(已检查)
        // - 源和目标不重叠(bytes 是外部数据)
        unsafe {
            std::ptr::copy_nonoverlapping(
                bytes.as_ptr(),
                dst.add(offset),
                bytes.len(),
            );
        }

        Ok(())
    }

    // 读取指定范围的数据(安全接口)
    fn read(&self, offset: usize, len: usize) -> Result<&[u8], String> {
        if offset + len > self.data.len() {
            return Err(format!(
                "读取越界: offset={}, len={}, capacity={}",
                offset, len, self.data.len()
            ));
        }

        let ptr = self.data.as_ptr();

        // SAFETY:
        // - ptr 来自 self.data.as_ptr(),非空且对齐
        // - offset + len <= self.data.len()(已检查)
        // - 返回的切片生命周期与 &self 绑定
        Ok(unsafe { slice::from_raw_parts(ptr.add(offset), len) })
    }

    // 在指定偏移写入一个 i32(小端序)
    fn write_i32(&mut self, offset: usize, value: i32) -> Result<(), String> {
        let bytes = value.to_le_bytes();
        self.write(offset, &bytes)
    }

    // 从指定偏移读取一个 i32(小端序)
    fn read_i32(&self, offset: usize) -> Result<i32, String> {
        let bytes = self.read(offset, 4)?;
        // 从切片构造 i32
        let mut arr = [0u8; 4];
        arr.copy_from_slice(bytes);
        Ok(i32::from_le_bytes(arr))
    }

    fn len(&self) -> usize {
        self.data.len()
    }
}

fn main() {
    let mut buf = ByteBuffer::new(64);

    // 写入字节数据
    buf.write(0, b"Hello").unwrap();
    buf.write(10, b"World").unwrap();

    // 读取字节数据
    let hello = buf.read(0, 5).unwrap();
    let world = buf.read(10, 5).unwrap();
    println!("读取: {} {}", 
        String::from_utf8_lossy(hello),
        String::from_utf8_lossy(world));

    // 写入和读取整数
    buf.write_i32(20, 12345).unwrap();
    buf.write_i32(24, -9999).unwrap();

    let v1 = buf.read_i32(20).unwrap();
    let v2 = buf.read_i32(24).unwrap();
    println!("整数: {}, {}", v1, v2);

    // 边界检查
    match buf.write(60, b"too long data") {
        Ok(_) => println!("写入成功"),
        Err(e) => println!("预期错误: {}", e),
    }

    match buf.read(100, 10) {
        Ok(_) => println!("读取成功"),
        Err(e) => println!("预期错误: {}", e),
    }

    println!("缓冲区大小: {} 字节", buf.len());
}

常见问题 ​

问题一:unsafe 块会影响块外的代码吗?

不会。unsafe 块的作用域仅限于花括号内部。块外的代码仍然受到编译器的完整安全检查。但 unsafe 块内部的错误操作可能导致块外代码观察到未定义行为。

问题二:unsafe 块中的安全代码还安全吗?

安全代码在任何地方都是安全的——在 unsafe 块中写安全代码不会有额外风险。问题在于如果 unsafe 操作破坏了不变量(如创建了无效引用),后续的安全代码可能会触发未定义行为。

问题三:多个 unsafe 操作应该放在一个块里还是分开?

如果多个操作共享相同的安全性前提,可以放在一个 unsafe 块中并写一个统一的 SAFETY 注释。如果安全性前提不同,分开写更清晰。

问题四:unsafe 块需要写 SAFETY 注释吗?

强烈建议写。Clippy 有 clippy::undocumented_unsafe_blocks lint 可以强制要求。SAFETY 注释解释了为什么这段 unsafe 代码是正确的,帮助代码审查和未来维护。

适用场景 ​

  • 裸指针操作:需要解引用 *const T / *mut T
  • FFI 调用:调用外部 C 函数
  • 性能优化:跳过运行时检查(如边界检查)
  • 底层操作:内存复制、位操作等

注意事项 ​

  • unsafe 块的范围应尽可能小
  • 每个 unsafe 块都应有 SAFETY 注释
  • unsafe 块不会关闭借用检查器和类型系统
  • unsafe 块内的错误可能导致块外代码出现未定义行为
  • 优先将 unsafe 操作封装在安全的函数接口后面
  • unsafe 块是表达式,可以返回值

总结 ​

unsafe { ... } 块是在安全代码中执行 unsafe 操作的语法结构。它是一个表达式,作用域仅限于花括号内部,不影响块外代码。在 unsafe 块中可以解引用裸指针、调用 unsafe 函数等五种操作,但借用检查器、类型系统等安全检查仍然有效。编写 unsafe 块时应遵循最小化原则——只把真正需要 unsafe 的操作放在块中,其余安全操作放在块外。每个 unsafe 块都应附带 SAFETY 注释,解释为什么代码是正确的。实际项目中,unsafe 块通常被封装在安全的公共 API 后面,使用者不需要直接接触 unsafe。