Rust 2026 经验谈 - Unsafe 代码审查清单

1
/// 自定义的线程安全引用计数指针。
2
///
3
/// # Safety
4
///
5
/// 实现 `Send` 是安全的，因为：
6
/// - 内部计数使用 `AtomicUsize`，线程安全
7
/// - 数据通过 `UnsafeCell` 访问，但所有访问都通过原子计数守卫
8
/// - 不存在 `&mut` 引用的线程间传递
9
unsafe impl<T: Sync> Send for MyRc<T> {}
10

11
/// # Safety
12
///
13
/// 实现 `Sync` 是安全的，因为：
14
/// - `MyRc` 本身是只读的（引用计数是原子的）
15
/// - 内部数据 `T: Sync` 保证并发共享引用安全
16
unsafe impl<T: Sync> Sync for MyRc<T> {}

1
fn read_config(path: &Path) -> Result<Config> {
2
    let file = std::fs::File::open(path)?;
3
    let mut reader = std::io::BufReader::new(file);
4

5
    let version = unsafe {
6
        // SAFETY:
7
        // - buf 是 4 字节的栈上数组，对齐为 1
8
        // - reader.read_exact 确保写入 4 字节
9
        // - u32 的小端字节解释总是有效的
10
        let mut buf = [0u8; 4];
11
        reader.read_exact(&mut buf)?;
12
        u32::from_le_bytes(buf)
13
    };
14

15
    Ok(Config { version })
16
}

1
unsafe fn bad_assumption(ptr: *const u8, len: usize) -> &[u8] {
2
    // SAFETY: ptr 是有效的，len 也是对的
3
    // ↑ 这个注释没有任何证明力！
4
    std::slice::from_raw_parts(ptr, len)
5
}
6

7
// 好的 Safety 注释应该引用具体的保证来源：
8
unsafe fn good_assumption(ptr: *const u8, len: usize, capacity: usize) -> &[u8] {
9
    // SAFETY:
10
    // 调用者（process_buffer）保证：
11
    // - ptr 来自 Vec::as_ptr，对齐为 1，非空
12
    // - len <= capacity（在 process_buffer 中已检查）
13
    // - 数据在 'a 期间有效（Vec 的生命周期约束）
14
    std::slice::from_raw_parts(ptr, len)
15
}

1
#[cfg(test)]
2
mod tests {
3
    use loom::sync::atomic::{AtomicUsize, Ordering};
4
    use loom::thread;
5

6
    #[test]
7
    fn test_atomic_counter() {
8
        loom::model(|| {
9
            let counter = AtomicUsize::new(0);
10

11
            let t1 = thread::spawn(|| {
12
                counter.fetch_add(1, Ordering::SeqCst);
13
            });
14

15
            let t2 = thread::spawn(|| {
16
                counter.fetch_add(1, Ordering::SeqCst);
17
            });
18

19
            t1.join().unwrap();
20
            t2.join().unwrap();
21

22
            let val = counter.load(Ordering::SeqCst);
23
            assert!(val == 1 || val == 2);
24
            // fetch_add 不会丢失，最终值一定是 2
25
            // 但上面的断言允许中间状态
26
        });
27
    }
28
}

1
#[cfg(test)]
2
mod tests {
3
    use loom::sync::Arc;
4
    use loom::thread;
5

6
    struct SimpleLock {
7
        locked: loom::sync::atomic::AtomicBool,
8
        data: loom::sync::atomic::AtomicUsize,
9
    }
10

11
    impl SimpleLock {
12
        fn new() -> Self {
13
            Self {
14
                locked: loom::sync::atomic::AtomicBool::new(false),
15
                data: loom::sync::atomic::AtomicUsize::new(0),
16
            }
17
        }
18

19
        fn lock(&self) {
20
            while self.locked.compare_exchange(
21
                false, true,
22
                loom::sync::atomic::Ordering::Acquire,
23
                loom::sync::atomic::Ordering::Relaxed,
24
            ).is_err() {
25
                loom::thread::yield_now();
26
            }
27
        }
28

29
        fn unlock(&self) {
30
            self.locked.store(false, loom::sync::atomic::Ordering::Release);
31
        }
32
    }
33

34
    #[test]
35
    fn test_simple_lock_mutual_exclusion() {
36
        loom::model(|| {
37
            let lock = Arc::new(SimpleLock::new());
38
            let lock1 = lock.clone();
39
            let lock2 = lock.clone();
40

41
            let t1 = thread::spawn(move || {
42
                lock1.lock();
43
                let v = lock1.data.load(loom::sync::atomic::Ordering::Relaxed);
44
                lock1.data.store(v + 1, loom::sync::atomic::Ordering::Relaxed);
45
                lock1.unlock();
46
            });
47

48
            let t2 = thread::spawn(move || {
49
                lock2.lock();
50
                let v = lock2.data.load(loom::sync::atomic::Ordering::Relaxed);
51
                lock2.data.store(v + 1, loom::sync::atomic::Ordering::Relaxed);
52
                lock2.unlock();
53
            });
54

55
            t1.join().unwrap();
56
            t2.join().unwrap();
57

58
            let val = lock.data.load(loom::sync::atomic::Ordering::Relaxed);
59
            assert_eq!(val, 2);
60
        });
61
    }
62
}

