rust-unsafe-boundaries

Rust 不安全边界

使用此技能，将不安全 Rust 隔离在小巧、有文档说明且可测试的边界内。只有当安全 API 无法以可接受的正确性和性能表达所需操作时，才可以使用不安全代码。

核心工作流

1. 先尝试安全的设计。检查标准 API、所有权重构、迭代器、同步原语和现有 crate。
2. 明确说明安全 Rust 无法证明的不变量。如果无法写清楚该不变量，暂时不要编写不安全代码。
3. 将不安全代码块控制得尽可能小。在代码块之前用安全代码完成运行时检查和准备工作。
4. 在每个不安全代码块的正前方添加 // SAFETY: 注释，说明其中每项不安全操作为何有效。
5. 只有当调用方必须满足额外条件时，才将函数标记为 unsafe fn。在 # Safety 部分中记录这些条件。
6. 启用或遵守 unsafe_op_in_unsafe_fn；不安全函数中的不安全操作仍应包在显式的不安全代码块中。
7. 测试正常行为、边界情况、panic 路径和销毁行为。项目支持时运行 Miri。

边界规则

添加或审核不安全代码前，请阅读 references/safety-invariants.md。

• 优先使用私有的不安全内部实现，并通过安全的公共包装器提供接口。
• 优先使用 MaybeUninit<T>，而不是已弃用或临时拼凑的未初始化内存模式。
• 除非已证明有效性、对齐、初始化、别名规则和生命周期均成立，否则绝不从原始指针创建引用。
• 除非已证明容量、初始化和所有权均成立，否则不要使用 set_len、指针运算或 from_raw_parts。
• 涉及部分初始化的值、手动销毁或长度变更时，明确处理 panic 安全性。
• 避免使用 static mut；优先使用 OnceLock、LazyLock、原子类型或加锁状态。

文档模式

/// # Safety
///
/// `ptr` must be non-null, aligned for `T`, initialized, and valid for reads
/// for the returned lifetime. No mutable reference may alias the same value.
pub unsafe fn read_ref<'a, T>(ptr: *const T) -> &'a T {
    // SAFETY: The caller guarantees `ptr` satisfies the documented contract.
    unsafe { &*ptr }
}

审核清单

• 每个不安全代码块都有就近的 SAFETY 说明。
• 每个 unsafe fn 或不安全 trait 都有 # Safety 契约。
• 公共安全 API 无法被用于破坏内部不变量。
• Drop、panic 和提前返回路径都能保留初始化状态和所有权。
• 测试或 Miri 覆盖危险边界，而不只是顺利执行的路径。