Rust 工具链
强制要求
TypeScript 与 Python 是 AI 辅助开发的默认语言。Rust 不是默认选项,仅当项目确实需要以下能力时才选择 Rust:
- 兼具内存安全和极致性能
- 系统级组件
- 供其他语言使用的原生扩展
- WebAssembly 目标
采用 Rust 必须给出明确理由、征得用户同意,并在项目 ADR 中记录这些内容。
熟悉 Rust 本身不构成采用理由。
适用范围
本文档是 Rust 项目的基线标准,不能替代项目级评估。采用 Rust 前须确认两点:需求属于上述场景之一,且 TypeScript、Python 或 Go 无法以合理成本满足。
版本策略
通过 mise 或 rustup 安装并使用 stable 工具链。
在 Cargo.toml 中使用 edition 2024。
默认不启用 nightly 特性;需要 nightly 时,必须将其作为明确决策记录在案。
使用规则
构建与打包
只使用 cargo 进行构建和打包。
不要将标准 cargo 命令封装在自定义构建脚本中。
格式化
使用 rustfmt 进行格式化。
通过 mise task 提供 cargo fmt。
Lint 工具
使用 cargo clippy 进行 Lint。
CI 必须将警告视为错误:
cargo clippy --all-targets -- -D warnings
unsafe 块
每个 unsafe 块必须附带 // SAFETY: 注释,说明使该代码块安全的不变量。
不要用 unsafe 绕过借用检查器。
错误处理
库中的错误类型使用 thiserror。
anyhow 只用于二进制边界;库的公开 API 不得暴露它。
工作区布局
多 crate 项目使用 cargo workspace。
依赖版本在工作区层面保持同步。
测试
CI 中运行 cargo test。