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