Rust Unsafe 代码规范：不安全块要小到能被审查
一、Unsafe 不是绕过 Rust，而是写下责任
Rust 的安全性来自类型系统和借用检查，但系统编程无法完全避免 unsafe。FFI、裸指针、手写内存布局、SIMD、无锁结构，都可能需要 unsafe。问题不在于用了 unsafe，而在于 unsafe 是否被限制、审查和证明。
不安全块应该小到能被审查。每一段 unsafe 都要说明前置条件、内存所有权、别名规则、生命周期和线程安全假设。否则它会变成 C 代码藏在 Rust 外衣里。
二、安全边界：把 unsafe 包在安全 API 后面
调用方不应该被迫理解内部裸指针。库作者负责把不变量守住，对外暴露安全接口。unsafe 的边界越清楚，系统越可维护。
三、代码示例：为裸指针写明条件
下面是一个简化示例，展示注释应该写什么。
rust
/// # Safety
/// `ptr` must be non-null, aligned, and valid for `len` elements.
/// The memory must not be mutated for the returned slice lifetime.
pub unsafe fn view<'a>(ptr: *const f32, len: usize) -> &'a [f32] {
std::slice::from_raw_parts(ptr, len)
}这段代码本身很短，但条件很重。调用者必须保证指针有效、对齐、生命周期正确。生产代码里，若能在外层校验 null、长度和边界，就不要把所有责任都甩给调用者。
四、工程边界：测试不能证明完全安全
unsafe 错误很多时候不会立刻崩溃。越界、悬垂指针、数据竞争，可能在特定优化级别或压力下才出现。测试很重要，但不能替代设计证明。建议使用 Miri、AddressSanitizer、ThreadSanitizer、fuzz 和代码审查组合。
取舍方面，unsafe 能换性能和底层控制，但每一处都增加审查成本。高层业务代码尽量不要出现 unsafe；性能热点可以集中到少数模块，由熟悉内存模型的人维护。Rust 的优势不是永远不写 unsafe，而是把 unsafe 控制在可见范围内。
还要避免"为了省一次 clone"就引入 unsafe。很多时候，安全实现已经足够快；真正需要 unsafe 的地方，应该有 benchmark 和瓶颈证据。没有证据的 unsafe，是给未来制造债务。
代码审查时，可以要求每个 unsafe 块回答三个问题：为什么 safe Rust 做不到，调用方必须满足什么条件，违反条件会造成什么后果。回答不清楚，就不应该合并。unsafe 文档不是形式，它是维护者之间的契约。
还要控制 unsafe 的扩散。底层模块可以有少量 unsafe，对外提供安全抽象；上层业务如果到处写裸指针，Rust 的安全收益就被消耗掉了。项目可以用 lint 或审查规则限制 unsafe 出现位置，让风险集中。
发布前还应跑一轮压力和模糊测试。unsafe 代码最怕边界输入，长度为 0、超大长度、未对齐地址、并发访问都要覆盖。测试不能证明绝对安全，但能把明显错误提前挡住。
生产落地补充：从能跑到可维护
从生产落地角度看，这类方案不能只停留在主流程。更关键的是把输入校验、失败分支、资源上限和回滚路径提前写清楚。主流程通常容易在演示环境里跑通，真正暴露问题的是异常输入、依赖抖动、并发放大和权限边界。一篇技术方案如果没有解释这些约束，读者很难判断它能否放进真实系统。
评估时建议先定义三类指标：正确性指标、稳定性指标和成本指标。正确性指标回答结果是否可信，稳定性指标回答失败时是否可控，成本指标回答持续运行是否划算。三类指标要同时进入验收清单，不能只用平均耗时或单次成功率证明方案有效。
实现层面还需要把观测数据留出来。日志至少包含请求标识、关键参数摘要、耗时、状态和错误类型；指标至少覆盖成功率、超时率、重试次数和队列长度；必要时再补 Trace 关联上下游调用。这样排查问题时不用靠猜，也能区分是代码逻辑、外部依赖还是容量配置导致的故障。
异常路径补充：把失败当成接口契约
下面的补充片段强调一个原则：调用方必须得到稳定、可解释的错误，而不是在超时、空输入或依赖失败时收到模糊结果。代码不追求覆盖所有业务细节，而是展示输入校验、超时控制和错误封装这三个生产系统最容易遗漏的环节。
rust
use std::time::Duration;
#[derive(Debug)]
enum RunError {
InvalidInput(String),
Timeout,
Upstream(String),
}
fn validate_request(input: &str) -> Result<(), RunError> {
if input.trim().is_empty() {
return Err(RunError::InvalidInput("输入不能为空".to_string()));
}
Ok(())
}
async fn run_with_guard(input: &str) -> Result<String, RunError> {
validate_request(input)?;
let task = async move {
// 真实项目中这里接入文件、网络或模型调用。
Ok::<String, RunError>(format!("accepted: {}", input))
};
tokio::time::timeout(Duration::from_secs(3), task)
.await
.map_err(|_| RunError::Timeout)?
.map_err(|err| RunError::Upstream(format!("执行失败: {:?}", err)))
}五、总结
Rust unsafe 代码规范的核心，是让不安全块小、条件清楚、边界明确、测试和审查到位。unsafe 是责任声明，不是逃离 Rust 安全模型的捷径。