rust-systems

Rust 系统与服务

涵盖现代应用层 Rust（edition 2024）：命令行工具、Web 服务、库。不包括 no_std／嵌入式开发。

工作规则

• 在库中保留错误变体，并在应用边界补充运行上下文。
• 写入替代内容前，区分配置缺失与文件不可读或无效的情况。
• 避免在异步工作线程上执行阻塞任务，限制队列和派生任务，并定义关闭行为。
• 将变更视为内部变更前，先追踪导出的接口；验证已安装运行时具备的能力。
• 不要在并发测试中修改进程级状态；实际运行二进制文件，并测试相关的功能组合。

不安全代码规范

• 默认不使用 unsafe。如果 clippy 标记了问题，不要用 #[allow] 忽略；应重构。下文的 #[expect] 例外不适用于此处；不安全代码问题应修复，而不是添加注解。
• 每个 unsafe 块上方都要添加 // SAFETY: 注释，说明各项不变量为何成立。没有注释 = 审核不通过。
• 尽量缩小 unsafe 块：在模块边界将其封装为安全抽象，并将模块标记为 pub(crate)。
• 对包含 unsafe 或原始指针运算的 crate 使用 miri（cargo +nightly miri test）；它能捕获被优化器掩盖的未定义行为。
• 对于零拷贝模式，优先使用 bytemuck、zerocopy、bytes，而不是手动编写 transmutes。
• 在 edition 2024 中，写入环境变量属于 unsafe。只能在 main 中、运行时启动或任何线程派生之前写入。 并发调用 getenv 会产生未定义行为；OnceLock 并不能使其安全。注意首次使用时延迟写入 LD_LIBRARY_PATH 一类变量的情况；应将其提前到启动阶段。

规范

• 简单优先：每项变更都应尽可能简单，尽量减少影响代码。
• 只修改必要内容；避免在 PR 中进行无关变更。
• 不要用 #[allow(clippy::...)] 走捷径；应修复根本问题。确实需要抑制时，改用 #[expect(clippy::lint_name, reason = "...")]：如果 lint 不再触发，expect 会发出警告，因此失去原有原因的抑制会自行报告，而 allow 则会永远悄然失效。（expect 需要 Rust 1.81+；edition 2024 已满足这一最低版本要求。）
• 添加 trait 或泛型前，先确认至少有 3 处会用到它。否则，具体类型会更清晰。
• bool::then_some(x) 会按值接收 x：无论布尔值如何，都会先计算参数。 因此，将条件与固定宽度切片组合成保护条件，会恰好在条件要检查的输入上触发 panic：(b.len() >= 19 && b[4] == b'-').then_some(&v[..19]) 会对任何更短的值触发 panic，使程序在本应报告结果未定的函数中以状态码 101 退出。应使用惰性求值的 then(|| …)。Clippy 不会标记这一区别。使用 grep 搜索 then_some(，检查参数是否包含索引、切片、unwrap 或分配操作。另请注意：固定宽度切片并不等于解析。&v[..19] 也会在非 ASCII 字符中间触发 panic；对两个这样的前缀进行字典序比较会丢弃时区偏移，因此 01:00+02:00 会排在 00:00Z 之后，尽管它实际早了 1 小时。应解析并规范化，或直接拒绝。

验证

• cargo fmt --all -- --check 通过，且差异为零
• cargo clippy --workspace --all-targets --all-features -- -D warnings 通过
• cargo nextest run --workspace（或 cargo test --workspace）通过，且失败数为零
• 使用 nextest 时，cargo test --doc --workspace 也必须通过；nextest 不会运行文档测试
• 对于任何将用于生产环境的 crate，cargo deny check 通过（许可证、公告、重复依赖项）
• 新增的 unsafe 均有 // SAFETY: 注释

特定任务参考

实现或审查相关行为前，请先阅读对应的参考文档：

• 对于 Cargo 配置、工作区变更、公共 API 可达性、构建配置或 CI：请参阅 toolchain-and-interfaces.md。
• 对于错误、所有权、解析边界、Tokio、关闭或并发：请参阅 ownership-and-execution.md。
• 对于 CLI/服务入口、生产环境韧性、遥测或测试：请参阅 applications-and-testing.md。

适用时，请参阅现有的专项参考文档：

• macros-and-os-boundaries.md。
• rustdoc.md。
• build-profiles.md。
• performance.md。
• cli-tools.md。
• production-resilience.md。
• axum-service.md。
• observability.md。
• ci-pipeline.md。