1
// 使用条件编译切换 loom 和真实实现
2
#[cfg(test)]
3
mod concurrency_tests {
4
    #[cfg(not(loom))]
5
    use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
6
    #[cfg(loom)]
7
    use loom::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
8

9
    #[cfg(not(loom))]
10
    use std::sync::Arc;
11
    #[cfg(loom)]
12
    use loom::sync::Arc;
13

14
    #[cfg(not(loom))]
15
    use std::thread;
16
    #[cfg(loom)]
17
    use loom::thread;
18

19
    #[test]
20
    fn test_concurrent_access() {
21
        #[cfg(loom)]
22
        loom::model(|| {
23
            self::test_body();
24
        });
25

26
        #[cfg(not(loom))]
27
        self::test_body();
28
    }
29

30
    fn test_body() {
31
        // 测试逻辑，使用上面的条件编译类型
32
    }
33
}

1
unsafe fn process_ptr(ptr: *const u8, len: usize) {
2
    // Edition 2024: unsafe fn 函数体需显式 unsafe {}
3
    // ✓ 检查空指针
4
    if ptr.is_null() {
5
        return;
6
    }
7

8
    // ✓ 检查对齐（如果需要）
9
    assert_eq!((ptr as usize) % std::mem::align_of::<u8>(), 0);
10

11
    // ✓ 检查是否在有效分配范围内
12
    // （无法直接检查——需要从调用者保证）
13

14
    // ✓ 检查 len 是否合理
15
    if len > isize::MAX as usize {
16
        panic!("len too large");
17
    }
18

19
    unsafe {
20
        let slice = std::slice::from_raw_parts(ptr, len);
21
    }
22
}

1
// ❌ 未初始化读取
2
fn bad_uninit() -> i32 {
3
    let mut x: i32;
4
    // x 未初始化就被使用
5
    unsafe { std::ptr::read(&x) }  // UB
6
}
7

8
// ✓ 使用 MaybeUninit
9
fn good_uninit() -> i32 {
10
    let mut x = std::mem::MaybeUninit::<i32>::uninit();
11
    unsafe {
12
        x.as_mut_ptr().write(42);  // 先写入
13
        x.assume_init()            // 再读取
14
    }
15
}
16

17
// ✓ 逐字段初始化结构体
18
fn init_struct() -> MyStruct {
19
    let mut s = std::mem::MaybeUninit::<MyStruct>::uninit();
20
    unsafe {
21
        let ptr = s.as_mut_ptr();
22
        std::ptr::addr_of_mut!((*ptr).field1).write(1);
23
        std::ptr::addr_of_mut!((*ptr).field2).write(2);
24
        std::ptr::addr_of_mut!((*ptr).field3).write(3);
25
        s.assume_init()
26
    }
27
}

1
// ❌ 数据竞争
2
use std::sync::atomic::AtomicBool;
3
use std::cell::UnsafeCell;
4

5
struct BadOnce<T> {
6
    initialized: AtomicBool,
7
    value: UnsafeCell<T>,
8
}
9

