Wade-DevCode Rust 安全实践
何时用
- 写新的 Rust 函数、结构体或模块时。
- 设计数据结构，思考所有权与生命周期时。
- 处理错误传播、编写库 crate 时。
- 准备写
unsafe块或评估是否真的需要unsafe时。 - 发现编译器报 borrow checker 错误，想靠
clone/Rc强行绕过时。
核心规则
1. 顺着所有权/借用设计，不靠 clone/Rc 硬绕；理解生命周期
规则： 遇到借用检查报错时，先理解所有权模型要表达的约束，调整数据流或函数签名；只有在语义上确实需要共享所有权时才用 Rc/Arc，不把它们当"绕过编译器的万金油"；clone 有性能代价，大结构体不随意 clone。
为什么： AI 面对 borrow checker 报错时最常见的反应是加 .clone() 或把类型换成 Rc<RefCell<T>>——这能让代码编译，但往往意味着绕开了编译器在帮你捕获的真实问题：可能是数据所有权设计不合理，可能是生命周期标注缺失。用 RefCell 把静态借用检查变成运行时 panic，在 Rust 里是倒退，不是进步。
怎么做：
- 报 borrow 错误 → 先读错误信息，理解哪个变量的生命周期冲突，考虑重组代码顺序或拆分函数。
- 函数返回引用 → 正确标注生命周期参数，让编译器而非运行时来保证安全。
- 确实需要多所有者 →
Arc<T>（多线程）或Rc<T>（单线程），但要在注释里说明为何需要共享所有权。
2. 错误用 Result + ?，库代码不 unwrap/panic；用 thiserror/anyhow 分场景
规则： 可能失败的操作返回 Result<T, E>，通过 ? 传播；库 crate 的公开 API 中不使用 unwrap()/expect()/panic!()（调用方无法捕获 panic）；应用程序层用 anyhow 简化错误汇聚，库层用 thiserror 定义具体错误类型。
为什么： AI 写 Rust 时的典型懒惰：let val = map.get("key").unwrap()，在 happy path 下工作，一旦 key 不存在就 unwind panic，且调用方无法在类型层面知道这里会 panic。库的职责是把所有可能的失败都表达在类型里，让调用方决定怎么处理，而不是替调用方决定"遇到这种情况就崩溃"。
怎么做：
- 库 crate：
#[derive(thiserror::Error)]定义枚举错误类型，每个变体对应一种具体失败场景。 - 应用 crate / 原型：
anyhow::Result<T>+?快速传播，context()/with_context()添加现场信息。 - 确实不可能失败的
unwrap→ 改写成expect("此处 key 在初始化时已保证存在")并写明原因，或用unreachable!配合注释。
3. unsafe 最小化并注释不变量；能安全抽象就封装
规则： unsafe 块应尽可能小，仅包含无法用安全 API 表达的操作；每个 unsafe 块旁必须有注释，说明为何此处安全（维护的不变量是什么）；能把 unsafe 封装进一个安全的函数/结构体，就不要让 unsafe 泄漏到上层调用方。
为什么： AI 倾向于在遇到生命周期或类型系统挑战时直接用 unsafe 强行转换（如 std::mem::transmute），注释一句"// 应该没问题"就提交了。这类代码的危险性在于它能编译、能通过测试，但在某个边界条件下触发未定义行为，且 Miri / sanitizer 很难覆盖到所有路径。
怎么做：
- 写
unsafe前先问：有没有std/bytemuck/zerocopy等安全 crate 能做这件事？ - 写了
unsafe→ 注释格式：// SAFETY: [解释为何此处满足 XX 的不变量，即...]。 - 用
miri（cargo miri test）定期跑，检测未定义行为；CI 里加cargo test --sanitize=address。
4. 用类型表达约束（枚举状态机、newtype），让非法状态不可表示
规则： 把业务约束编码进类型系统：用枚举而非字符串/整数常量表示状态；用 newtype 模式区分语义不同的同类型值；避免用 bool 参数区分行为——该拆成两个函数。
为什么： AI 常写出 fn send_email(address: String, verified: bool)，然后所有调用方都要记住"第二个参数是是否验证过"，极容易传反。更好的设计是 fn send_email(address: VerifiedEmail)——传入未验证的 String 在编译时就报错，根本不存在运行时检查的必要。这是 Rust 类型系统最强大的能力，AI 却经常忽视。
怎么做：
- 状态流转 → 枚举 +
impl方法，非法状态转换不提供方法（类型状态机模式）。 - 同类型但语义不同的值（用户 ID vs 文章 ID，都是
u64）→struct UserId(u64); struct PostId(u64);，杜绝混用。 - 函数有多个同类型参数 → 考虑 builder 模式或命名结构体，降低参数传反的风险。
5. 善用 Option/迭代器组合子；遵循 clippy 建议
规则： 处理 Option/Result 优先使用 map、and_then、unwrap_or_else、ok_or 等组合子，而非嵌套 match；所有代码通过 cargo clippy -- -D warnings（警告即错误）；cargo fmt 格式化。
为什么： AI 写 Option 处理时常退化成多层嵌套 match：match x { Some(v) => match v.get(...) { Some(r) => ..., None => ... }, None => ... }。这与 Rust 的迭代器哲学背道而驰，且可读性极差。clippy 中有数百条来自社区经验的建议，很多直接指出安全隐患（如使用了 ptr::null() 而非 ptr::null_mut()），忽视 clippy 等于放弃了免费的代码审查。
怎么做：
Option<T>链式变换 →opt.map(|v| ...).unwrap_or_default()。- 处理集合 → 用迭代器链（
.filter().map().collect()），避免显式for+push。 - CI 中：
cargo clippy -- -D warnings && cargo fmt --check，有报警就失败。
正例 / 反例
反例：靠 clone 绕过借用 + 库代码 unwrap
// 反例 — clone 掩盖设计问题，库函数直接 unwrap
use std::collections::HashMap;
pub fn get_display_name(users: &HashMap<u64, String>, id: u64) -> String {
let users_clone = users.clone(); // ❌ 为了"方便"克隆整个 map
users_clone.get(&id).unwrap().clone() // ❌ 库代码 unwrap，调用方无法处理缺失
}
// 正例 — 零克隆借用，错误用 Result 表达
use std::collections::HashMap;
#[derive(Debug, thiserror::Error)]
pub enum UserError {
#[error("用户 {0} 不存在")]
NotFound(u64),
}
pub fn get_display_name(
users: &HashMap<u64, String>,
id: u64,
) -> Result<&str, UserError> {
users
.get(&id)
.map(String::as_str)
.ok_or(UserError::NotFound(id)) // ✅ 调用方决定如何处理缺失
}
反例：bool 参数 + 裸字符串状态
// 反例 — bool 参数语义模糊，字符串状态无法穷举
fn process_order(order_id: u64, is_priority: bool, status: &str) {
if status == "pendign" { ... } // ❌ 拼写错误，编译器不报
}
process_order(42, true, "pending"); // ❌ true 是什么意思？
// 正例 — 枚举穷举状态，newtype 明确语义
#[derive(Debug)]
enum OrderStatus { Pending, Processing, Shipped, Cancelled }
struct OrderId(u64); // ✅ newtype，不会和其他 u64 混淆
fn process_order(id: OrderId, priority: Priority, status: OrderStatus) {
match status {
OrderStatus::Pending => { ... }
OrderStatus::Processing => { ... }
// 编译器强制穷举 ✅
}
}
自查清单
- 遇到 borrow checker 报错，是否先理解根因，而不是立刻加
.clone()或Rc？ - 库 crate 的公开函数中是否有
unwrap()/expect()调用？（应该没有） - 每个
unsafe块旁是否有// SAFETY:注释，说明维护的不变量？ - 是否用枚举/newtype 把业务约束编码进类型，让非法状态在编译时就不可表示？
-
Option/Result处理是否用组合子，而非多层嵌套match？ -
cargo clippy -- -D warnings和cargo fmt --check全部通过？ -
unsafe代码是否已用cargo miri test验证过？