Rust 2026 经验谈 - 常见 bug 模式与防御性编程

1
// 不好：panic 消息是 "called `Option::unwrap()` on a `None` value"
2
let port = config.get("port").unwrap();
3

4
// 好：panic 消息告诉你"为什么"这里不该失败
5
let port = config.get("port")
6
    .expect("config must contain 'port' — check config.toml");
7

8
// 更好：返回 Result，让调用者决定
9
let port = config.get("port")
10
    .ok_or(ConfigError::MissingField("port"))?;

1
// unwrap：失败时 panic
2
let user = users.find_by_id(id).unwrap();
3

4
// ok_or：失败时返回错误
5
let user = users.find_by_id(id)
6
    .ok_or(AppError::UserNotFound(id))?;
7

8
// 注意：ok_or 会急切求值错误表达式
9
// 如果创建错误对象有开销，用 ok_or_else
10
let user = users.find_by_id(id)
11
    .ok_or_else(|| AppError::UserNotFound(id))?;

1
// 有合理默认值的场景
2
let timeout = config.get("timeout")
3
    .and_then(|v| v.parse().ok())
4
    .unwrap_or(30);  // 默认 30 秒
5

6
// 或用 unwrap_or_default（需要 Default trait）
7
let flags: Vec<String> = config.get_list("flags")
8
    .unwrap_or_default();  // 空Vec

1
let x: u8 = 255;
2
let y = x + 1;  // debug: panic!  |  release: 静默溢出为 0

1
// 计算缓冲区大小
2
let buf_size = header_len + body_len;  // 如果 header_len + body_len > usize::MAX 呢？
3
let buf = vec![0u8; buf_size];  // 分配了一个"很小"的缓冲区（回绕后）
4

5
// 然后 body 数据写入时越界——但不是 Rust 的边界检查先捕获，
6
// 而是 buf_size 已经错了，写入的语义就不对了

1
let x: u8 = 250;
2
let y = x.saturating_add(10);  // 255，而非回绕到 4
3

4
// 常用场景：计数器、进度条
5
progress.saturating_add(step);
6
remaining.saturating_sub(consumed);

1
// 哈希计算、CRC、加密——这些场景回绕是正确的语义
2
let hash = hash.wrapping_mul(31).wrapping_add(byte as u64);

1
let buf_size = header_len.checked_add(body_len)
2
    .ok_or(Error::BufferTooLarge)?;
3

4
// 或者用 ? 传播
5
let total = a.checked_add(b)?;  // 溢出时返回 None

1
let (result, did_overflow) = x.overflowing_add(y);
2
if did_overflow {
3
    log::warn!("integer overflow detected: {} + {}", x, y);
4
}

1
[profile.release]
2
overflow-checks = true  # release 也检查溢出（约 5-10% 性能开销）

1
let v = vec![1, 2, 3];
2

3
// panic 风格：越界时 panic
4
let x = v[10];  // thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 10'
5

6
// Option 风格：越界时返回 None
7
let x = v.get(10);  // None

1
use std::sync::Mutex;
2

3
let a = Mutex::new(0);
4
let b = Mutex::new(0);
5

6
// 线程 1
7
let mut ga = a.lock().unwrap();
8
let mut gb = b.lock().unwrap();  // 如果线程 2 先拿了 b，这里就死锁
9

10
// 线程 2（在另一个线程中）
11
let mut gb = b.lock().unwrap();
12
let mut ga = a.lock().unwrap();  // 等待线程 1 释放 a → 死锁

1
use parking_lot::ReentrantMutex;
2

3
let m = ReentrantMutex::new(0);
4

5
let guard1 = m.lock();
6
// 同一线程可以再次加锁——但这是否是你想要的？
7
let guard2 = m.lock();  // 不会死锁，但可能导致逻辑错误

1
use tokio::sync::Mutex;
2

3
// async Mutex 的死锁更难调试，因为"持有锁"的时间可能跨越 .await 点
4
let mut guard = cache.lock().await;
5
let data = fetch_from_db(&key).await;  // 持有 cache 锁的同时等待网络！
6
guard.insert(key, data);               // 其他任务无法访问 cache

1
let data = {
2
    let guard = cache.lock().await;
3
    guard.get(&key).cloned()  // 克隆数据
4
}; // 锁已释放
5

6
let data = match data {
7
    Some(d) => d,
8
    None => fetch_from_db(&key).await,  // 不持有锁
9
};
10

11
cache.lock().await.insert(key, data);  // 短暂加锁

1
# .clippy.toml 或 Cargo.toml [lints.clippy]
2
# 推荐的防御性 lint 集合

1
#![warn(
2
    clippy::unwrap_used,           // 禁止 unwrap，强制 expect 或 ?
3
    clippy::expect_used,           // 可选：也禁止 expect（更严格）
4
    clippy::indexing_slicing,      // 禁止 v[i]，强制 v.get(i)
5
    clippy::arithmetic_side_effects,  // 禁止裸算术，强制 checked/saturating
6
    clippy::panic,                 // 禁止显式 panic!
7
    clippy::todo,                  // 禁止 todo!（确保没有未完成代码）
8
    clippy::unimplemented,         // 禁止 unimplemented!
9
    clippy::unreachable,           // 禁止 unreachable!（用 unreachable_unchecked 显式标注）
10
)]
11

12
#![allow(
13
    clippy::expect_used,           // 在测试中允许 expect
14
)]

1
# GitHub Actions
2
- name: Clippy
3
  run: cargo clippy --all-targets --all-features -- -D warnings