10
impl<T> BadOnce<T> {
11
    fn get(&self) -> &T {
12
        if self.initialized.load(std::sync::atomic::Ordering::Relaxed) {
13
            unsafe { &*self.value.get() }
14
        } else {
15
            // 多个线程可能同时进入这里
16
            // 写入 value 的数据竞争！
17
            unsafe {
18
                std::ptr::write(self.value.get(), /* init */);
19
            }
20
            self.initialized.store(true, std::sync::atomic::Ordering::Relaxed);
21
            unsafe { &*self.value.get() }
22
        }
23
    }
24
}
25

26
// ✓ 使用正确的同步
27
struct GoodOnce<T> {
28
    initialized: AtomicBool,
29
    value: UnsafeCell<MaybeUninit<T>>,
30
}
31

32
impl<T> GoodOnce<T> {
33
    fn get(&self, init: impl FnOnce() -> T) -> &T {
34
        if self.initialized.load(std::sync::atomic::Ordering::Acquire) {
35
            unsafe { (*self.value.get()).assume_init_ref() }
36
        } else {
37
            let val = init();
38
            unsafe {
39
                std::ptr::write(self.value.get(), MaybeUninit::new(val));
40
            }
41
            self.initialized.store(true, std::sync::atomic::Ordering::Release);
42
            unsafe { (*self.value.get()).assume_init_ref() }
43
        }
44
    }
45
}
46
// 注意：上面的 GoodOnce 仍有一个问题——多线程同时初始化
47
// 生产代码应使用 std::sync::OnceLock

1
// ✓ FFI 边界的标准处理
2
#[unsafe(no_mangle)]
3
pub extern "C" fn my_lib_process(data: *const u8, len: usize) -> i32 {
4
    // 1. 验证输入
5
    if data.is_null() && len > 0 {
6
        return -1;
7
    }
8

9
    // 2. catch_unwind 防止 panic 跨边界
10
    let result = std::panic::catch_unwind(|| {
11
        let slice = if data.is_null() || len == 0 {
12
            &[]
13
        } else {
14
            unsafe { std::slice::from_raw_parts(data, len) }
15
        };
16
        internal_process(slice)
17
    });
18

19
    match result {
20
        Ok(Ok(())) => 0,
21
        Ok(Err(e)) => e as i32,
22
        Err(_) => -999,
23
    }
24
}

1
1. 定位所有 unsafe 块和 unsafe fn
2
   └─ cargo geiger（自己的 crate）
3
   └─ grep -r "unsafe" src/
4

5
2. 对每个 unsafe 实例，检查：
6
   ├─ 是否有 # Safety 文档？
7
   ├─ Safety 的前置条件是否可验证？
8
   ├─ 调用处是否有 SAFETY 注释？
9
   ├─ 是否可通过 safe API 消除？
10
   └─ 是否有 Miri 测试覆盖？
11

12
3. 运行 Miri
13
   └─ cargo +nightly miri test
14

15
4. 运行 loom（如果有并发 unsafe）
16
   └─ RUSTFLAGS="--cfg loom" cargo test
17

18
5. 审查依赖的 unsafe
19
   └─ cargo geiger --dependencies-only
20
   └─ 审查关键依赖的 unsafe 代码

1
// 优先级 1：可以用 safe API 替代
2
// unsafe { std::ptr::copy(src, dst, len); }
3
// → src[..len].copy_to_slice(&mut dst[..len]);
4

5
// 优先级 2：缩小 unsafe 块范围
6
// unsafe {
7
//     let a = *ptr1;
8
//     let b = *ptr2;
9
//     let c = a + b;  // 加法不需要 unsafe！
10
// }
11
// →
12
// let (a, b) = unsafe { (*ptr1, *ptr2) };
13
// let c = a + b;
14

15
// 优先级 3：用封装层隔离
16
pub fn safe_wrapper(data: &[u8]) -> Result<u32> {
17
    if data.len() < 4 {
18
        return Err(Error::TooShort);
19
    }
20
    Ok(unsafe { read_u32_le(data.as_ptr()) })
21
}
22

23
unsafe fn read_u32_le(ptr: *const u8) -> u32 {
24
    // Safety: 调用者保证 ptr 有效且至少 4 字节
25
    // Edition 2024: unsafe fn 函数体需显式 unsafe {}
26
    unsafe {
27
        u32::from_le_bytes([
28
            *ptr,
29
            *ptr.add(1),
30
            *ptr.add(2),
31
            *ptr.add(3),
32
        ])
33
    }
34
}